Workshop Client

@eys-55/workshop-client is the one-command Participant Client. It prepares a safe empty Participant Workspace and local Session Project, performs readiness and admission, opens the Participant Console, launches Claude Code, and supplies the local MCP executable. It refuses to initialize a non-empty unrecognized directory.

The published Client defaults to the hosted Production service at https://workshop-agent-arena.vercel.app. Operators of a separate self-hosted deployment can override only that origin with WORKSHOP_API_URL; Participants using the hosted product do not set an environment variable.

The canonical behavior lives in the Client and readiness contract. Current implementation/contract alignment questions are tracked in the implementation audit.

Commands

• join CODE --name "Display Name": the only normal Participant command.
• doctor: support-only readiness diagnosis.
• setup: support-only reusable setup repair.
• mcp: internal executable path used by Claude Code.

A support command cannot convert a failed native clean-machine journey into SM-01 evidence.

Executable flow

src/bin.ts
  -> src/cli.ts
  -> src/client-command.ts pure workflow
  -> src/node-runtime.ts hosted/local adapters
  -> src/node-workspace.ts durable local state and Session Project

The current normal sequence is:

initialize an empty Participant Workspace or recognize existing state
  -> preflight or recovery
  -> prepare and verify the signed Session Project transfer
  -> install and prove Claude Code, MCP, hooks, permissions, and sandbox
  -> browser pairing
  -> persist pending admission
  -> admit
  -> save durable identity
  -> connect, open the Participant Console, and launch the working session

Consult the canonical contract before changing observable ordering.

Preparation and admitted MCP

src/preparation-mcp.ts provides the normal pre-admission one-tool context surface. It is privacy-limited and bound to a preparation credential.

After admission, src/node-runtime.ts dynamically loads the bundled @twc/workshop-mcp/stdio server with exactly seven Participant tools. The two surfaces are not interchangeable.

Local workspace and state

src/node-workspace.ts owns:

• ignored, owner-restricted Workshop identity and pending-admission files;
• managed Claude instructions, MCP, hooks, permissions, and sandbox config;
• nested Session Project creation/recovery;
• authoritative project-bundle application and fast-forward-only sync;
• signed transfer verification before Git reads a bundle;
• digest-protected atomic managed-file updates;
• dirty-worktree, path, scope, archive, permission, and symlink defenses.

Pending admission is persisted under .workshop/pending/<CODE>.json. Durable Participant credentials are not the Join Code and are sent in headers, not request bodies.

A pending-outcome recovery can resume at admission and connection without repeating successful setup and pairing.

Source map

| Path | Owns | | ------------------------------ | --------------------------------------------------------------- | | src/bin.ts | Executable entrypoint | | src/cli.ts | Streams, command dispatch, exit handling | | src/client-command.ts | Readiness/admission workflow and stable result/error formatting | | src/node-runtime.ts | HTTP, browser, Claude Code, MCP, and bounded-response adapters | | src/node-workspace.ts | Managed files, ignored state, Session Project and Git safety | | src/preparation-mcp.ts | Pre-admission one-tool MCP | | src/version.ts | Embedded Client package version | | scripts/build-executable.mjs | Bundled executable build | | scripts/pack-smoke.mjs | Packed artifact install/behavior proof |

Authority and recovery

• Readiness failure creates no Participant and returns one exact repair action.
• Join Code is a Workshop locator, not a durable bearer credential.
• Rerunning join recovers the same authorized identity/Session Project.
• Credential-family rotation invalidates stale connections.
• Managed files and scopes fail closed on conflict or escape.
• The Client receives neither Facilitator authority nor canonical GitHub App credentials and the normal journey requires no manual Git.
• Outer preparation responses are capped at 64 MiB; the verified bundle inside that response is capped at 4 MiB by the shared MCP verifier.

Repository development uses Node 24 and npm 10.9.8. The published Client has a wider consumer contract—Node ^22.22.2 || ^24.15.0 and npm 10–12—and the Client/MCP executable bundles target Node 22. Consumption support does not change the monorepo toolchain.

Tests and package gates

npm test --workspace @eys-55/workshop-client -- test/cli.test.ts
npm test --workspace @eys-55/workshop-client -- test/client-command.test.ts
npm test --workspace @eys-55/workshop-client -- test/managed-files.test.ts
npm test --workspace @eys-55/workshop-client -- test/node-runtime.test.ts
npm test --workspace @eys-55/workshop-client
npm run typecheck --workspace @eys-55/workshop-client

src/preparation-mcp.ts currently lacks a direct Client-owned test. Do not mistake admitted MCP preparation tests for coverage of this implementation.

Run pack smoke only when executable/package contents, versioning, or embedded dependencies change:

npm run test:pack --workspace @eys-55/workshop-client

The compatibility matrix additionally requires an immutable package archive and full source SHA. It is a release gate, not the edit loop. See the development guide.

Registry release

The public Client is published by the manually dispatched Publish Workshop Client workflow on main. The npm package must trust exactly these GitHub publisher coordinates:

• organization or user: Eys-55;
• repository: twc-workshops;
• workflow filename: publish-workshop-client.yml;
• environment: npm-release; and
• allowed action: npm publish only.

The dispatcher supplies the exact source SHA, declared Client version, and intentional next or latest tag. The workflow rejects any mismatch, restores the repository with Node 24.18.0 and npm 10.9.8, runs the Client and certification release checks, packs one archive, then changes only the publish CLI to npm 11.18.0 for OIDC support. No long-lived npm write token is stored in GitHub.

The GitHub repository is private, so npm cannot issue public provenance for this package. The workflow disables provenance explicitly and verifies the published archive's SHA-1, integrity, and selected distribution tag against the locally packed metadata. A successful registry publication is Client artifact evidence only; it does not establish SM-01, HP-01, V1-DEPLOYED, or Workshop eligibility.