mirror of
https://github.com/garrytan/gstack.git
synced 2026-08-22 22:17:16 +02:00
* fix(ci): skill-docs freshness gate covers all 10 hosts and can actually fail The Codex/Factory gates ran 'git diff --exit-code -- .agents/' / '-- .factory/', but both paths are gitignored (.gitignore:16-17) — git diff on ignored untracked paths is always empty, so those two gates were structurally incapable of failing and 7 of 10 hosts had no gate at all. New shape: one 'gen:skill-docs --host all' pass (the generator hard-fails on any per-host error, gating all 10 hosts on generates-cleanly), byte-freshness via git diff for tracked output, plus a porcelain check that fails on untracked generated strays (git diff can't see brand-new files). The gitignored-hosts byte-freshness limitation is documented in the workflow comment. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): exorcise the sidebar-agent ghost from the test suite browse/src/sidebar-agent.ts was deleted in the v1.14 sidebar refactor, but the test suite kept testing it for 48 versions. Nothing noticed because the free suite runs in no CI job and Bun-era module-load errors were suppressed in the Windows shard runner via an exclusion pattern whose own comment documented the breakage ('broken on every platform since v1.14 ... exit 0'). - Delete sidebar-security.test.ts + security-source-contracts.test.ts: crashed at module load (unguarded readFileSync of the deleted file); per-assertion triage confirmed every SERVER_SRC pin targeted the deleted chat prompt builder (zero hits in today's server.ts) — nothing to port. - Delete sidebar-integration.test.ts: 11 of 13 tests exercised deleted endpoints (/sidebar-command queue, /sidebar-agent/event, chat buffer); the 2 passing tests pinned only the blanket auth gate, covered by server-auth.test.ts + dual-listener.test.ts. - Delete test/skill-e2e-sidebar.test.ts: E2E for the deleted queue flow. - sidebar-ux.test.ts 1,669 -> 830 lines: 20 dead-chat describes + 15 dead tests removed (incl. 10 vacuous passes asserting on empty indexOf slices); 2 stale pins on LIVE features fixed (content.js typed-catch CSSOM fallback, arrow-hint window widened). 95 pass / 0 fail. - sidebar-tabs.test.ts: both failures were stale pins, not regressions — forceRestart's deliberate ws.close(4001) and the terminal-agent spawn that moved into spawnTerminalAgent() (identity-based kill refactor). 28 pass. - touchfiles.ts: drop the three sidebar E2E entries from BOTH maps (E2E_TOUCHFILES + E2E_TIERS) — they pointed diff-selection at the deleted file, so those tests were unreachable by any diff. - test-free-shards.ts: remove the now-dead sidebar-agent exclusion pattern. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(ci): run the free test suite in CI (it ran nowhere) The full free suite (bun test: browse/test/ + test/ + make-pdf/test/) had no CI job on any Linux/macOS runner — only Windows curated shards, paid evals, and doc-freshness gates existed. That's how two module-load-crashing test files survived 48 versions. Same cached Dockerfile.ci image and container wiring as evals.yml (deps restore, build, Chromium verify). Includes a module-load-error guard: older Bun reported test-file import crashes with exit 0 on macOS/Linux, so the job also fails on any nonzero 'N errors' count in the summary — future crash-class regressions can't hide from the exact job built to catch them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(test): validate touchfile dependency paths exist on disk New guard in touchfiles.test.ts: every non-glob dep path must exist, and every glob's anchor directory must exist. This is the axis the 181-key two-map sync discipline never covered — an entry can point at a long-deleted file and diff-based selection then silently never triggers those tests (the sidebar trio sat rotted for 48 versions). First run immediately caught a fourth rotted entry: 'spec authored quality' referenced test/fixtures/spec/** (directory does not exist) and selected for a judge test that exists nowhere in the repo. Removed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): remove deleted /sidebar-chat endpoint from tunnel allowlist TUNNEL_PATHS is the audited tunnel attack surface — its own comment says every addition widens it. '/sidebar-chat' stayed in the set after the endpoint was deleted with the chat-queue path, meaning any future route matching that path would have been silently tunnel-exposed. The set is now exactly the pair ceremony (/connect) and the scoped command endpoint (/command), and the dual-listener closed-set pin enforces that. Also repairs a pre-existing red pin in dual-listener.test.ts: v1.63.0.0 made the tunnel allowlist args-aware (canDispatchOverTunnel gained a second param) without updating the test — red on main since then, invisible because the free suite had no CI job. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): delete chain's shadow dispatcher that skipped every security gate meta-commands.ts carried a 'CLI mode' fallback that re-implemented command routing without the server pipeline's gates: no scope check, no domain check, no tab ownership, no rate limit, no hidden-element stripping, no scoped-token enveloping — and it called handleReadCommand without a BrowserManager, which also skipped the JS-origin cookie-exfiltration assertion. It was unreachable in production (server.ts always passes executeCommand) and one boolean away from being live. chain now hard-errors without a server context. handleReadCommand's bm param is required and assertJsOriginAllowed runs unconditionally. The chain tests that exercised the deleted fallback now route through a server-shaped executeCommand adapter (real handlers + trust wrapping + {status,result} envelope), so their behavioral coverage — sequencing, trust markers, pipe format, aliases, error reporting — survives on the production-shaped path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(extension): delete the dead chat-queue client surface The sidebar-command handler in background.js POSTed to a server endpoint that no longer exists (deleted with the chat queue) — ~35 lines of fully-wired dead code including error handling for the permanent 404, plus its allowlist entry. No sender in the extension ever emitted the message type. chatEnabled leaves the /health contract (server hardcoded false, background.js re-derived it, nothing consumed it — the chat input element it guarded is gone from sidepanel.html). BROWSE_SIDEBAR_CHAT env flag had zero readers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): delete dead exports the ripped chat path left behind Three-way split by importer class: (a) Zero importers, deleted: the whole attack-attempt logging cluster in security.ts (logAttempt, AttemptRecord, salted hashPayload + device-salt, attempts.jsonl rotation, telemetry spawn plumbing incl. buildTelemetrySpawnCommand/resolveBashBinary — the LIVE attempts.jsonl writer is tunnel-denial-log.ts with its own rotation); the decision-file handshake (writeDecision/readDecision/clearDecision/excerptForReview — written for sidebar-agent's poll loop, which no longer exists); sidebar-utils.ts (whole module — its sanitizeExtensionUrl 'sanitized before embedding in a prompt' for the deleted prompt builder); 8 dead server.ts imports (sanitizeExtensionUrl, generateCanary, injectCanary, writeDecision, rotateRoot, serializeRegistry, restoreRegistry, clearAgentRecord); buildPtyClearCookie + buildSseClearCookie; WEBDRIVER_MASK_SCRIPT (orphaned by the D7 stealth narrowing — applyStealth never used it). (b) Dead-pin tests edited with their exports: the 'still exported' pin in stealth-layer-c, the string-content describe in stealth-webdriver (its live applyStealth behavioral coverage untouched), the clear-cookie assertions, security-review-flow.test.ts deleted whole (all 4 describes exercised the dead decision mechanism, incl. a 'simulated sidebar-agent poll loop'). (c) KEPT deliberately: leaseCount (live behavioral coverage), extractPtyCookie + validatePtySessionToken (extractPtyCookie is adopted by the terminal-agent cookie-parse unification later in this wave), resetSessionMarker + clearContentFilters (test-support API for the live content-security layer). Also fixes two pre-existing red pins found while here, invisible until the free suite got a CI job: the v1.44 spawnClaude->maybeSpawnPty rename in terminal-agent.test.ts, and a cross-file test-isolation bug where content-security.test.ts's clearContentFilters() wiped the auto-registered url-blocklist filter for every later file in the same bun process (security-integration.test.ts failed on co-run; afterAll now restores it). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): delete the dead ML layers — transcript classifier and DeBERTa ensemble The L4b Haiku transcript classifier and the opt-in DeBERTa ensemble (GSTACK_SECURITY_ENSEMBLE=deberta, a documented 721MB download) had ZERO production callers since the chat-path agent that invoked them was ripped. The only live ML path is scanPageContent (testsavant) inside the security sidecar subprocess. Deleted by import graph: - security-classifier.ts 614 -> 265 lines: HAIKU_MODEL, checkTranscript, shouldRunTranscriptCheck, loadDeberta, scanPageContentDeberta, ToolCallInput, all DEBERTA_* consts + load state. Header now states the live truth (imported only by security-sidecar-entry.ts). downloadFile kept, name intact — it is an enumerated egress sink (HF model download). - security-bunnative.ts + test: a research skeleton self-described as 'NOT a production replacement', shipped into src/ with zero importers. - security-bench-ensemble{,-live}.test.ts + the Haiku response fixture: a paid live-model benchmark for a layer that could not fire. The security-classifier-tdz test's only case exercised checkTranscript — gone. - security.ts: layer-model header rewritten to the live architecture; StatusDetail.layers -> {testsavant, canary}; getStatus() no longer requires the impossible transcript==='ok' for 'protected' (old on-disk session state with a transcript key is tolerated on read, never re-emitted). - security-sidecar-entry.ts needed zero changes: it serializes getClassifierStatus() verbatim and no consumer read .transcript (verified in sidecar-client + server.ts). - BROWSER.md security section matches reality (ensemble knob gone, 112MB not 22MB, sidecar hosting documented). combineVerdict/THRESHOLDS retained as the pure, tested combiner of record — comments now flag transcript/deberta votes as producer-less. Net: 26 pass in security.test.ts incl. a NEW regression test for stale- transcript disk tolerance; egress-receipt tripwire green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: scrub the sidebar-agent ghost from comments and CLAUDE.md 20+ comments across 10 files still described the deleted sidebar-agent.ts as a live process — including load-bearing architecture claims ('IMPORTED ONLY BY sidebar-agent.ts', 'sidebar-agent fills this in on first prompt-injection load', 'kill sidebar-agent' in shutdown docs) and ~60 lines of tombstone blocks in server.ts enumerating deleted identifiers by name (a false grep surface: searching processAgentEvent hit server.ts and looked live). CLAUDE.md's security-stack section now documents the LIVE architecture: L1-L3 content filters + testsavant via the security sidecar subprocess; the L4b/ensemble rows, the GSTACK_SECURITY_ENSEMBLE knob, and the 721MB DeBERTa download are gone (deleted as dead code this wave) with an explicit do-not-re-document note; attempts.jsonl is correctly attributed to tunnel-denial-log.ts; the no-live-writer status of classifierStatus is stated. Comments that survive now describe what IS, not what WAS: the promotion gate in domain-skills.ts explains why classifier_score>0 is load-bearing given no L4 load-time scan exists; file-permissions.ts names real sensitive files. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): delete the codex-helpers shadow module gen-skill-docs.ts imported externalSkillName (unaliased) from resolvers/codex-helpers.ts at line 21 and then re-declared the same function locally — the import was silently shadowed, and the imported copy was the STALE one (it lacked the frontmatterName param the local copy grew). Three more functions were byte-identical duplicates, imported only under _-prefixed aliases to keep the module 'referenced', and transformFrontmatter was a superseded hardcoded-Codex variant. Nothing else imported the module. Also drops three dead top-of-file imports (COMMAND_DESCRIPTIONS, SNAPSHOT_FLAGS — which pulled the whole browse/src module graph into every generator run for nothing — and an unused review-resolver trio). Proof: bun run gen:skill-docs exits 0 with a byte-identical tree (zero-diff regen); gen-skill-docs.test.ts 405/405 green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(server): delete ServerConfig.idleTimeoutMs + chromiumProfile — documented, never read Both fields carried JSDoc asserting embedder behavior that did not exist: the idle check reads the module-level IDLE_TIMEOUT_MS env constant, and both resolveChromiumProfile() call sites pass no argument. Worse than absent — an embedder passing idleTimeoutMs: 5000 silently got 30 minutes. Wiring them honestly is impossible today: the idle timer, activity state, and shutdown target are module-global, so a per-factory value would lie for any process running more than one handler. Deleted instead, with a ServerConfig note pointing at the deferred singleton/route-table refactor where real support belongs. BROWSE_IDLE_TIMEOUT and CHROMIUM_PROFILE env remain the honest knobs. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): wire appendSecureFile at the four real log-append sites file-permissions.ts carries a 24-line rationale for why POSIX mode bits are insufficient on Windows and implements appendSecureFile (0600 at create, Windows ACL on first write only) — but its single caller was the dead logAttempt, while the four REAL page-content log writers (console/network/ dialog logs in server.ts, the command audit log) used raw fs.appendFileSync with no mode. Page-content-derived logs now get owner-only permissions from birth on every platform. Verified before wiring: mode applies atomically at create via appendFileSync {mode}, and the ACL pass runs only on first write — no per-append subprocess cost on the hot console-log path. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(stealth): handoff() uses the shared profile resolution + lock cleanup The headless-to-headed handoff path hardcoded ~/.gstack/chromium-profile, silently ignoring $CHROMIUM_PROFILE and $GSTACK_HOME (gbrowser's gbd sets per-workspace profiles), and skipped cleanSingletonLocks() — so a handoff into a profile with a stale SingletonLock could hang where launchHeaded() would have recovered. This was the third live drift between the three Chromium launch paths; the first two are documented in comments as shipped stealth regressions. Minimal targeted fix — the full buildLaunchConfig() extraction stays in the deferred queue. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): resolver registry describes the template language again Seven registered {{PLACEHOLDER}}s had zero uses in any .tmpl (checked in both bare and :arg forms): REDACT_TAXONOMY_TABLE, TEST_COVERAGE_AUDIT_REVIEW, MODEL_OVERLAY, QUESTION_PREFERENCE_CHECK, QUESTION_LOG, INLINE_TUNE_FEEDBACK, MAKE_PDF_SETUP. The last two of those families are invoked programmatically by preamble.ts (functions kept, registry entries dropped); the question-tuning trio and the review coverage-audit wrapper were documented by their own module as existing 'for unit testing' that no test performed — deleted, along with generateRedactTaxonomyTable + its EXAMPLE/TIER_BLURB constants (its '/cso renders the full table' comment was itself stale) and its test describe. Also deletes the gated-resolver mechanism (ResolverEntry/appliesTo/ unwrapResolver + test/resolver-entry.test.ts): fully built, fully tested, used by zero of the 65 registry entries — the generator loop simplifies to a direct function call. CLAUDE.md's redact-doc line stops advertising the dead token. Proof: zero-diff regen (0 SKILL.md changed); gen-skill-docs + skill-validation 737 tests green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): wire boundaryInstruction from host config; drop three no-op binDir ternaries hosts/codex.ts declared boundaryInstruction and nothing read it — review.ts kept its own byte-identical CODEX_BOUNDARY literal (verified equal + trailing escaped newlines). The resolver now reads the config, so the boundary has one owner. (autoplan's template carries deliberately generic variants, enforced by gen-skill-docs.test.ts:1358 — untouched by design.) The 'ctx.host === codex ? $GSTACK_BIN : ctx.paths.binDir' ternary appeared in three resolvers and could never change the result: resolvers/types.ts already sets binDir to $GSTACK_BIN for every usesEnvVars host including codex. Proof: zero-diff regen for claude AND codex hosts; gen-skill-docs + host-config suites green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test-infra): judge uses resolveClaudeBinary; eval:watch reads the real partials dir judgePtyState spawned the bare string 'claude' three definitions below the resolveClaudeBinary() helper this same file exports — broken under hermetic PATHs where every other launch in the file resolves correctly. eval:watch read _partial-e2e.json from the legacy global ~/.gstack-dev/evals/ while EvalCollector writes it into the per-project eval dir (or GSTACK_EVAL_DIR) — so the dashboard's completed-tests panel was empty whenever slug detection succeeded, i.e. the normal case. The heartbeat and per-run progress logs stay global by design (session-runner.ts: 'heartbeat stays global'). The three eval-CLI docstrings stop claiming the legacy dir is the primary location. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): delete the superseded SDK ship-idempotency suite and three orphaned fixtures test/skill-e2e-ship-idempotency.test.ts's own header documented that the monolith's SDK-harness version tests a synthetic prompt while it exercises the real /ship skill — the author knew the old suite was superseded and left both running, two paid LLM runs for one behavior. The weaker copy is gone; its 'ship-idempotency' diff-selection key goes with it (the dedicated file is periodic-tier, which always runs under EVALS_ALL — the key had no remaining consumer). Fixture rot: test/fixtures/golden-ship-claude.md was a 128KB zero-reader orphan that had drifted 46KB from its live successor (test/fixtures/golden/claude-ship-SKILL.md) while looking authoritative; parity-baseline-v1.46.0.0.json and v1.53.0.0.json had zero readers (three tests pin three OTHER baseline versions — consolidation is queued, deletion of the unreferenced two is free). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(bin): delete zero-caller scripts; make host-config-export's docstring honest - bin/gstack-open-url (14 lines): announced in a CHANGELOG entry, wired into nothing, ever. bin/gstack-platform-detect (27 lines): zero callers, and its hand-rolled host list was already stale (SLATE_HOST.md cites it as a problem). Note: the deprecated gstack-brain-consumer/reader pair the audit flagged was already deleted upstream in v1.63 with a stay-deleted tripwire. - scripts/task-emission-schema.ts (61 lines): a typed schema module nothing imported; the tasks-section comment now documents the JSONL fields inline. - scripts/host-config-export.ts claimed to be the 'shell bridge for the bash setup script' — setup never calls it (its hand-rolled host lists drifting is a known follow-up). Docstring now states what it IS: a standalone, test-pinned query CLI not yet wired into setup. Its validateValue + CLI_REGEX/PATH_REGEX internals were dead (defined for a guarantee the header claimed but nothing enforced). - KEPT deliberately: scripts/preflight-agent-sdk.ts — a documented manual diagnostic (CONTRIBUTING.md + USING_GBRAIN_WITH_GSTACK.md reference it). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(server): one lone-surrogate sanitizer, one sanitizeReplacer, one startTunnel Three copies of the surrogate sanitizer existed with two algorithms (sanitize.ts regex vs a hand-rolled charCodeAt walk in server.ts — verified byte-identical across 11 edge cases before converging) plus two identical sanitizeReplacer definitions each wrapping a different copy. sanitize.ts is now the single source of truth; the runs-INSIDE-JSON.stringify egress invariant is unchanged at every call site and its pin tests were adapted to the new import shape without losing intent. The ngrok tunnel-start sequence existed three times in server.ts — the /tunnel/start route and the BROWSE_TUNNEL=1 autostart were line-for-line equivalent (a comment admitted 'Same cleanup as /tunnel/start's error path'). One startTunnel() now owns the ephemeral loopback bind, the pre-send egress receipt, the state-file RMW via tmpStatePath(), and the ordered error-path cleanup; callers keep their distinct response surfaces. The BROWSE_TUNNEL_LOCAL_ONLY test path shares nothing (no ngrok, different state field) and deliberately stays separate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): one session-cookie registry implementation, two instances pty-session-cookie.ts and sse-session-cookie.ts were byte-identical modulo the cookie name — mint/validate/parse/prune/TTL, the exact code a security fix would have to land in twice (and a third hand-rolled cookie parse in terminal-agent.ts had already diverged; unified next commit). createSessionCookieStore() owns the implementation; both modules become thin instantiations keeping every exported name, their distinct threat-model docstrings, and separate token spaces (an SSE-read cookie must never grant PTY access). pty-session-lease.ts deliberately stays out — different contract (sessionId/secret split, refresh, env TTL). The factory imports nothing from token-registry (cookie-picker-auth-isolation invariant, still pinned by sse-session-cookie.test.ts). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(security): terminal-agent uses the shared PTY cookie parser The /ws upgrade's cookie fallback hand-parsed the Cookie header inline — the fourth copy of the session-cookie parse, and the one that had already diverged from the others. Parsing now goes through extractPtyCookie; validation deliberately stays against the agent's own in-process validTokens map (the server's registry lives in a different process). The ws-handler pin test now pins the shared-parser call instead of the raw cookie-name literal. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor(hosts): defineHost() factory — 10 copy-paste host files become declarations hosts/*.ts were ten copies of one file: runtimeRoot byte-identical in 9/10, pathRewrites mechanically derivable from the host name for 7/10, the 11-entry toolRewrites map byte-identical between openclaw and gbrain, and every asset change a 10-file edit (cursor and slate had already fallen out of three other hand-maintained lists). defineHost() owns the defaults; each host file now declares only what makes it different (slate/cursor: 8 lines each). Shared constants: CROSS_MODEL_RESOLVERS, GBRAIN_RESOLVERS, EXEC_STYLE_TOOL_REWRITES. Genuinely-different things stayed explicit: codex/factory $GSTACK_ROOT rewrites, hermes's tool vocabulary, claude's denylist+prefixable install, opencode's wider runtimeRoot. Proof: JSON.stringify(ALL_HOST_CONFIGS) dump-diff before/after EMPTY (and a runtime walk confirmed no function-valued or undefined-keyed fields, so the JSON diff is complete); gen:skill-docs --host all zero-diff; host-config + gen-skill-docs + idempotency suites 485/485. Host files 595 -> 285 lines. docs/ADDING_A_HOST.md teaches the factory pattern. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(lib): fs-atomic — one atomic-write implementation, with the race actually fixed Atomic tmp-write-then-rename was reimplemented ~20 times across lib/, bin/, and browse/src with three tmp-suffix conventions. One of them was a latent bug this commit closes: lib/worktree.ts used a bare '.tmp' suffix — the deterministic-tmp collision race browse/src/server.ts documents having hit in production (its fix, pid+random, was trapped in a comment at one site). lib/fs-atomic.ts: atomicWriteSync (always throws, best-effort tmp cleanup, pid+random suffix, optional mode applied at tmp creation so the file never exists with looser permissions) + atomicWriteQuiet (shutdown paths only). Unit tests pin the throw/quiet contracts, 0600 mode, tmp-name uniqueness (captured via the read-only-dir failure path — Bun's fs exports are readonly, no monkeypatching), and no-stray-tmp cleanup. Migrated: lib/worktree.ts (the bare-.tmp bug), lib/gstack-decision.ts (snapshot + compact log), lib/gbrain-local-status.ts (probe cache). browse sites follow separately. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(lib): jsonl-store's docstring stops lying; mode option added; lib bypasses adopted The header claimed 'single source of truth... the ONLY copy' with write-time injection REJECTION — while appendJsonl never screened anything, only 1 of ~10 JSONL stores imported it, and a bypass appender lived in the same directory. Now: the contract is explicit (screening is the CALLER's job via hasInjection/firstInjectionMatch; the enforcing callers are named), a option applies 0600 at create for sensitive stores, and the lib bypasses are adopted (gstack-memory-helpers ×2, redact-audit-log — which keeps its chmod backstop for files created looser by pre-mode versions). browse/src keeps its own appenders by design (compiled-binary surface, own secure-append helper) and the header now says so. gstack-decision's batched archive append stays deliberate (single-write crash-window semantics appendJsonl's one-record contract can't express). New pins: 0600-at-create, and a test that documents appendJsonl does NOT self-screen — so nobody can re-document it as self-screening without making it true. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(browse): migrate hand-rolled atomic writes to lib/fs-atomic Seven sites, each audited for its existing throw-vs-swallow contract before migrating: writeSessionState + the four fire-and-forget tab/state writers use atomicWriteQuiet (they swallowed before); writeAgentRecord + the boot-time port-file write use atomicWriteSync (they threw before — and writeAgentRecord previously leaked its tmp file on rename failure, which the helper cleans). All carry {mode: 0o600} plus restrictFilePermissions after successful writes, preserving the Windows ACL hardening that writeSecureFile provided (mode bits are POSIX-only). server.ts untouched: its three state writes route through tmpStatePath(), pinned by server-tmp-state-path.test.ts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(hosts): delete five dead HostConfig fields metadataFormat (generator hardcodes openai.yaml), sidecar (behavior lives in setup's create_agents_sidecar — knowledge preserved as a comment in codex.ts), install.prefixable (skill_prefix is implemented entirely in bin/gstack-config), staticFiles (docstring cited a SOUL.md that never existed anywhere), and adapter (its only would-be consumer, openclaw-adapter.ts, was fully dead — with a test asserting the field was undefined). Kept: learningsMode (wired next), linkingStrategy (validation reads it), coAuthorTrailer (consumed by resolvers/utility.ts). Proof: JSON dump diff shows ONLY the deleted keys vanishing; zero-diff regen across all 10 hosts; host-config + gen-skill-docs suites green. Note: this commit also carries chunk-23 edits to the shared hosts/claude.ts + define-host.ts + host-config.test.ts files (skipSkills collapse, stale line-number comment drops) — pathspec commits, concurrent prep. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): preamble tiers are explicit; silent ?? 4 default becomes an error; spec stops rendering its preamble twice Eight skills (scrape, diagram, spec, skillify, pair-agent, landing-report, open-gstack-browser + its connect-chrome symlink) silently received the HEAVIEST tier-4 preamble because a missing frontmatter field defaulted to 4. Tiers are now declared in every {{PREAMBLE}} template's frontmatter and a missing declaration throws at generation time with the template path (the 5 templates without {{PREAMBLE}} never invoke the resolver). The stale hand-written tier-map comment (wrong in 3 of 4 rows) is gone. Bonus bug fixed: spec/SKILL.md.tmpl mentioned {{PREAMBLE}} in prose, so the generator inlined the ENTIRE preamble a second time — spec/SKILL.md shrinks 127,462 -> 80,924 bytes (-46,538) from de-duplication alone. skill-size-budget gains a reasoned INTENTIONAL_SHRINKS entry (its frozen baseline had measured the doubled-preamble bug). New tests: missing-tier throw carries the path; every {{PREAMBLE}} template declares a tier. (Carries chunk-23 edits in the shared test/gen-skill-docs.test.ts.) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): learningsMode is read from host config, not a hardcoded host name resolvers/learnings.ts branched on ctx.host === 'codex' while every host declared learningsMode — the field was decorative, and the 7 hosts configured 'basic' (cursor, slate, kiro, opencode, openclaw, hermes, gbrain) silently received the 'full' cross-project flow their runtimes can't execute (it depends on AskUserQuestion + gstack-config plumbing). Output now matches declaration: basic hosts get the project-scoped search block. Blast radius proof: all committed Claude SKILL.md files and the three golden fixtures are byte-identical; the behavior diff lands only in the gitignored external-host trees (hand-verified: .cursor review's learnings section swaps the cross-project AskUserQuestion block for the project-scoped search). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(gen): small config scrubs — openclaw blobs to real files, setup host drift, dead artifacts - The three openclaw markdown blobs hardcoded inside gen-skill-docs.ts (which silently reverted any hand edit to their tracked outputs on regen) move to openclaw/templates/*.md source files; output shasums byte-identical. - setup's --host allowlists gain cursor + slate — both fully registered hosts with generated output, but './setup --host cursor' exited 1 because two hand-rolled lists in setup had drifted from hosts/index.ts. - scripts/proactive-suggestions.json deleted: 31KB regenerated on every run, read by nobody (the catalog-trim design's reader was never built); its emitter and three determinism tests (which guaranteed a file nothing reads didn't churn) retired with stays-retired pins. - claude/SKILL.md.tmpl deleted: a complete 8.9KB skill that never generated output (directory name collides with the host id 'claude'), in no registry. Recoverable from git if ever wanted under a non-colliding name. - openclaw's frozen extraFields.version '0.15.2.0' stamp dropped; includeSkills: [] no-ops omitted (the generator treats [] as absent); llms.txt 55 -> 54 skills. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(gen): correct preamble tiers for the 8 silently-heaviest skills With tiers now explicit, set them RIGHT by analogy to the tiered population: scrape/diagram/open-gstack-browser (+ the connect-chrome symlink) -> tier 1 (launchers and artifact generators, like browse and make-pdf); landing-report/pair-agent/skillify -> tier 2 (dashboards and session tools, like health and canary); spec -> tier 3 (interactive planning, like the plan-*-review family). Each tier-1 skill sheds 271 lines of onboarding prose it never needed; tier-2 shed 20 each. Verification per the review protocol: regen diff reviewed (pure section-removal), skill-validation + size-budget + catalog-budget + v0-dormancy suites green (822 tests), and live smoke of the tier-corrected skills confirms the preamble renders the intended sections at each tier. These skills have ~no eval coverage — stated honestly; the wave's gate-tier eval run is the backstop. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(test): e2e-gate — one tier-gate implementation, side-effect-free, with the trap pinned The EVALS/EVALS_TIER gate was copy-pasted into ~40 test files and had drifted into six different predicates — the drift that made 'eval:bg:all runs everything' silently false. test/helpers/e2e-gate.ts owns the semantics now: describeE2ETier(tier) + e2eTierEnabled(tier), env read at call time, zero side effects (the existing e2e-helpers module runs a ~30s claude ping at import under EVALS=1, so the gate lives in its own module; purity is pinned by tests that scan imports and comment-stripped source). The unit matrix pins all four env combos — including EVALS=1 with EVALS_TIER unset -> SKIP, the exact trap that made eval:bg:all a non-run. The tier-alignment tripwire gains a second regex for the helper shape (old shape still detected — stragglers can't hide), and the sharded paid runner's PRE-SPAWN tier classifier learns the helper shape too: without that, every gate-sharded run would have spawned all 28 periodic shards just to skip them, each paying the e2e-helpers import ping (~15 min of dead wall clock in the CI-blocking lane). Verified: gate runs exclude the 29 periodic files, periodic excludes the 8 gate files — identical to pre-migration. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor(test): migrate the 36 tier-gated eval files to describeE2ETier Mechanical two-liner swap in 34 files (each keeping its declared tier — all 36 predicates verified against E2E_TIERS before migrating); the two files with compound gates (overlay-harness's EvalCollector feed, codex-e2e's CODEX_AVAILABLE) keep their extra conditions via e2eTierEnabled. Tier rationale comments preserved. codex-e2e/gemini-e2e/benchmark-providers keep their distinct stderr-message gate shapes by design. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor(test): skill-e2e + skill-llm-eval adopt the shared selection machinery Both files re-implemented the diff-selection machinery e2e-helpers already exported. The helper gained computeDiffSelection() (extracted, identical behavior) and a trailing optional selection param on the *IfSelected helpers (defaults preserve all 30+ existing importers). skill-e2e.test.ts drops ~120 duplicated lines; skill-llm-eval keeps its LLM_JUDGE_TOUCHFILES selection and test.concurrent semantics via testConcurrentIfSelected. Deliberate deltas, stated: skill-e2e.test.ts now honors the EVALS_TIER intersection its local copy lacked (affects only direct bun test invocations of that file — it matches no eval-script glob); its recordE2E gains the helper's three diagnostic fields; skill-llm-eval sharded solo now runs e2e-helpers' module-scope preflight it already ran in combined processes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): kill the silent-truncation race; exempt the tier-corrected shrinks The full-suite shakeout (budgeted by the plan) surfaced both immediately: 1. server-embedder-terminal-port.test.ts stubbed process.exit and restored the REAL exit in its finally — but shutdown() schedules async work that can call process.exit AFTER restoration, killing the entire bun process mid-suite with exit 0 and NO summary. This is the silent-truncation class the new free-suite CI job guards against, reproduced locally on the first full run. Exit now stays a logging no-op between tests (late async exits become visible stderr lines, not process death); the true exit returns in afterAll. 2. The 80%-of-baseline shrink guard correctly flagged the six tier-corrected skills — their baseline was measured at the silent tier-4 default. Added to INTENTIONAL_SHRINKS with the reason, joining spec's double-preamble entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * release: v1.64.0.0 — the code-smell fix wave 35 commits, one PR: guard repairs (free suite in CI per-file, all-host freshness gates, tunnel allowlist, diff-selection validation), the sidebar-agent ghost exorcism (dead ML layers, dead endpoints, dead exports, ghost comments), config honesty (defineHost factory, dead fields deleted, preamble tiers explicit, spec double-render fixed), and dedup with safety nets (session-cookie factory, fs-atomic, jsonl-store contract, one eval tier-gate). Net -24,943 lines across 183 files. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): free-tests step runs under bash (container sh rejects pipefail) Maiden-voyage shakeout, exactly as budgeted: the CI container's default shell is dash, which errors on 'set -o pipefail' before the first test ran. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): free-tests curates 8 container-incompatible files with reasons Second maiden-voyage shakeout round: 376 of 384 files ran green in the container on the first completed pass. The 8 that can't run there yet are excluded the same way the Windows shards curate POSIX-bound files — each with its reason inline (headed-Chrome handoff, real-PTY round-trip, X server management, extension-origin identity, the job's own TMPDIR override, and three pre-existing env failures that fail on dev machines too). Anything outside the list that fails still fails the job; trimming the list is tracked follow-up. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): gstack-config-key-locale — suppress the skill_prefix auto-relink side effect The test invokes the repo's own bin/gstack-config, whose 'set skill_prefix' auto-runs $(dirname $0)/gstack-relink — resolving the install dir to the repo itself. In any environment where the loop shares a working tree (the free-tests CI container, a fresh-HOME run), gstack-patch-names rewrote all 52 tracked SKILL.md names to gstack- prefixed, poisoning five unrelated suites downstream (hermetic-skills-seeding, host-config golden, skill-census, skill-validation, spec-template-sync). GSTACK_SETUP_RUNNING=1 is the documented suppression; relink behavior stays covered by relink.test.ts's mock install. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(bin): gstack-codex-session-import — empty sessions dir exits 0 on Linux GNU xargs runs 'ls -t' once even on empty input, listing the cwd and producing a bogus LATEST from the repo root; BSD xargs (macOS) skips the run, which is why the NO_SESSIONS path only broke on Linux. xargs -r pins the BSD behavior on both platforms. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(parity): rebaseline v1.57.7.0 → v1.64.1.0 + skeleton-cap headroom The two parallel v1.64 waves (code-smell fix wave + main's #2571) each added shared-preamble prose, pushing document-release / design-consultation / cso past their size ratios on the v1.57.7.0 anchor and four carved skeletons (plan-ceo-review, plan-eng-review, office-hours, design-consultation) 22-280 B over their absolute caps. New baseline is union-normalized (skeleton + sections/*.md, matching what the harness measures); caps get +~1 KB headroom each with per-cap rationale. The v1.57.7.0 fixture stays in test/fixtures/ for the audit trail, and capture-parity-baseline.ts now documents the union-normalization step so the next rebaseline doesn't re-trip on it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(ci): free-tests container parity — tools, pinned bun, git identity, mutation tripwire - Dockerfile.ci: add python3 (gstack-jsonl-merge/brain-sync/detach shell out to it), file (skill-validation's binary check), poppler-utils (make-pdf e2e gates hard-require pdftotext/pdffonts/pdfinfo), fonts-noto-color-emoji (emoji render gate, mirrors make-pdf-gate.yml). Fix the bun pin: the bun.sh installer ignores a BUN_VERSION env var, so the old form silently installed latest on every rebuild (observed 1.3.13/1.3.14 drift vs the 1.3.10 devs run locally); pass the version as the positional arg. - free-tests.yml: git identity + safe.directory for the git-exercising tests (container checkout is owned by a different uid than runner); post-loop tree-mutation tripwire that names a tracked-file-mutating test instead of letting downstream collateral confuse the report; skip the documented variants-retry-after timing flake. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(bin): gstack-session-update — detached updater owns its stdio (SIGPIPE) The backgrounded update subshell inherited the session hook's stdout/stderr pipes. Once the hook exits and the caller closes them, any child that writes — git pull's autostash notice, setup output — dies of SIGPIPE, logged as PULL_FAILED exit=141 with an empty stderr capture (observed in the free-tests container, and reachable by any production hook runner that closes stdio promptly). Redirect the fork to /dev/null; all observability already flows through the session-update log file. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): gstack-decision-bins — explicit branch context for the scope filter CI checks out a detached HEAD, where gitBranch() returns undefined on both the log and search sides, so an implicitly branch-scoped decision can never surface (filterByScope requires a matching non-empty ctx.branch). Pass the branch explicitly on both sides — the filter logic is what's under test, not git branch detection. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(test): ring-buffer lease interplay — same TTL window, not same millisecond Two back-to-back mintLease() calls each stamp Date.now() + TTL; when they straddle a millisecond boundary the exact-equality assertion flakes (observed in CI: expiries of ...525 vs ...526). Assert the expiries are within a 50 ms window instead — the invariant under test is that leases share a TTL policy, not that they mint in the same clock tick. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
548 lines
27 KiB
TypeScript
548 lines
27 KiB
TypeScript
import type { TemplateContext } from './types';
|
|
|
|
export function generateTestBootstrap(_ctx: TemplateContext): string {
|
|
return `## Test Framework Bootstrap
|
|
|
|
**Detect existing test framework and project runtime:**
|
|
|
|
\`\`\`bash
|
|
setopt +o nomatch 2>/dev/null || true # zsh compat
|
|
# Detect project runtime
|
|
[ -f Gemfile ] && echo "RUNTIME:ruby"
|
|
[ -f package.json ] && echo "RUNTIME:node"
|
|
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
|
|
[ -f go.mod ] && echo "RUNTIME:go"
|
|
[ -f Cargo.toml ] && echo "RUNTIME:rust"
|
|
[ -f composer.json ] && echo "RUNTIME:php"
|
|
[ -f mix.exs ] && echo "RUNTIME:elixir"
|
|
# Detect sub-frameworks
|
|
[ -f Gemfile ] && grep -q "rails" Gemfile 2>/dev/null && echo "FRAMEWORK:rails"
|
|
[ -f package.json ] && grep -q '"next"' package.json 2>/dev/null && echo "FRAMEWORK:nextjs"
|
|
# Check for existing test infrastructure
|
|
ls jest.config.* vitest.config.* playwright.config.* .rspec pytest.ini pyproject.toml phpunit.xml 2>/dev/null
|
|
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
|
|
# Check opt-out marker
|
|
[ -f .gstack/no-test-bootstrap ] && echo "BOOTSTRAP_DECLINED"
|
|
\`\`\`
|
|
|
|
**If test framework detected** (config files or test directories found):
|
|
Print "Test framework detected: {name} ({N} existing tests). Skipping bootstrap."
|
|
Read 2-3 existing test files to learn conventions (naming, imports, assertion style, setup patterns).
|
|
Store conventions as prose context for use in Phase 8e.5 or Step 7. **Skip the rest of bootstrap.**
|
|
|
|
**If BOOTSTRAP_DECLINED** appears: Print "Test bootstrap previously declined — skipping." **Skip the rest of bootstrap.**
|
|
|
|
**If NO runtime detected** (no config files found): Use AskUserQuestion:
|
|
"I couldn't detect your project's language. What runtime are you using?"
|
|
Options: A) Node.js/TypeScript B) Ruby/Rails C) Python D) Go E) Rust F) PHP G) Elixir H) This project doesn't need tests.
|
|
If user picks H → write \`.gstack/no-test-bootstrap\` and continue without tests.
|
|
|
|
**If runtime detected but no test framework — bootstrap:**
|
|
|
|
### B2. Research best practices
|
|
|
|
Use WebSearch to find current best practices for the detected runtime:
|
|
- \`"[runtime] best test framework 2025 2026"\`
|
|
- \`"[framework A] vs [framework B] comparison"\`
|
|
|
|
If WebSearch is unavailable, use this built-in knowledge table:
|
|
|
|
| Runtime | Primary recommendation | Alternative |
|
|
|---------|----------------------|-------------|
|
|
| Ruby/Rails | minitest + fixtures + capybara | rspec + factory_bot + shoulda-matchers |
|
|
| Node.js | vitest + @testing-library | jest + @testing-library |
|
|
| Next.js | vitest + @testing-library/react + playwright | jest + cypress |
|
|
| Python | pytest + pytest-cov | unittest |
|
|
| Go | stdlib testing + testify | stdlib only |
|
|
| Rust | cargo test (built-in) + mockall | — |
|
|
| PHP | phpunit + mockery | pest |
|
|
| Elixir | ExUnit (built-in) + ex_machina | — |
|
|
|
|
### B3. Framework selection
|
|
|
|
Use AskUserQuestion:
|
|
"I detected this is a [Runtime/Framework] project with no test framework. I researched current best practices. Here are the options:
|
|
A) [Primary] — [rationale]. Includes: [packages]. Supports: unit, integration, smoke, e2e
|
|
B) [Alternative] — [rationale]. Includes: [packages]
|
|
C) Skip — don't set up testing right now
|
|
RECOMMENDATION: Choose A because [reason based on project context]"
|
|
|
|
If user picks C → write \`.gstack/no-test-bootstrap\`. Tell user: "If you change your mind later, delete \`.gstack/no-test-bootstrap\` and re-run." Continue without tests.
|
|
|
|
If multiple runtimes detected (monorepo) → ask which runtime to set up first, with option to do both sequentially.
|
|
|
|
### B4. Install and configure
|
|
|
|
1. Install the chosen packages (npm/bun/gem/pip/etc.)
|
|
2. Create minimal config file
|
|
3. Create directory structure (test/, spec/, etc.)
|
|
4. Create one example test matching the project's code to verify setup works
|
|
|
|
If package installation fails → debug once. If still failing → revert with \`git checkout -- package.json package-lock.json\` (or equivalent for the runtime). Warn user and continue without tests.
|
|
|
|
### B4.5. First real tests
|
|
|
|
Generate 3-5 real tests for existing code:
|
|
|
|
1. **Find recently changed files:** \`git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -10\`
|
|
2. **Prioritize by risk:** Error handlers > business logic with conditionals > API endpoints > pure functions
|
|
3. **For each file:** Write one test that tests real behavior with meaningful assertions. Never \`expect(x).toBeDefined()\` — test what the code DOES.
|
|
4. Run each test. Passes → keep. Fails → fix once. Still fails → delete silently.
|
|
5. Generate at least 1 test, cap at 5.
|
|
|
|
Never import secrets, API keys, or credentials in test files. Use environment variables or test fixtures.
|
|
|
|
### B5. Verify
|
|
|
|
\`\`\`bash
|
|
# Run the full test suite to confirm everything works
|
|
{detected test command}
|
|
\`\`\`
|
|
|
|
If tests fail → debug once. If still failing → revert all bootstrap changes and warn user.
|
|
|
|
### B5.5. CI/CD pipeline
|
|
|
|
\`\`\`bash
|
|
# Check CI provider
|
|
ls -d .github/ 2>/dev/null && echo "CI:github"
|
|
ls .gitlab-ci.yml .circleci/ bitrise.yml 2>/dev/null
|
|
\`\`\`
|
|
|
|
If \`.github/\` exists (or no CI detected — default to GitHub Actions):
|
|
Create \`.github/workflows/test.yml\` with:
|
|
- \`runs-on: ubuntu-latest\`
|
|
- Appropriate setup action for the runtime (setup-node, setup-ruby, setup-python, etc.)
|
|
- The same test command verified in B5
|
|
- Trigger: push + pull_request
|
|
|
|
If non-GitHub CI detected → skip CI generation with note: "Detected {provider} — CI pipeline generation supports GitHub Actions only. Add test step to your existing pipeline manually."
|
|
|
|
### B6. Create TESTING.md
|
|
|
|
First check: If TESTING.md already exists → read it and update/append rather than overwriting. Never destroy existing content.
|
|
|
|
Write TESTING.md with:
|
|
- Philosophy: "100% test coverage is the key to great vibe coding. Tests let you move fast, trust your instincts, and ship with confidence — without them, vibe coding is just yolo coding. With tests, it's a superpower."
|
|
- Framework name and version
|
|
- How to run tests (the verified command from B5)
|
|
- Test layers: Unit tests (what, where, when), Integration tests, Smoke tests, E2E tests
|
|
- Conventions: file naming, assertion style, setup/teardown patterns
|
|
|
|
### B7. Update CLAUDE.md
|
|
|
|
First check: If CLAUDE.md already has a \`## Testing\` section → skip. Don't duplicate.
|
|
|
|
Append a \`## Testing\` section:
|
|
- Run command and test directory
|
|
- Reference to TESTING.md
|
|
- Test expectations:
|
|
- 100% test coverage is the goal — tests make vibe coding safe
|
|
- When writing new functions, write a corresponding test
|
|
- When fixing a bug, write a regression test
|
|
- When adding error handling, write a test that triggers the error
|
|
- When adding a conditional (if/else, switch), write tests for BOTH paths
|
|
- Never commit code that makes existing tests fail
|
|
|
|
### B8. Commit
|
|
|
|
\`\`\`bash
|
|
git status --porcelain
|
|
\`\`\`
|
|
|
|
Only commit if there are changes. Stage all bootstrap files (config, test directory, TESTING.md, CLAUDE.md, .github/workflows/test.yml if created):
|
|
\`git commit -m "chore: bootstrap test framework ({framework name})"\`
|
|
|
|
---`;
|
|
}
|
|
|
|
// ─── Test Coverage Audit ────────────────────────────────────
|
|
//
|
|
// Shared methodology for codepath tracing, ASCII diagrams, and test gap analysis.
|
|
// Three modes, three placeholders, one inner function:
|
|
//
|
|
// {{TEST_COVERAGE_AUDIT_PLAN}} → plan-eng-review: adds missing tests to the plan
|
|
// {{TEST_COVERAGE_AUDIT_SHIP}} → ship: auto-generates tests, coverage summary
|
|
// {{TEST_COVERAGE_AUDIT_REVIEW}} → review: generates tests via Fix-First (ASK)
|
|
//
|
|
// ┌────────────────────────────────────────────────┐
|
|
// │ generateTestCoverageAuditInner(mode) │
|
|
// │ │
|
|
// │ SHARED: framework detect, codepath trace, │
|
|
// │ ASCII diagram, quality rubric, E2E matrix, │
|
|
// │ regression rule │
|
|
// │ │
|
|
// │ plan: edit plan file, write artifact │
|
|
// │ ship: auto-generate tests, write artifact │
|
|
// │ review: Fix-First ASK, INFORMATIONAL gaps │
|
|
// └────────────────────────────────────────────────┘
|
|
|
|
type CoverageAuditMode = 'plan' | 'ship' | 'review';
|
|
|
|
function generateTestCoverageAuditInner(mode: CoverageAuditMode): string {
|
|
const sections: string[] = [];
|
|
|
|
// ── Intro (mode-specific) ──
|
|
if (mode === 'ship') {
|
|
sections.push(`100% coverage is the goal — every untested path is a path where bugs hide and vibe coding becomes yolo coding. Evaluate what was ACTUALLY coded (from the diff), not what was planned.`);
|
|
} else if (mode === 'plan') {
|
|
sections.push(`100% coverage is the goal. Evaluate every codepath in the plan and ensure the plan includes tests for each one. If the plan is missing tests, add them — the plan should be complete enough that implementation includes full test coverage from the start.`);
|
|
} else {
|
|
sections.push(`100% coverage is the goal. Evaluate every codepath changed in the diff and identify test gaps. Gaps become INFORMATIONAL findings that follow the Fix-First flow.`);
|
|
}
|
|
|
|
// ── Test framework detection (shared) ──
|
|
sections.push(`
|
|
### Test Framework Detection
|
|
|
|
Before analyzing coverage, detect the project's test framework:
|
|
|
|
1. **Read CLAUDE.md** — look for a \`## Testing\` section with test command and framework name. If found, use that as the authoritative source.
|
|
2. **If CLAUDE.md has no testing section, auto-detect:**
|
|
|
|
\`\`\`bash
|
|
setopt +o nomatch 2>/dev/null || true # zsh compat
|
|
# Detect project runtime
|
|
[ -f Gemfile ] && echo "RUNTIME:ruby"
|
|
[ -f package.json ] && echo "RUNTIME:node"
|
|
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
|
|
[ -f go.mod ] && echo "RUNTIME:go"
|
|
[ -f Cargo.toml ] && echo "RUNTIME:rust"
|
|
# Check for existing test infrastructure
|
|
ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
|
|
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
|
|
\`\`\`
|
|
|
|
3. **If no framework detected:**${mode === 'ship' ? ' falls through to the Test Framework Bootstrap step (Step 4) which handles full setup.' : ' still produce the coverage diagram, but skip test generation.'}`);
|
|
|
|
// ── Before/after count (ship only) ──
|
|
if (mode === 'ship') {
|
|
sections.push(`
|
|
**0. Before/after test count:**
|
|
|
|
\`\`\`bash
|
|
# Count test files before any generation
|
|
git ls-files 2>/dev/null | grep -E '(\\.test\\.|\\.spec\\.|_test\\.|_spec\\.)' | wc -l
|
|
\`\`\`
|
|
|
|
Store this number for the PR body.`);
|
|
}
|
|
|
|
// ── Codepath tracing methodology (shared, with mode-specific source) ──
|
|
const traceSource = mode === 'plan'
|
|
? `**Step 1. Trace every codepath in the plan:**
|
|
|
|
Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:`
|
|
: `**${mode === 'ship' ? '1' : 'Step 1'}. Trace every codepath changed** using \`git diff origin/<base>...HEAD\`:
|
|
|
|
Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:`;
|
|
|
|
const traceStep1 = mode === 'plan'
|
|
? `1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.`
|
|
: `1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.`;
|
|
|
|
sections.push(`
|
|
${traceSource}
|
|
|
|
${traceStep1}
|
|
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
|
|
- Where does input come from? (request params, props, database, API call)
|
|
- What transforms it? (validation, mapping, computation)
|
|
- Where does it go? (database write, API response, rendered output, side effect)
|
|
- What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
|
|
3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
|
|
- Every function/method that was added or modified
|
|
- Every conditional branch (if/else, switch, ternary, guard clause, early return)
|
|
- Every error path (try/catch, rescue, error boundary, fallback)
|
|
- Every call to another function (trace into it — does IT have untested branches?)
|
|
- Every edge: what happens with null input? Empty array? Invalid type?
|
|
|
|
This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.`);
|
|
|
|
// ── User flow coverage (shared) ──
|
|
sections.push(`
|
|
**${mode === 'ship' ? '2' : 'Step 2'}. Map user flows, interactions, and error states:**
|
|
|
|
Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
|
|
|
|
- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
|
|
- **Interaction edge cases:** What happens when the user does something unexpected?
|
|
- Double-click/rapid resubmit
|
|
- Navigate away mid-operation (back button, close tab, click another link)
|
|
- Submit with stale data (page sat open for 30 minutes, session expired)
|
|
- Slow connection (API takes 10 seconds — what does the user see?)
|
|
- Concurrent actions (two tabs, same form)
|
|
- **Error states the user can see:** For every error the code handles, what does the user actually experience?
|
|
- Is there a clear error message or a silent failure?
|
|
- Can the user recover (retry, go back, fix input) or are they stuck?
|
|
- What happens with no network? With a 500 from the API? With invalid data from the server?
|
|
- **Empty/zero/boundary states:** What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?
|
|
|
|
Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.`);
|
|
|
|
// ── Check branches against tests + quality rubric (shared) ──
|
|
sections.push(`
|
|
**${mode === 'ship' ? '3' : 'Step 3'}. Check each branch against existing tests:**
|
|
|
|
Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:
|
|
- Function \`processPayment()\` → look for \`billing.test.ts\`, \`billing.spec.ts\`, \`test/billing_test.rb\`
|
|
- An if/else → look for tests covering BOTH the true AND false path
|
|
- An error handler → look for a test that triggers that specific error condition
|
|
- A call to \`helperFn()\` that has its own branches → those branches need tests too
|
|
- A user flow → look for an integration or E2E test that walks through the journey
|
|
- An interaction edge case → look for a test that simulates the unexpected action
|
|
|
|
Quality scoring rubric:
|
|
- ★★★ Tests behavior with edge cases AND error paths
|
|
- ★★ Tests correct behavior, happy path only
|
|
- ★ Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")`);
|
|
|
|
// ── E2E test decision matrix (shared) ──
|
|
sections.push(`
|
|
### E2E Test Decision Matrix
|
|
|
|
When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:
|
|
|
|
**RECOMMEND E2E (mark as [→E2E] in the diagram):**
|
|
- Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
|
|
- Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
|
|
- Auth/payment/data-destruction flows — too important to trust unit tests alone
|
|
|
|
**RECOMMEND EVAL (mark as [→EVAL] in the diagram):**
|
|
- Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
|
|
- Changes to prompt templates, system instructions, or tool definitions
|
|
|
|
**STICK WITH UNIT TESTS:**
|
|
- Pure function with clear inputs/outputs
|
|
- Internal helper with no side effects
|
|
- Edge case of a single function (null input, empty array)
|
|
- Obscure/rare flow that isn't customer-facing`);
|
|
|
|
// ── Regression rule (shared) ──
|
|
sections.push(`
|
|
### REGRESSION RULE (mandatory)
|
|
|
|
**IRON RULE:** When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is ${mode === 'plan' ? 'added to the plan as a critical requirement' : 'written immediately'}. No AskUserQuestion. No skipping. Regressions are the highest-priority test because they prove something broke.
|
|
|
|
A regression is when:
|
|
- The diff modifies existing behavior (not new code)
|
|
- The existing test suite (if any) doesn't cover the changed path
|
|
- The change introduces a new failure mode for existing callers
|
|
|
|
When uncertain whether a change is a regression, err on the side of writing the test.${mode !== 'plan' ? '\n\nFormat: commit as `test: regression test for {what broke}`' : ''}`);
|
|
|
|
// ── ASCII coverage diagram (shared) ──
|
|
sections.push(`
|
|
**${mode === 'ship' ? '4' : 'Step 4'}. Output ASCII coverage diagram:**
|
|
|
|
Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:
|
|
|
|
\`\`\`
|
|
CODE PATHS USER FLOWS
|
|
[+] src/services/billing.ts [+] Payment checkout
|
|
├── processPayment() ├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
|
|
│ ├── [★★★ TESTED] happy + declined + timeout ├── [GAP] [→E2E] Double-click submit
|
|
│ ├── [GAP] Network timeout └── [GAP] Navigate away mid-payment
|
|
│ └── [GAP] Invalid currency
|
|
└── refundPayment() [+] Error states
|
|
├── [★★ TESTED] Full refund — :89 ├── [★★ TESTED] Card declined message
|
|
└── [★ TESTED] Partial (non-throw only) — :101 └── [GAP] Network timeout UX
|
|
|
|
LLM integration: [GAP] [→EVAL] Prompt template change — needs eval test
|
|
|
|
COVERAGE: 5/13 paths tested (38%) | Code paths: 3/5 (60%) | User flows: 2/8 (25%)
|
|
QUALITY: ★★★:2 ★★:2 ★:1 | GAPS: 8 (2 E2E, 1 eval)
|
|
\`\`\`
|
|
|
|
Legend: ★★★ behavior + edge + error | ★★ happy path | ★ smoke check
|
|
[→E2E] = needs integration test | [→EVAL] = needs LLM eval
|
|
|
|
**Fast path:** All paths covered → "${mode === 'ship' ? 'Step 7' : mode === 'review' ? 'Step 4.75' : 'Test review'}: All new code paths have test coverage ✓" Continue.`);
|
|
|
|
// ── Mode-specific action section ──
|
|
if (mode === 'plan') {
|
|
sections.push(`
|
|
**Step 5. Add missing tests to the plan:**
|
|
|
|
For each GAP identified in the diagram, add a test requirement to the plan. Be specific:
|
|
- What test file to create (match existing naming conventions)
|
|
- What the test should assert (specific inputs → expected outputs/behavior)
|
|
- Whether it's a unit test, E2E test, or eval (use the decision matrix)
|
|
- For regressions: flag as **CRITICAL** and explain what broke
|
|
|
|
The plan should be complete enough that when implementation begins, every test is written alongside the feature code — not deferred to a follow-up.`);
|
|
|
|
// ── Test plan artifact (plan + ship) ──
|
|
sections.push(`
|
|
### Test Plan Artifact
|
|
|
|
After producing the coverage diagram, write a test plan artifact to the project directory so \`/qa\` and \`/qa-only\` can consume it as primary test input:
|
|
|
|
\`\`\`bash
|
|
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
|
USER=$(whoami)
|
|
DATETIME=$(date +%Y%m%d-%H%M%S)
|
|
\`\`\`
|
|
|
|
Write to \`~/.gstack/projects/{slug}/{user}-{branch}-eng-review-test-plan-{datetime}.md\`:
|
|
|
|
\`\`\`markdown
|
|
# Test Plan
|
|
Generated by /plan-eng-review on {date}
|
|
Branch: {branch}
|
|
Repo: {owner/repo}
|
|
|
|
## Affected Pages/Routes
|
|
- {URL path} — {what to test and why}
|
|
|
|
## Key Interactions to Verify
|
|
- {interaction description} on {page}
|
|
|
|
## Edge Cases
|
|
- {edge case} on {page}
|
|
|
|
## Critical Paths
|
|
- {end-to-end flow that must work}
|
|
\`\`\`
|
|
|
|
This file is consumed by \`/qa\` and \`/qa-only\` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.`);
|
|
} else if (mode === 'ship') {
|
|
sections.push(`
|
|
**5. Generate tests for uncovered paths:**
|
|
|
|
If test framework detected (or bootstrapped in Step 4):
|
|
- Prioritize error handlers and edge cases first (happy paths are more likely already tested)
|
|
- Read 2-3 existing test files to match conventions exactly
|
|
- Generate unit tests. Mock all external dependencies (DB, API, Redis).
|
|
- For paths marked [→E2E]: generate integration/E2E tests using the project's E2E framework (Playwright, Cypress, Capybara, etc.)
|
|
- For paths marked [→EVAL]: generate eval tests using the project's eval framework, or flag for manual eval if none exists
|
|
- Write tests that exercise the specific uncovered path with real assertions
|
|
- Run each test. Passes → commit as \`test: coverage for {feature}\`
|
|
- Fails → fix once. Still fails → revert, note gap in diagram.
|
|
|
|
Caps: 30 code paths max, 20 tests generated max (code + user flow combined), 2-min per-test exploration cap.
|
|
|
|
If no test framework AND user declined bootstrap → diagram only, no generation. Note: "Test generation skipped — no test framework configured."
|
|
|
|
**Diff is test-only changes:** Skip Step 7 entirely: "No new application code paths to audit."
|
|
|
|
**6. After-count and coverage summary:**
|
|
|
|
\`\`\`bash
|
|
# Count test files after generation
|
|
git ls-files 2>/dev/null | grep -E '(\\.test\\.|\\.spec\\.|_test\\.|_spec\\.)' | wc -l
|
|
\`\`\`
|
|
|
|
For PR body: \`Tests: {before} → {after} (+{delta} new)\`
|
|
Coverage line: \`Test Coverage Audit: N new code paths. M covered (X%). K tests generated, J committed.\`
|
|
|
|
**7. Coverage gate:**
|
|
|
|
Before proceeding, check CLAUDE.md for a \`## Test Coverage\` section with \`Minimum:\` and \`Target:\` fields. If found, use those percentages. Otherwise use defaults: Minimum = 60%, Target = 80%.
|
|
|
|
Using the coverage percentage from the diagram in substep 4 (the \`COVERAGE: X/Y (Z%)\` line):
|
|
|
|
- **>= target:** Pass. "Coverage gate: PASS ({X}%)." Continue.
|
|
- **>= minimum, < target:** Use AskUserQuestion:
|
|
- "AI-assessed coverage is {X}%. {N} code paths are untested. Target is {target}%."
|
|
- RECOMMENDATION: Choose A because untested code paths are where production bugs hide.
|
|
- Options:
|
|
A) Generate more tests for remaining gaps (recommended)
|
|
B) Ship anyway — I accept the coverage risk
|
|
C) These paths don't need tests — mark as intentionally uncovered
|
|
- If A: Loop back to substep 5 (generate tests) targeting the remaining gaps. After second pass, if still below target, present AskUserQuestion again with updated numbers. Maximum 2 generation passes total.
|
|
- If B: Continue. Include in PR body: "Coverage gate: {X}% — user accepted risk."
|
|
- If C: Continue. Include in PR body: "Coverage gate: {X}% — {N} paths intentionally uncovered."
|
|
|
|
- **< minimum:** Use AskUserQuestion:
|
|
- "AI-assessed coverage is critically low ({X}%). {N} of {M} code paths have no tests. Minimum threshold is {minimum}%."
|
|
- RECOMMENDATION: Choose A because less than {minimum}% means more code is untested than tested.
|
|
- Options:
|
|
A) Generate tests for remaining gaps (recommended)
|
|
B) Override — ship with low coverage (I understand the risk)
|
|
- If A: Loop back to substep 5. Maximum 2 passes. If still below minimum after 2 passes, present the override choice again.
|
|
- If B: Continue. Include in PR body: "Coverage gate: OVERRIDDEN at {X}%."
|
|
|
|
**Coverage percentage undetermined:** If the coverage diagram doesn't produce a clear numeric percentage (ambiguous output, parse error), **skip the gate** with: "Coverage gate: could not determine percentage — skipping." Do not default to 0% or block.
|
|
|
|
**Test-only diffs:** Skip the gate (same as the existing fast-path).
|
|
|
|
**100% coverage:** "Coverage gate: PASS (100%)." Continue.`);
|
|
|
|
// ── Test plan artifact (ship mode) ──
|
|
sections.push(`
|
|
### Test Plan Artifact
|
|
|
|
After producing the coverage diagram, write a test plan artifact so \`/qa\` and \`/qa-only\` can consume it:
|
|
|
|
\`\`\`bash
|
|
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
|
|
USER=$(whoami)
|
|
DATETIME=$(date +%Y%m%d-%H%M%S)
|
|
\`\`\`
|
|
|
|
Write to \`~/.gstack/projects/{slug}/{user}-{branch}-ship-test-plan-{datetime}.md\`:
|
|
|
|
\`\`\`markdown
|
|
# Test Plan
|
|
Generated by /ship on {date}
|
|
Branch: {branch}
|
|
Repo: {owner/repo}
|
|
|
|
## Affected Pages/Routes
|
|
- {URL path} — {what to test and why}
|
|
|
|
## Key Interactions to Verify
|
|
- {interaction description} on {page}
|
|
|
|
## Edge Cases
|
|
- {edge case} on {page}
|
|
|
|
## Critical Paths
|
|
- {end-to-end flow that must work}
|
|
\`\`\``);
|
|
} else {
|
|
// review mode
|
|
sections.push(`
|
|
**Step 5. Generate tests for gaps (Fix-First):**
|
|
|
|
If test framework is detected and gaps were identified:
|
|
- Classify each gap as AUTO-FIX or ASK per the Fix-First Heuristic:
|
|
- **AUTO-FIX:** Simple unit tests for pure functions, edge cases of existing tested functions
|
|
- **ASK:** E2E tests, tests requiring new test infrastructure, tests for ambiguous behavior
|
|
- For AUTO-FIX gaps: generate the test, run it, commit as \`test: coverage for {feature}\`
|
|
- For ASK gaps: include in the Fix-First batch question with the other review findings
|
|
- For paths marked [→E2E]: always ASK (E2E tests are higher-effort and need user confirmation)
|
|
- For paths marked [→EVAL]: always ASK (eval tests need user confirmation on quality criteria)
|
|
|
|
If no test framework detected → include gaps as INFORMATIONAL findings only, no generation.
|
|
|
|
**Diff is test-only changes:** Skip Step 4.75 entirely: "No new application code paths to audit."
|
|
|
|
### Coverage Warning
|
|
|
|
After producing the coverage diagram, check the coverage percentage. Read CLAUDE.md for a \`## Test Coverage\` section with a \`Minimum:\` field. If not found, use default: 60%.
|
|
|
|
If coverage is below the minimum threshold, output a prominent warning **before** the regular review findings:
|
|
|
|
\`\`\`
|
|
⚠️ COVERAGE WARNING: AI-assessed coverage is {X}%. {N} code paths untested.
|
|
Consider writing tests before running /ship.
|
|
\`\`\`
|
|
|
|
This is INFORMATIONAL — does not block /review. But it makes low coverage visible early so the developer can address it before reaching the /ship coverage gate.
|
|
|
|
If coverage percentage cannot be determined, skip the warning silently.`);
|
|
}
|
|
|
|
return sections.join('\n');
|
|
}
|
|
|
|
export function generateTestCoverageAuditPlan(_ctx: TemplateContext): string {
|
|
return generateTestCoverageAuditInner('plan');
|
|
}
|
|
|
|
export function generateTestCoverageAuditShip(_ctx: TemplateContext): string {
|
|
return generateTestCoverageAuditInner('ship');
|
|
}
|