flowstate-shell-core Package Skill

Package: @epicdm/flowstate-shell-core Repository: epic-flowstate-community Path: packages/flowstate-shell-core Version: 1.0.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Shell Core Adapter Contracts

Status: Active Purpose: Keep terminal transport implementations compatible with Terminal and TerminalTabs. Scope: packages/flowstate-shell-core/src/adapters/ITerminalAdapter.ts Trigger: A task changes terminal IPC, WebSocket, mock, or custom adapter behavior. Input: Adapter source and the host transport protocol. Output: An adapter that satisfies shell-core component expectations.

Current Contract

export interface ITerminalAdapter {
  connect(): Promise<string>
  write(data: string): void
  onData(callback: (data: string) => void): void
  disconnect(): void
  resize?(cols: number, rows: number): void
}

connect() returns the session ID generated by the adapter/server. It does not receive a sessionId argument in current source.

Responsibilities

Adapter Review Checklist

• Does connect() match the current zero-argument signature?
• If backend output can arrive before connect() resolves, does the adapter buffer it until onData() is registered?
• Does onData() replace or register exactly the callback the component should use?
• Does disconnect() prevent later output from writing to an unmounted terminal?
• Does resize() tolerate repeated calls and dimensions from FitAddon?
• Are transport-specific details kept outside flowstate-shell-core?
• Do tests exercise both data delivery and cleanup?

Timing Invariant

Terminal awaits connect() before registering the xterm input handler and adapter output callback. Adapter implementations that subscribe to a backend stream during connect() should either delay stream forwarding or keep a small output buffer and flush it from onData(callback).

Known Caller Packages

• packages/flowstate-shell/src/adapters/ElectronAdapter.ts
• packages/flowstate-shell/src/adapters/WebSocketAdapter.ts
• packages/flowstate-shell/src/components/TerminalProvider.tsx

Use package-local flowstate-shell skills for adapter protocol specifics.

Verification

yarn workspace @epicdm/flowstate-shell-core test -- tests/adapters/MockAdapter.test.ts
yarn workspace @epicdm/flowstate-shell-core typecheck

Also run yarn workspace @epicdm/flowstate-shell test when editing real platform adapters.

Package Skill Inventory

Skill Inventory: @epicdm/flowstate-shell-core

Review date: 2026-06-30

Skill Map

Feature Coverage

Composition Notes

• Use package-local flowstate-shell skills when the task involves Electron IPC, WebSocket transport, TerminalProvider, or platform-specific adapter construction.
• Use this package for reusable UI contracts and xterm integration only.
• Do not publish generated .flowstate/dojo skilllets until they are rebuilt from these reviewed local skills.

Review Gate

Package Skill Review: @epicdm/flowstate-shell-core

Review date: 2026-06-30 Verdict: pass

Quality Gate

• Source-backed package purpose: pass.
• Public entry points documented: pass.
• Composable skill map: pass.
• Stale README/generator drift called out: pass.
• Dojo publish readiness: deferred until reviewed skills replace generated .flowstate/dojo content.

Evidence Checked

• package.json
• README.md
• src/index.ts
• src/adapters/ITerminalAdapter.ts
• src/components/Terminal.tsx
• src/components/TerminalTabs.tsx
• src/themes/terminalThemes.ts
• src/themes/useTerminalTheme.ts
• src/types.ts
• tests/adapters/MockAdapter.test.ts
• tests/components/Terminal.test.tsx
• tests/components/TerminalTabs.test.tsx
• .flowstate/feature-matrix/inventory.md
• .flowstate/dojo/agent-skillset.md

Verification Results

yarn workspace @epicdm/flowstate-shell-core test
yarn workspace @epicdm/flowstate-shell-core typecheck
yarn workspace @epicdm/flowstate-shell-core build
yarn workspace @epicdm/flowstate-shell-core lint
yarn nx build @epicdm/flowstate-shell-core

Results:

• ASCII/frontmatter check passed.
• test passed: 3 suites, 8 tests.
• typecheck passed.
• build passed.
• lint passed with 1 existing warning for a non-null assertion in src/themes/terminalThemes.ts.
• nx build passed and reported the existing Nx Cloud setup notice.

Dojo Status

Deferred. Existing generated Dojo artifacts should be rebuilt from these reviewed local skills before publication because current Dojo files only list exports and have ID/publisher drift.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-shell-core/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.