flowstate-shell Package Skill

Package: @epicdm/flowstate-shell Repository: epic-flowstate-community Path: packages/flowstate-shell 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

FlowState Shell Electron Adapter

Purpose

Use this skill when working with terminal sessions in an Electron renderer process.

Read First

• packages/flowstate-shell/src/adapters/ElectronAdapter.ts
• packages/flowstate-shell/tests/adapters/ElectronAdapter.test.ts
• Electron preload/main-process terminal bridge code in the consuming app

Runtime Contract

ElectronAdapter requires:

window.electronAPI.terminal

Expected methods:

• connect(sessionId)
• write(sessionId, data)
• disconnect(sessionId)
• resize(sessionId, cols, rows)
• onData(callback)
• onExit(callback)

Workflow

1. Call connect().
2. Adapter generates electron-<timestamp>-<random> session id.
3. Adapter registers data and exit listeners.
4. Adapter calls electronAPI.terminal.connect(sessionId).
5. Call onData(callback) to receive terminal output.
6. Call write(data) and resize(cols, rows) after connect.
7. Call disconnect() to notify main process and remove listeners.

Guardrails

• connect, write, disconnect, and resize throw outside Electron renderer.
• write and resize throw before connect.
• Incoming data and exit messages are filtered by session id.
• disconnect() with no session is a no-op.
• Exit events are delivered to the data callback as a process-exited message.

Verification

yarn workspace @epicdm/flowstate-shell test --runInBand tests/adapters/ElectronAdapter.test.ts

Package Skill Inventory

@epicdm/flowstate-shell Skill Inventory

Skill Set

Design Notes

This package should be taught by runtime environment: Electron renderer, browser WebSocket, and React provider. Shared UI components belong to shell-core; PTY server behavior belongs to shell-server.

Not Included

• No standalone skilllets for useTerminal.
• No shell-server PTY/session management details.
• No generated Dojo text reused directly.

Review Gate

@epicdm/flowstate-shell Skills Review

Verdict

Pass with tracked follow-ups.

The authored skills are source-backed and workflow-oriented. They cover shell client boundaries, Electron adapter, WebSocket adapter, provider behavior, and maintenance drift.

Coverage

• ElectronAdapter: covered from src/adapters/ElectronAdapter.ts and tests.
• WebSocketAdapter: covered from src/adapters/WebSocketAdapter.ts and tests.
• TerminalProvider/useTerminal: covered from src/components/TerminalProvider.tsx.
• Boundaries: covered from shell package exports and shell-core/server package relationships.
• Drift: covered from README legacy scope and generated Dojo artifacts.

Verification Results

LC_ALL=C rg -n "[^\\x00-\\x7F]" packages/flowstate-shell/.flowstate/skills
rg -n "^name:|^description:" packages/flowstate-shell/.flowstate/skills
yarn workspace @epicdm/flowstate-shell test
yarn workspace @epicdm/flowstate-shell typecheck
yarn workspace @epicdm/flowstate-shell build
yarn workspace @epicdm/flowstate-shell lint
yarn nx build @epicdm/flowstate-shell

Results:

• ASCII scan passed with no non-ASCII matches.
• Frontmatter scan found name and description on all five skills.
• typecheck passed.
• build passed and emitted root plus adapters/WebSocketAdapter CJS, ESM, sourcemap, and DTS outputs. Build reports existing package export-order warnings because types appears after import and require.
• test passed: 2 suites, 15 tests.
• lint passed with 36 existing warnings around Electron window.electronAPI any access and WebSocket JSON parsing.
• yarn nx build @epicdm/flowstate-shell passed and built @epicdm/flowstate-shell-core first. Nx Cloud reported the existing unconnected-workspace 401 warning.

Follow-Ups

• Fix README legacy package scope and license drift.
• Rebuild package-local Dojo content from these reviewed skills before publishing.
• Consider adjusting package export condition order so types is first.

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/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.