flowstate-shell-server Package Skill

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

Status: Active Purpose: Start and operate the shell server with the current auth model. Scope: packages/flowstate-shell-server/src/cli.ts, src/WebSocketServer.ts, and src/verify-jwt.ts Trigger: A task involves shell server startup, health checks, CLI flags, JWT public keys, or authentication failures. Input: Port, optional RSA public key path, and desired runtime mode. Output: Running server or correct auth diagnosis.

CLI Startup

flowstate-shell-server --port=3001 --jwt-public-key=/path/to/public.pem

Supported parser forms:

• --port=3001
• --port 3001
• --jwt-public-key=/path/to/public.pem
• --jwt-public-key /path/to/public.pem

The CLI also accepts --auth-token, but current WebSocket message authentication is implemented through jwtPublicKeyPath, not token comparison.

In container deployments, docker/agent-entrypoint.sh passes --jwt-public-key when JWT_PUBLIC_KEY_PATH exists and treats --auth-token as obsolete.

Programmatic Startup

import { ShellWebSocketServer } from '@epicdm/flowstate-shell-server'

const server = new ShellWebSocketServer({
  port: 3001,
  jwtPublicKeyPath: '/etc/flowstate/shell-jwt-public.pem',
})

await server.start()

Health Check

curl http://localhost:3001/health

Expected shape:

{
  "status": "ok",
  "uptime": 0,
  "sessions": 0,
  "clients": 0,
  "port": 3001,
  "version": "0.1.0"
}

Auth Model

When jwtPublicKeyPath is configured:

1. Server loads the RSA public key PEM and stores it base64-encoded.
2. Client must send { "type": "auth", "token": "<RS256 JWT>" }.
3. Server verifies JWT format, alg: RS256, signature, and exp.
4. On success, server sends { "type": "auth_response", "success": true }.
5. On failure, server sends failure response and closes the socket.
6. If no auth arrives within 10 seconds, server closes with auth timeout.

When no public key is configured, auth is disabled for dev mode and clients are pre-authenticated.

Gateway Versus Direct Auth

Some deployed clients may append a query-string token for gateway validation. That is not the same as direct ShellWebSocketServer auth. If a client connects directly to this package with jwtPublicKeyPath configured, it must still send the auth message after the WebSocket opens.

Verification

yarn workspace @epicdm/flowstate-shell-server test -- tests/WebSocketServer.test.ts tests/verify-jwt.test.ts
yarn workspace @epicdm/flowstate-shell-server typecheck

Run yarn workspace @epicdm/flowstate-shell-server build after CLI changes because bin points to dist/cli.js.

Package Skill Inventory

Skill Inventory: @epicdm/flowstate-shell-server

Review date: 2026-06-30

Skill Map

Feature Coverage

Composition Notes

• Use flowstate-shell-core skills for React terminal components and adapter contracts.
• Use flowstate-shell skills for browser/Electron/WebSocket client adapters.
• Use this package for the server runtime, tmux persistence, and protocol source of truth.

Review Gate

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

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 generated artifacts are rebuilt from reviewed skills.

Evidence Checked

• package.json
• README.md
• src/index.ts
• src/types.ts
• src/WebSocketServer.ts
• src/TerminalSessionManager.ts
• src/TmuxAdapter.ts
• src/SessionStore.ts
• src/cli.ts
• src/verify-jwt.ts
• tests/protocol.test.ts
• tests/WebSocketServer.test.ts
• tests/TerminalSessionManager.test.ts
• tests/TmuxAdapter.test.ts
• .flowstate/feature-matrix/inventory.md
• .flowstate/dojo/agent-skillset.md

Verification Results

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

Results:

• ASCII/frontmatter check passed.
• tmux -V passed: tmux 3.6a.
• test --runInBand passed: 6 suites, 74 tests. The run emitted an existing MaxListenersExceededWarning from repeated server lifecycle tests.
• typecheck passed.
• lint passed with 30 existing warnings across WebSocketServer.ts, cli.ts, and types.ts.
• build passed with the existing package export-order warning because types comes after import and require.
• nx build passed with the same export-order warning and existing Nx Cloud 401/unconnected workspace notice.

Dojo Status

Deferred. Existing generated Dojo artifacts should be rebuilt from these reviewed local skills before publication because current Dojo files list exports, include stale authToken examples, 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-server/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.