fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1483a4540696d186dd86fecdbef0511ed35de73c
agentic-dev/docs/work/epics/walking-skeleton/04-runner-app-protocol-clone-install/_story.md
Danijel Martinek 99180887f3 docs(work): decompose platform-retrofit and walking-skeleton epics 
platform-retrofit: 8 stories / 18 tasks (spec bundle into docs/product,
single-version release-please before deletions, demo feature removal,
web-next auth shell, optional cores, work-tree archive, library traces,
agent-doc rewrite). walking-skeleton: 11 stories / 28 tasks across
workspaces, discovery, core-runner-protocol, runner app, editor, and
the flagship connect-to-selection e2e; builds on platform-retrofit
(prose dependency note — cross-epic frontmatter unsupported).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
2026-07-12 12:28:51 +02:00

3.7 KiB
Raw Blame History

id, epic, title, type, status, feature, depends-on, blocks, created
id epic title type status feature depends-on blocks created
04-runner-app-protocol-clone-install walking-skeleton runner app — protocol server, clone stage, install stage technical-story todo runner
01-vite-kitchen-fixture
02-core-runner-protocol
05-runner-scan-and-preview-adapter
06-runner-provisioner-port
2026-07-12T10:24:14Z

Goal

Ship the first half of apps/runner: a WS server speaking @repo/core-runner-protocol (hello/ready handshake gated on the workspace-scoped auth token), then the clone stage (PAT via ephemeral credential helper, spec §6 verbatim) and the install stage (package-manager detection), each emitting staged progress and named error events, each proven by the protocol integration suite against a real spawned runner and a git daemon-served vite-kitchen.

Why

The runner ↔ repo-toolchain seam is one of the three risks this epic exists to burn down. Clone and install are where credentials touch disk and subprocesses — the credential-leak assertions (no PAT in URLs, argv, logs, or .git/config; spec §15) must grow up with the code, not after it. App-tier imperative code is expected here (PRD Implementation decisions); the protocol is the contract, so tests assert through the protocol and never against runner internals (PRD Testing decisions).

Done when

  • apps/runner exists; every inbound/outbound message is zod-parsed against core-runner-protocol; handshake rejects a bad/missing workspace-scoped token.
  • Clone stage delivers the PAT to git via an ephemeral credential helper (spec §6 mechanics verbatim); credential never appears in any log, process argv, or .git/config in the runner workspace — asserted by the integration suite.
  • Install stage detects the package manager and installs, streaming staged progress events.
  • Named error events for bad URL, bad token, and install failure (PRD user story 5).
  • Protocol integration suite (real spawned runner + git daemon-served fixture, real WS) passes in CI on ubuntu.
  • pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff all pass after each task.

In scope

  • apps/runner app scaffold (app-tier — no feature generator applies; template app conventions).
  • WS server + envelope parsing + hello/ready handshake + status/error emission.
  • Clone stage with ephemeral credential helper + leak assertions.
  • Install stage with package-manager detection + progress events.
  • Integration tests using core-testing's git-serving helpers (story 01).

Out of scope

  • Scan + preview adapter + agent script (story 05).
  • Provisioning of the runner (story 06) — tests spawn it directly.
  • Watch/HMR, perf budgets (discovery-and-library); Next.js adapter (preview-and-nextjs-depth).
  • Local runner / CLI agent (local-runner-cli).

Tasks

  • Scaffold apps/runner: WS server speaking @repo/core-runner-protocol (every message zod-parsed), hello/ready handshake gated on the workspace-scoped auth token, status/error event emission; integration test spawns the real runner and completes the handshake over real WS.
  • Add the clone stage: git clone of the requested repo with the PAT delivered via an ephemeral credential helper (spec §6 verbatim — never in URLs, argv, logs, or .git/config), staged progress events; integration test clones the git daemon-served vite-kitchen, asserts credential-leak absence (grep argv/logs/.git/config), and asserts named failure events for bad URL / bad token.
  • Add the install stage: package-manager detection + install with staged progress events; integration test asserts install completes on the fixture and a named failure event is emitted on install error.