diff --git a/.github/workflows/ai-triage.yml b/.github/workflows/ai-triage.yml index 7a725a0cc..04bc87ae8 100644 --- a/.github/workflows/ai-triage.yml +++ b/.github/workflows/ai-triage.yml @@ -96,41 +96,47 @@ jobs: Be generous in your assessment — only flag clear violations. Ambiguous cases should be marked as aligned. Do NOT flag issues/PRs that are legitimately reporting bugs or requesting features, even if they could be better written.`; - const response = await fetch('https://api.anthropic.com/v1/messages', { - method: 'POST', - headers: { - 'x-api-key': process.env.ANTHROPIC_API_KEY, - 'content-type': 'application/json', - 'anthropic-version': '2023-06-01' - }, - body: JSON.stringify({ - model: 'claude-haiku-4-5-20251001', - max_tokens: 1024, - messages: [{ role: 'user', content: prompt }] - }) - }); - - if (!response.ok) { - const err = await response.text(); - core.setFailed(`Anthropic API error: ${response.status} ${err}`); - return; - } - - const data = await response.json(); - const text = data.content[0].text; - - // Extract JSON from response (handle markdown code blocks) - const jsonMatch = text.match(/\{[\s\S]*\}/); - if (!jsonMatch) { - core.setFailed(`Could not parse Claude response: ${text}`); + if (!process.env.ANTHROPIC_API_KEY) { + core.warning('Skipping AI triage because ANTHROPIC_API_KEY is not configured.'); return; } let result; try { + const response = await fetch('https://api.anthropic.com/v1/messages', { + method: 'POST', + headers: { + 'x-api-key': process.env.ANTHROPIC_API_KEY, + 'content-type': 'application/json', + 'anthropic-version': '2023-06-01' + }, + body: JSON.stringify({ + model: 'claude-haiku-4-5-20251001', + max_tokens: 1024, + messages: [{ role: 'user', content: prompt }] + }), + signal: AbortSignal.timeout(20000) + }); + + if (!response.ok) { + const err = await response.text(); + core.warning(`Skipping AI triage after Anthropic API error: ${response.status} ${err}`); + return; + } + + const data = await response.json(); + const text = data.content?.[0]?.text ?? ''; + + // Extract JSON from response (handle markdown code blocks) + const jsonMatch = text.match(/\{[\s\S]*\}/); + if (!jsonMatch) { + core.warning(`Skipping AI triage because the model response was not parseable JSON: ${text}`); + return; + } + result = JSON.parse(jsonMatch[0]); } catch (e) { - core.setFailed(`JSON parse error: ${e.message}\nRaw text: ${text}`); + core.warning(`Skipping AI triage after unexpected failure: ${e.message}`); return; } core.info(`Triage result: ${JSON.stringify(result, null, 2)}`); diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 17351ebb2..e14add275 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -155,7 +155,7 @@ jobs: run: npm run test:coverage windows-portability: - timeout-minutes: 15 + timeout-minutes: 25 needs: detect-changes if: >- needs.detect-changes.outputs.docs-only != 'true' @@ -180,12 +180,17 @@ jobs: - name: Typecheck extensions run: npm run typecheck:extensions - - name: Run unit tests - run: npm run test:unit - - name: Run package tests run: npm run test:packages + - name: Run Windows portability tests + run: >- + node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs + --experimental-strip-types --test + src/tests/windows-portability.test.ts + src/resources/extensions/gsd/tests/validate-directory.test.ts + src/tests/integration/web-mode-windows-hide.test.ts + rtk-portability: timeout-minutes: 20 needs: detect-changes diff --git a/.gitignore b/.gitignore index e38b0e9bb..5862cc861 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,16 @@ # ── Compiled test output ── dist-test/ +# ── Compiled output in src/ (should only contain .ts source) ── +src/**/*.js +src/**/*.js.map +src/**/*.d.ts +src/**/*.d.ts.map +!src/**/*.test.js + +# ── Repowise index (local machine-generated cache) ── +.repowise/ + # ── GSD project state (development-only, lives in worktree branches) ── package-lock.json .claude/ @@ -42,6 +52,9 @@ tmp/ packages/*/dist/ packages/*/node_modules/ +# ── Scratch/WIP files ── +preflight-script.ts + # ── GSD baseline (auto-generated) ── dist/ !/pkg/dist/modes/ @@ -55,6 +68,7 @@ TODOS.md .planning/ .audits/ docs/coherence-audit/ +.plans/ # ── GSD project state (per-worktree, never committed) ── .gsd/ @@ -65,3 +79,6 @@ bun.lock # ── GSD baseline (auto-generated) ── .gsd + +# ── GSD baseline (auto-generated) ── +.gsd-id diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 000000000..a8e68079d --- /dev/null +++ b/.mcp.json @@ -0,0 +1,14 @@ +{ + "mcpServers": { + "repowise": { + "command": "repowise", + "args": [ + "mcp", + "/Users/jeremymcspadden/Github/gsd-2", + "--transport", + "stdio" + ], + "description": "repowise: codebase intelligence \u2014 docs, graph, git signals, dead code, decisions" + } + } +} diff --git a/.plans/extension-loading-multi-path.md b/.plans/extension-loading-multi-path.md new file mode 100644 index 000000000..1cc76f735 --- /dev/null +++ b/.plans/extension-loading-multi-path.md @@ -0,0 +1,138 @@ +# Extension Loading: Dependency Sort + Unified Enable/Disable + +## Context + +GSD-2 has a well-structured extension system with three discovery paths (bundled, global/community, project-local) that are **already wired up** through pi's `DefaultPackageManager.addAutoDiscoveredResources()`. However, two critical gaps remain: + +1. `sortExtensionPaths()` (topological dependency sort) is implemented but **never called** — `dependencies.extensions` in manifests is decorative +2. The GSD extension registry (enable/disable) only applies to **bundled** extensions — community extensions bypass it entirely + +### Architecture (Current Flow) + +``` +GSD loader.ts + → discoverExtensionEntryPaths(bundledExtDir) + → filter by GSD registry (isExtensionEnabled) + → set GSD_BUNDLED_EXTENSION_PATHS env var + ↓ +DefaultResourceLoader.reload() + → packageManager.resolve() + → addAutoDiscoveredResources() + → project: cwd/.gsd/extensions/ (CONFIG_DIR_NAME = ".gsd") + → global: ~/.gsd/agent/extensions/ (includes synced bundled) + → loadExtensions(mergedPaths) ← NO sort, NO registry check on community +``` + +### Key Files + +| File | Role | +|------|------| +| `src/loader.ts` (lines 146-161) | GSD startup — bundled discovery + registry filter | +| `src/extension-sort.ts` | Topological sort (Kahn's BFS) — EXISTS but NEVER CALLED | +| `src/extension-registry.ts` | Registry I/O, enable/disable, tier checks | +| `src/resource-loader.ts` (lines 589-607) | `buildResourceLoader()` — constructs DefaultResourceLoader | +| `packages/pi-coding-agent/src/core/resource-loader.ts` (lines 311-395) | `reload()` — merges paths, calls `loadExtensions()` | +| `packages/pi-coding-agent/src/core/package-manager.ts` (lines 1585-1700) | `addAutoDiscoveredResources()` — auto-discovers from .gsd/ dirs | +| `packages/pi-coding-agent/src/core/extensions/loader.ts` (lines 945-1002) | `discoverAndLoadExtensions()` — DEAD CODE, never invoked | + +--- + +## Plan + +### Task 1: Wire topological sort into extension loading + +**What:** Call `sortExtensionPaths()` on the merged extension paths before passing them to `loadExtensions()`. + +**Where:** `packages/pi-coding-agent/src/core/resource-loader.ts` ~line 381-385 + +**Before:** +```typescript +const extensionsResult = await loadExtensions(extensionPaths, this.cwd, this.eventBus); +``` + +**After:** +```typescript +import { sortExtensionPaths } from '../../../src/extension-sort.js'; + +const { sortedPaths, warnings } = sortExtensionPaths(extensionPaths); +for (const w of warnings) { + // emit as diagnostic, not hard error +} +const extensionsResult = await loadExtensions(sortedPaths, this.cwd, this.eventBus); +``` + +**Consideration:** `sortExtensionPaths` lives in `src/` (GSD side), not in `packages/pi-coding-agent/`. Need to either: +- (a) Move it into pi-coding-agent as a shared utility, OR +- (b) Import it cross-package (already done for other GSD→pi imports), OR +- (c) Call it on the GSD side before paths reach pi — harder since auto-discovered paths are added inside pi's package manager + +Option (a) is cleanest — the sort logic only depends on `readManifestFromEntryPath` which is also in `src/extension-registry.ts` but could be duplicated or shared. + +### Task 2: Apply GSD registry to community extensions + +**What:** When `buildResourceLoader()` in `src/resource-loader.ts` constructs the DefaultResourceLoader, also discover and filter community extensions from `~/.gsd/agent/extensions/` through the GSD registry — same as it already does for `~/.pi/agent/extensions/` paths. + +**Where:** `src/resource-loader.ts` → `buildResourceLoader()` (lines 589-607) + +**Current code already filters pi extensions:** +```typescript +const piExtensionPaths = discoverExtensionEntryPaths(piExtensionsDir) + .filter((entryPath) => !bundledKeys.has(getExtensionKey(entryPath, piExtensionsDir))) + .filter((entryPath) => { + const manifest = readManifestFromEntryPath(entryPath) + if (!manifest) return true + return isExtensionEnabled(registry, manifest.id) + }) +``` + +**Add similar filtering for community extensions in agentDir:** +- Discover extensions in `~/.gsd/agent/extensions/` that are NOT bundled +- Filter through `isExtensionEnabled(registry, manifest.id)` +- Pass as disabled (via override patterns or pre-filtering) to the resource loader + +**Alternative approach:** Hook into `addAutoDiscoveredResources` or the `addResource` call to check the GSD registry. This might be cleaner since the auto-discovery already happens inside pi's package manager. + +### Task 3: Emit sort warnings as diagnostics + +**What:** Surface dependency warnings (missing deps, cycles) through GSD's diagnostic system so users see them. + +**Where:** Wherever the sort is invoked from Task 1. + +**Format:** +``` +⚠ Extension 'gsd-watch' declares dependency 'gsd' which is not installed — loading anyway +⚠ Extensions 'foo' and 'bar' form a dependency cycle — loading in alphabetical order +``` + +### Task 4: Clean up dead code + +**What:** The `discoverAndLoadExtensions()` function in `packages/pi-coding-agent/src/core/extensions/loader.ts` (lines 945-1002) is exported but never invoked. The project-local trust model inside it (`getUntrustedExtensionPaths`) also never runs. + +**Options:** +- (a) Remove it entirely — it's dead +- (b) Mark deprecated — in case upstream pi uses it +- (c) Leave it — lowest risk + +Recommend (b) for now — add `@deprecated` JSDoc so it doesn't grow new callers. + +### Task 5: Tests + +- **Sort integration test:** Create two extensions where A depends on B. Verify B loads before A after sort. +- **Registry community test:** Drop a community extension in `~/.gsd/agent/extensions/`, run `gsd extensions disable `, verify it doesn't load. +- **Conflict test:** Same extension ID in project-local and global — verify project-local wins. +- **Missing dep test:** Extension declares dependency on non-existent extension — verify warning emitted, extension still loads. +- **Cycle test:** Two extensions that depend on each other — verify warning, both load. + +--- + +## Follow-up PR (separate) + +**Subagent extension forwarding:** Update `src/resources/extensions/subagent/index.ts` to forward ALL extension paths (not just bundled) to child processes. May need a second env var like `GSD_COMMUNITY_EXTENSION_PATHS` or consolidate into `GSD_EXTENSION_PATHS`. + +--- + +## Open Questions + +1. **Where should `sortExtensionPaths` live?** Currently in `src/` (GSD side). Needs to be callable from pi's resource-loader. Options: move to pi, keep and import cross-package, or duplicate. +2. **Should community extensions respect the same registry as bundled?** Or should they have their own enable/disable mechanism? Current plan unifies them. +3. **Project-local trust:** The TOFU model in the dead `discoverAndLoadExtensions()` never runs. Should `addAutoDiscoveredResources` also gate project-local extensions behind trust? Or is `.gsd/extensions/` in your own project always trusted? diff --git a/.plans/ollama-native-provider.md b/.plans/ollama-native-provider.md new file mode 100644 index 000000000..312743c95 --- /dev/null +++ b/.plans/ollama-native-provider.md @@ -0,0 +1,241 @@ +# Ollama Extension — First-Class Local LLM Support + +## Status: DRAFT — Awaiting approval + +## Problem + +Ollama support in GSD2 currently requires manual `models.json` configuration. Users must: +1. Know the OpenAI-compatibility endpoint (`localhost:11434/v1`) +2. Manually list every model they want to use +3. Set compat flags (`supportsDeveloperRole: false`, etc.) +4. Use a dummy API key + +There's an `ollama-cloud` provider for hosted Ollama, and a discovery adapter that can list models, but no first-class **local Ollama** extension that "just works." + +## Goal + +Make Ollama the easiest way to use GSD2 — zero config when Ollama is running locally. All Ollama functionality lives in a single extension: `src/resources/extensions/ollama/`. + +## Architecture + +Everything is a self-contained extension under `src/resources/extensions/ollama/`. The extension: +- Auto-detects Ollama on startup via health check +- Discovers and registers local models with the model registry +- Provides native Ollama API streaming (not OpenAI shim) +- Exposes `/ollama` slash commands for model management +- Registers an LLM-callable tool for model pull/status + +Minimal core changes — only `KnownProvider` and `KnownApi` type additions in `pi-ai`, and `env-api-keys.ts` for key resolution. Everything else is in the extension. + +## File Structure + +``` +src/resources/extensions/ollama/ +├── index.ts # Extension entry — wires everything on session_start +├── ollama-client.ts # HTTP client for Ollama REST API (/api/*) +├── ollama-discovery.ts # Model discovery + capability detection +├── ollama-provider.ts # Native /api/chat streaming provider (registers with pi-ai) +├── ollama-commands.ts # /ollama slash commands (status, pull, list, remove, ps) +├── ollama-tool.ts # LLM-callable tool for model management +├── model-capabilities.ts # Known model capability table (context window, vision, reasoning) +└── types.ts # Shared types for Ollama API responses +``` + +## Scope + +### Phase 1: Auto-Discovery + OpenAI-Compat Routing + +**What:** Extension that auto-detects Ollama, discovers models, registers them using the existing `openai-completions` API provider. Zero config needed. + +**Extension files:** +- `ollama/index.ts` — Main entry. On `session_start`: + 1. Probe `localhost:11434` (or `OLLAMA_HOST`) with 1.5s timeout + 2. If reachable, discover models via `/api/tags` + 3. Register discovered models with `ctx.modelRegistry` using correct defaults + 4. Show status widget if Ollama is detected +- `ollama/ollama-client.ts` — Low-level HTTP client: + - `isRunning()` — `GET /` health check + - `getVersion()` — `GET /api/version` + - `listModels()` — `GET /api/tags` + - `showModel(name)` — `POST /api/show` (details, template, parameters, size) + - `getRunningModels()` — `GET /api/ps` (loaded models, VRAM usage) + - `pullModel(name, onProgress)` — `POST /api/pull` (streaming progress) + - `deleteModel(name)` — `DELETE /api/delete` + - `copyModel(source, dest)` — `POST /api/copy` + - Respects `OLLAMA_HOST` env var for non-default endpoints +- `ollama/ollama-discovery.ts` — Enhanced model discovery: + - Calls `/api/tags` to get model list + - Calls `/api/show` per model (batch, cached) to get: + - `details.parameter_size` → estimate context window + - `details.families` → detect vision (clip), reasoning (deepseek-r1) + - `modelfile` → extract default parameters + - Returns enriched `DiscoveredModel[]` with proper capabilities +- `ollama/model-capabilities.ts` — Known model lookup table: + - Maps well-known model families to capabilities + - e.g., `llama3.1` → `{ contextWindow: 131072, input: ["text"] }` + - e.g., `llava` → `{ contextWindow: 4096, input: ["text", "image"] }` + - e.g., `deepseek-r1` → `{ reasoning: true, contextWindow: 131072 }` + - e.g., `qwen2.5-coder` → `{ contextWindow: 131072, input: ["text"] }` + - Fallback: estimate from parameter count if not in table +- `ollama/types.ts` — Ollama API response types + +**Core changes (minimal):** +- `packages/pi-ai/src/types.ts` — Add `"ollama"` to `KnownProvider` +- `packages/pi-ai/src/env-api-keys.ts` — Add `"ollama"` key resolution (returns `"ollama"` placeholder — no real key needed) +- `src/onboarding.ts` — Add `"ollama"` to provider selection list +- `src/wizard.ts` — Add `ollama` entry (no key required) + +**Model registration details:** +Each discovered model registers as: +```typescript +{ + id: "llama3.1:8b", // from /api/tags + name: "Llama 3.1 8B", // humanized + api: "openai-completions", // uses existing provider + provider: "ollama", + baseUrl: "http://localhost:11434/v1", + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + reasoning: false, // from capabilities table + input: ["text"], // from capabilities table + contextWindow: 131072, // from capabilities table or /api/show + maxTokens: 16384, // conservative default + compat: { + supportsDeveloperRole: false, + supportsReasoningEffort: false, + supportsUsageInStreaming: false, + maxTokensField: "max_tokens", + }, +} +``` + +**Behavior:** +- `gsd --list-models` shows all locally-pulled Ollama models automatically +- `/model ollama/llama3.1:8b` works without any config file +- If Ollama isn't running, extension is silent — no errors, no models listed +- `models.json` overrides still work (user config wins over auto-discovery) + +### Phase 2: Native Ollama API Provider (`/api/chat`) + +**What:** A dedicated streaming provider that talks Ollama's native protocol instead of the OpenAI compatibility shim. + +**Extension files:** +- `ollama/ollama-provider.ts` — Native `/api/chat` streaming: + - Registers `"ollama-chat"` API with `registerApiProvider()` + - Implements `stream()` and `streamSimple()`: + - Maps GSD `Context` → Ollama messages format + - Maps GSD `Tool[]` → Ollama tool format + - Streams NDJSON responses, maps back to `AssistantMessage` events + - Extracts `` blocks for reasoning models (deepseek-r1, qwq) + - Ollama-specific options: + - `keep_alive` — control model memory retention (default: "5m") + - `num_ctx` — pass through model's context window + - `num_predict` — max output tokens + - Temperature, top_p, top_k + - Response metadata: + - `eval_count` / `eval_duration` → tokens/sec in usage stats + - `total_duration`, `load_duration` → performance visibility + - Vision support: converts image content to base64 for multimodal models + +**Core changes:** +- `packages/pi-ai/src/types.ts` — Add `"ollama-chat"` to `KnownApi` + +**Phase 1 models switch to `api: "ollama-chat"` by default.** Users can force OpenAI-compat via `models.json` override if needed. + +**Why native over OpenAI-compat:** +- Full `keep_alive` / `num_ctx` control +- Better error messages (Ollama-native vs generic OpenAI) +- More reliable tool calling on Ollama's native format +- Performance metrics in response (tokens/sec) +- Foundation for model management commands + +### Phase 3: Local LLM Management UX + +**What:** `/ollama` slash commands and an LLM tool for model management. + +**Extension files:** +- `ollama/ollama-commands.ts` — Slash commands registered via `pi.registerCommand()`: + - `/ollama` — Status overview: + ``` + Ollama v0.5.7 — running (localhost:11434) + + Loaded: + llama3.1:8b 4.7 GB VRAM idle 3m + + Available: + llama3.1:8b (4.7 GB) + qwen2.5-coder:7b (4.4 GB) + deepseek-r1:8b (4.9 GB) + ``` + - `/ollama pull ` — Pull with streaming progress via `ctx.ui.setWidget()` + - `/ollama list` — List all local models with sizes and families + - `/ollama remove ` — Delete a model (with confirmation) + - `/ollama ps` — Running models + VRAM usage +- `ollama/ollama-tool.ts` — LLM-callable tool registered via `pi.registerTool()`: + - `ollama_manage` tool — lets the agent pull/list/check models + - Parameters: `{ action: "list" | "pull" | "status" | "ps", model?: string }` + - Use case: agent detects it needs a model, pulls it automatically + +**UX Flow:** +``` +$ gsd +> /ollama +Ollama v0.5.7 — running (localhost:11434) +Loaded: + llama3.1:8b — 4.7 GB VRAM, idle 3m +Available: + llama3.1:8b (4.7 GB) + qwen2.5-coder:7b (4.4 GB) + deepseek-r1:8b (4.9 GB) + +> /ollama pull codestral:22b +Pulling codestral:22b... +████████████████████████████░░░░ 78% (14.2 GB / 18.1 GB) +✓ codestral:22b ready + +> /model ollama/codestral:22b +Switched to codestral:22b (local, Ollama) +``` + +## Implementation Order + +1. **Phase 1** — Auto-discovery with OpenAI-compat routing. Biggest user impact, smallest risk. +2. **Phase 3** — Management UX (`/ollama` commands). Valuable even before native API. +3. **Phase 2** — Native `/api/chat` provider. Optimization over OpenAI-compat; do last. + +## Core Changes Summary (minimal) + +| File | Change | +|------|--------| +| `packages/pi-ai/src/types.ts` | Add `"ollama"` to `KnownProvider`, `"ollama-chat"` to `KnownApi` (Phase 2) | +| `packages/pi-ai/src/env-api-keys.ts` | Add `"ollama"` → always returns `"ollama"` placeholder | +| `src/onboarding.ts` | Add `"ollama"` to provider picker | +| `src/wizard.ts` | Add `"ollama"` key mapping (no key required) | + +Everything else lives in `src/resources/extensions/ollama/`. + +## Risks & Mitigations + +| Risk | Mitigation | +|------|------------| +| Ollama not running — startup probe latency | 1.5s timeout; cache result; probe async so it doesn't block TUI paint | +| Model capabilities unknown | Known-model table + `/api/show` fallback + parameter_size estimation | +| Tool calling unreliable on small models | Detect param count; warn on <7B models | +| Ollama API changes between versions | Version detect via `/api/version`; stable endpoints only | +| Conflicts with `models.json` Ollama config | User config always wins; auto-discovered models merge beneath manual config | +| Extension disabled — no impact on core | Extension is additive; disabling removes all Ollama features cleanly | + +## Testing Strategy + +- Unit tests: `ollama-client.ts` with mocked fetch responses +- Unit tests: `ollama-discovery.ts` model capability parsing +- Unit tests: `ollama-provider.ts` message format mapping + NDJSON stream parsing +- Unit tests: `model-capabilities.ts` known model lookups +- Integration test: mock HTTP server simulating Ollama `/api/tags`, `/api/chat`, `/api/pull` +- Manual test: real Ollama instance with llama3.1, qwen2.5-coder, deepseek-r1 + +## Open Questions + +1. **Startup probe** — Probe Ollama on `session_start` (adds ~1.5s if not running) or lazy on first `/model`? **Recommendation: async probe on session_start (non-blocking), eager if `OLLAMA_HOST` is set.** +2. **Auto-start** — Try to launch Ollama if installed but not running? **Recommendation: no — too invasive. Show helpful message in `/ollama` status.** +3. **Vision support** — Support multimodal models (llava, etc.) in Phase 2 native API? **Recommendation: yes, detected via capabilities table.** +4. **Model refresh** — How often to re-probe Ollama for new models? **Recommendation: on `/ollama list`, on `/model` command, and every 5 min (existing TTL).** diff --git a/.prompt-injection-scanignore b/.prompt-injection-scanignore new file mode 100644 index 000000000..b6cc73a03 --- /dev/null +++ b/.prompt-injection-scanignore @@ -0,0 +1,2 @@ +# False positives in GSD prompt templates — these are legitimate LLM instructions, not injection +src/resources/extensions/gsd/prompts/doctor-heal.md:You are now responsible diff --git a/CHANGELOG.md b/CHANGELOG.md index c39890e6a..a89f4f0b3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,592 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +## [2.71.0] - 2026-04-11 + +### Added +- **mcp-server**: add secure_env_collect tool via MCP form elicitation + +### Fixed +- **tui**: clear pinned output on message_end to prevent duplicate display +- **tui**: clear pinned latest output on turn completion +- **tui**: restore pinned output above editor during tool execution +- TOCTOU file locking race conditions in event log and custom workflow graph +- **tui**: mask secure extension input values in interactive mode +- **claude-code**: harden MCP elicitation schema handling +- **claude-code**: accept secure_env_collect MCP elicitation forms +- **interactive**: keep MCP tool output ordered and restore secure prompt fallback +- **interactive**: preserve MCP tool output stream ordering +- **gsd**: resolve workflow MCP test typing regressions +- **mcp**: return isError flag on workflow tool execution failures +- **discuss**: add structuredQuestionsAvailable conditional to all gates +- **discuss**: add multi-round questioning to new-project discuss phase +- **gsd**: harden claude-code workflow MCP bootstrap +- **web**: drop provisional pre-tool question text + +### Changed +- extract deriveStateFromDb logic into composable helpers +- **pr**: drop web-layer changes from MCP stream-order fix + +## [2.70.1] - 2026-04-11 + +### Fixed +- **routing**: address codex review — complete interactive bypass and accurate banner +- **routing**: skip dynamic routing for interactive dispatches, always show model changes (#3962) +- **ci**: trim windows portability integration load +- **ci**: narrow windows portability coverage +- **ci**: skip validate-pack in windows portability job +- **ci**: unblock windows portability follow-up +- **windows**: harden portability across runtime and tooling +- **auto**: use pathToFileURL for cross-platform import and reconcile regression test +- **auto**: resolve resource-loader.js from GSD_PKG_ROOT on resume (#3949) +- **mcp-server**: importLocalModule resolves src/ paths from dist/ context +- **gsd**: surface scoped doctor health warnings +- **gsd**: skip skipped slices in milestone prompts +- **gsd**: handle doubled-backtick pre-exec paths +- **update**: fetch latest version from registry + +## [2.70.0] - 2026-04-10 + +### Added +- **mcp-server**: expose ask_user_questions via elicitation + +### Fixed +- **pi-ai**: remove Anthropic OAuth flow for TOS compliance +- **mcp-server**: hydrate model credentials into env +- **mcp-server**: hydrate stored tool credentials on startup +- **gsd**: auto-enable cmux when detected instead of prompting +- **mcp-server**: URL scheme regex no longer matches Windows drive letters + +## [2.69.0] - 2026-04-10 + +### Added +- **gsd**: implement ADR-005 multi-model provider and tool strategy +- **gsd**: complete ADR-004 capability-aware model routing implementation + +### Fixed +- **gsd**: add missing directories to codebase generator exclude list +- **gsd**: wire ADR-005 infrastructure into live paths +- **gsd**: replace empty catch with logWarning for CI compliance +- **gsd**: merge enhanced context sections into standard template, clean up stale gate patterns +- **gsd**: remove broken discuss-prepared template, inject briefs into discuss.md + +## [2.68.1] - 2026-04-10 + +### Fixed +- **ci**: update FILE-SYSTEM-MAP.md path after docs reorganization +- **test**: update discord invite test path after docs reorganization +- **gsd**: resolve resource-loader import for deployed extensions + +## [2.68.0] - 2026-04-10 + +### Added +- expose slice replanning over workflow MCP +- expose milestone workflow tools over MCP +- expose slice completion over workflow MCP +- expose task completion alias over workflow MCP +- expose GSD planning tools over MCP +- gate workflow MCP units by provider transport capabilities +- expose core GSD workflow tools over MCP +- add contextual tips system for TUI and web terminal + +### Fixed +- **state**: prevent false degraded-mode warning when DB not yet initialized +- **gsd**: use debugLog in catch block to satisfy empty-catch lint +- **gsd**: avoid false manifest and skipped-slice warnings +- **gsd**: replace empty catch block with descriptive comment +- guard autoCommitDirtyState and restore cwd on MergeConflictError (#2929) +- Claude Code MCP tool output rendering and real-time streaming +- **gsd**: surface warnings when DB or STATE.md init fails +- **gsd**: create gsd.db, runtime/, and STATE.md during init (#3880) +- **gsd**: suppress workflow stderr during /gsd +- **gsd**: enforce workflow write gates over MCP +- restore autoStartTime on resume + replace empty catch blocks (#3585) +- **mcp**: harden workflow tool boundary +- **gsd**: accept em-dash none verification rationale +- **gsd**: resync managed resources on auto resume +- **gsd**: stop stale forensics context hijacks +- **gsd**: serialize workflow MCP execution state +- **gsd**: restore milestone status db preflight +- **claude-code-cli**: suppress streamed internal tool noise +- **gsd**: skip same-path planning artifact copies +- **claude-code-cli**: suppress internal tool call noise +- **pi-coding-agent**: avoid oauth login for api-key providers +- **gsd**: snapshot new untracked files before dispatch +- **platform**: harden command execution and stabilize onboarding sync +- **pi-ai**: restore event stream factory export +- **gsd**: use valid codebase refresh logger +- **gsd**: auto-refresh codebase cache +- **gsd**: align model switching and prefs surfaces +- route slice and validation artifacts through DB tools +- make gsd_complete_task the only execute-task summary path +- **docs**: stop pointing repo documentation to gsd.build +- add activeEngineId and activeRunDir to PausedSessionMetadata interface +- **gsd**: address QA round 4 +- **gsd**: address QA round 3 +- **gsd**: address QA round 2 +- **gsd**: address QA round 1 +- **gsd**: address review feedback from trek-e +- **gsd**: assess recovery from paused worktree state +- **gsd**: satisfy extension typecheck for interrupted recovery +- **gsd**: restore hook dispatch export and guided flow imports +- **gsd**: clear stale paused metadata in guided flow +- **gsd**: preserve interrupted-session resume mode +- preserve explicit interrupted-session resume mode +- preserve step-mode and suppress stale paused resumes +- suppress stale interrupted-session resume prompts + +### Changed +- harden workflow MCP executor loading +- **ci**: add weekly workflow to regenerate model registry +- **deps**: refresh audited package locks + +## [2.67.0] - 2026-04-09 + +### Added +- **context**: implement R005 decision scope cascade and derive scope from slice metadata +- **M005**: Tiered Context Injection - relevance-scoped context with 65%+ reduction + +### Fixed +- **test**: align auto-loop test timers with updated session timeout +- **gsd**: repair CI after branch split +- **gsd**: repair CI after branch split +- **gsd**: repair CI after branch split +- **gsd**: fail closed for discussion gate enforcement +- **gsd**: harden auto merge recovery and session safety +- **gsd**: repair overlay, shortcut, and widget surfaces +- **gsd**: prevent stale workflow reconcile state writes +- **gsd**: align prompt contracts and validation flow +- **pi-tui**: harden input parsing and editor focus behavior +- **remote-questions**: cancel local TUI when remote answer wins the race +- **auto**: increase session timeout to 120s and treat timeout as recoverable pause (#3767) +- **ui**: apply anthropic-api display name to all model/provider UI surfaces +- **ui**: display 'anthropic-api' in GSD preferences wizard provider list +- **remote-questions**: race local TUI against remote channel instead of remote-only routing +- **ui**: display 'anthropic-api' in model selector to distinguish from claude-code +- **gates**: add mechanical enforcement for discussion question gates +- **prompts**: harden non-bypassable gates and exclude dot-folders from scanning +- **gsd**: ignore filename headings in parsePlan +- **providers**: match 'out of extra usage' error and respect claude-code provider in model resolution (#3772) +- **pi-ai**: recover XML parameters trapped in JSON strings +- **retry**: guard claude-code fallback to anthropic provider only +- **providers**: route Anthropic subscription users through Claude Code CLI (#3772) +- **claude-code**: use native Windows claude lookup +- **gsd**: suppress repeated preferences section warnings +- **gsd**: normalize described expected output paths +- **auto**: resilient transient error recovery — defer to Core RetryHandler and fix cmdCtx race + +## [2.66.1] - 2026-04-08 + +### Fixed +- **pi-tui**: revert contentCursorRow, use hardwareCursorRow as movement baseline +- **pi-tui**: use contentCursorRow for render movement baseline instead of cursorRow +- **gsd**: add logWarning to empty catch block in orphaned worktree cleanup +- **gsd**: add consecutiveFinalizeTimeouts to LoopState in journal tests +- **gsd**: add escalation and unit-detach guards to finalize timeout handlers +- **gsd**: add timeout guard around postUnitPreVerification to prevent auto-loop hang +- **gsd**: OS-specific keyboard shortcut hints via formatShortcut helper +- **subagent**: support list-style tools frontmatter +- clear autocomplete rows from content bottom +- parse annotated pre-exec file paths +- **gsd**: add orphaned milestone branch audit at auto-mode bootstrap + +## [2.66.0] - 2026-04-08 + +### Added +- **gsd**: add fast path for queued milestone discussion +- **gsd**: add /gsd show-config command +- **reactive**: graph diagnostics and subagent_model config +- **dispatch**: parallel research slices and parallel milestone validation +- **parallel**: worker model override for parallel milestone workers + +### Fixed +- **gsd**: validate depth verification answer before unlocking write-gate +- **gsd**: revert unknown artifact check to warn-and-proceed +- **gsd**: add missing cmd field to test base WorkflowEvent +- **gsd**: address remaining adversarial review findings for wave 3 +- **gsd**: detect concurrent event log growth during reconcile +- **gsd**: address adversarial review findings for wave 3 +- **gsd**: address adversarial review findings for wave 2 +- **gsd**: address adversarial review findings for wave 1 +- **gsd**: WAL-safe migration backup + stronger regression tests +- **gsd**: consistency and cleanup (wave 5/5) +- **gsd**: write safety — atomic writes and randomized tmp paths (wave 4/5) +- **gsd**: session and recovery robustness (wave 3/5) +- **gsd**: event log and reconciliation robustness (wave 2/5) +- **gsd**: critical state machine data integrity fixes (wave 1/5) +- **gsd**: critical state machine data integrity fixes (wave 1/5) +- **gsd**: remove ecosystem research stub and address adversarial review +- **gsd**: suppress model change notification in auto-mode unless verbose +- **gsd**: exclude task.files from checkTaskOrdering to prevent false positives +- **state**: skip ghost check for queued milestones in registry build +- **ci**: replace empty catch blocks and raw stderr with logWarning +- **logging**: add debugLog to empty catch in reopen-milestone +- **state-machine**: 9 resilience fixes + 86 regression tests (#3161) +- **gsd**: add incremental persistence to discuss prompts +- replace empty catch with logWarning for silent-catch-diagnostics test +- **test**: escape regex metacharacters in skip-by-preference pattern test +- **test**: search for numbered step definitions in prompt ordering test +- **test**: update notes loop test for notesVisible guard behavior +- **test**: update action count for note captures now included in results +- **test**: remove extraneous test file from wrong branch +- **test**: update worktree sync tests to use separate milestone IDs +- **gsd**: use valid LogComponent type for stale branch guard warning +- **test**: update rogue detection test for auto-remediation behavior +- **test**: update stuck-planning test to expect executing after reconciliation +- **test**: update file path consistency tests for inputs-only checking +- **test**: add CONTEXT file to queued milestone ghost detection test +- **test**: update needs-remediation test to expect validating-milestone phase +- **gsd**: import all-done milestones as complete during DB migration +- **gsd**: allow milestone completion when validation skipped by preference +- **gsd**: set slice sequence at all three insertion sites +- **gsd**: four prompt/runtime fixes for completion and session stability +- **gsd**: default insertMilestone status to queued instead of active +- **gsd**: suppress repeated frontmatter YAML parse warnings +- **gsd**: normalize list inputs in complete-task + fix roadmap dep parsing +- **gsd**: open DB before status derivation + respect isolation:none in quick +- **gsd**: add .bg-shell/ to baseline gitignore patterns +- **tui**: prevent Enter key infinite loop in interview notes mode +- **provider**: handle Enter key to initiate auth setup in provider manager +- **gsd**: cap run-uat dispatch attempts to prevent infinite replay loop +- **mcp**: use createRequire to resolve SDK wildcard subpath imports +- **gsd**: mark note captures as executed in executeTriageResolutions +- **gsd**: validate main_branch preference exists before using in merge +- **gsd**: handle deleted cwd in projectRoot to prevent ENOENT crash +- **gsd**: skip current milestone in syncWorktreeStateBack to prevent merge conflicts +- **gsd**: add structuredQuestionsAvailable conditional to slice discuss +- **gsd**: restore full tool set after discuss flow scoping +- **gsd**: tighten verifyExpectedArtifact to prevent rogue-write false positives +- **gsd**: add verification gate to complete-slice tool +- **gsd**: fix pre-execution-checks false positives from backticks and task.files +- **gsd**: stop renderAllProjections from overwriting authoritative PLAN.md +- **gsd**: auto-checkout to main when isolation:none finds stale milestone branch +- **gsd**: auto-remediate stale slice DB status when SUMMARY exists on disk +- **gsd**: open DB on demand in gsd_milestone_status for non-auto sessions +- **gsd**: detect phantom milestones from abandoned gsd_milestone_generate_id +- **gsd**: force re-validation when verdict is needs-remediation +- **gsd**: exclude closed slices from findMissingSummaries check +- **gsd**: recover from stale lockfile after crash or SIGKILL +- **gsd**: add createdAt timestamp and 30s age guard to staleness check +- **gsd**: clear stale pendingAutoStart after /clear interrupts discussion +- **gsd**: suppress misleading warnings for expected ENOENT/EISDIR conditions +- **gsd**: extract real error from message content when errorMessage is useless +- **gsd**: extract real error from message content when errorMessage is useless +- **gsd**: show accurate pause message for queued-user-message skip +- **gsd**: treat queued-user-message skip as non-retryable interruption +- **gsd**: recognize "Not provided." default in isVerificationNotApplicable +- **gsd**: discoverManifests skips symlinked extension directories +- **gsd**: recognize "Not provided." default in isVerificationNotApplicable +- **gsd**: reconcile plan-file tasks into DB when planner skips persistence (#3600) +- **gsd**: use isClosedStatus() in dispatch guard instead of raw complete check +- **browser-tools**: make sharp an optional lazy dependency +- **gsd**: pass required arguments in defer-milestone-stamp test +- **gsd**: replace remaining empty catch with logWarning +- **gsd**: use logWarning instead of raw stderr in catch blocks +- **gsd**: log error instead of empty catch in STATE.md rebuild +- **gsd**: log error instead of empty catch in skip_slice +- **gsd**: cast milestone classification to string for type safety +- **gsd**: treat zero-slice roadmap as pre-planning in guided flow +- **gsd**: rebuild STATE.md after skip-slice and strengthen rethink prompt +- **gsd**: use main_branch preference in worktree creation +- **gsd**: stamp defer and milestone captures as executed after triage +- **tui**: treat absolute file paths as plain text, not commands +- **tui**: break infinite re-render loop for images in cmux +- **gsd**: rebuild STATE.md before guided-flow dispatch +- **gsd**: defer queued shells in active milestone selection +- **retry**: prevent 429 quota cascade and 30-min lockout +- **gsd**: add fastPathInstruction to buildDiscussMilestonePrompt loadPrompt call + +### Changed +- auto-commit after quick-task +- auto-commit after quick-task +- auto-commit after quick-task +- auto-commit after quick-task +- auto-commit after quick-task +- auto-commit after quick-task +- auto-commit after quick-task + +## [2.65.0] - 2026-04-07 + +### Added +- **gsd**: persistent notification panel with TUI overlay, widget, and web API +- **gsd**: wire blocking behavior and strict mode for enhanced verification +- **gsd**: add post-execution cross-task consistency checks +- **gsd**: add pre-execution plan verification checks + +### Fixed +- **gsd**: wrap long notification messages and fit overlay to content +- **gsd**: remove background color from backdrop, fix message truncation +- **gsd**: restore consistent overlay height to prevent ghost artifacts +- **gsd**: improve notification overlay backdrop and content-fit sizing +- **gsd**: only unlink notification lock when owned, prevent foreign lock deletion +- **gsd**: add backdrop dimming and viewport padding to notification overlay +- **gsd**: add intent + phase guards to resume context fallback (#3615) +- **gsd**: inject task context for unstructured resume prompts (#3615) +- **pi-coding-agent**: restore extension tools after session switch (#3616) +- **agent-loop**: schema overload cap ignores bash execution errors (#3618) +- **bg-shell**: prevent signal handler accumulation + cap alert queue +- **gsd**: coerce plain-string provides field to array in complete-slice (#3585) +- address PR #3468 review findings +- **gsd**: persist autoStartTime across session resume so elapsed timer survives /exit +- **gsd**: add enhanced_verification preferences to mergePreferences +- **headless**: treat discuss and plan as multi-turn commands + +### Changed +- **interactive**: cap rendered chat components + kill orphan descendants +- **tui**: render-skip, frame isolation, Text cache guard, dispose + +## [2.64.0] - 2026-04-06 + +### Added +- **gsd**: add LLM safety harness for auto-mode damage control +- **ollama**: native /api/chat provider with full option exposure +- **parallel**: slice-level parallelism with dependency-aware dispatch (#3315) +- **mcp-client**: add OAuth auth provider for HTTP transport (#3295) + +### Fixed +- **ui**: remove 200-column cap on welcome screen width +- address adversarial review findings for #3576 +- **gsd**: replace hardcoded agent skill paths with dynamic resolution (#3575) +- **headless**: sync resources and use agent dir for query +- **cli**: show latest version and bypass npm cache in update check +- **gsd**: follow CONTRIBUTING standards for #3565 +- **gsd**: address Codex adversarial review findings for #3565 +- **gsd**: coerce string arrays to objects in complete-slice/task tools (#3565) +- **gsd**: harden flat-rate routing guard against alias/resolution gaps +- **pi-coding-agent**: register models.json providers and await Ollama probe in headless mode +- **ollama**: use apiKey auth mode to avoid streamSimple crash +- **gsd**: disable dynamic model routing for flat-rate providers +- **gsd**: address Codex adversarial review findings +- **gsd**: prevent LLM from querying gsd.db directly via bash (#3541) +- **gsd**: seed requirements table from REQUIREMENTS.md on first update +- **gsd**: inject S##-CONTEXT.md from slice discussion into all prompt builders +- **cli**: guard model re-apply against session restore and async rejection +- **pi-coding-agent**: resolve model fallback race that ignores configured provider (#3534) +- **detection**: add xcodegen and Xcode bundle support to project detection (#1882) +- **perf**: share jiti module cache across extension loads (#3308) +- **resource-sync**: prune removed bundled subdirectory extensions on upgrade (#1972) +- recognize U+2705 checkmark emoji as completion marker in prose roadmaps (#1897) +- **web**: use safePackageRootFromImportUrl for cross-platform package root (#1881) (#1893) +- isolate CmuxClient stdio to prevent TUI hangs in CMUX (#3306) +- worktree health check walks parent dirs for monorepo support (#3313) +- **gsd**: promote milestone status from queued to active in plan-milestone (#3317) +- **worktree**: correct merge failure notification command from /complete-milestone to /gsd dispatch complete-milestone (#1901) +- detect and block Gemini CLI OAuth tokens used as API keys (#3296) +- **auto**: break retry loop on tool invocation errors (malformed JSON) (#3298) +- **git**: use git add -u in symlink .gsd fallback to prevent hang (#3299) +- handle complete-slice context exhaustion to unblock downstream slices (#3300) +- cap consecutive tool validation failures to prevent stuck-loop (#3301) +- make enrichment tool params optional for limited-toolcall models (#3302) +- add filesystem safety guard to complete-slice.md (#3304) +- **extensions**: use bundledExtensionKeys for conflict detection instead of broken path heuristic (#3305) +- scope tools during discuss flows to prevent grammar overflow (#3307) +- **preferences**: warn on silent parse failure for non-frontmatter files (#3310) +- track remote-questions in managed-resources manifest (#3312) +- **auto**: add timeout guard for postUnitPostVerification in runFinalize (#3314) +- **gsd**: handle large markdown parameters in complete-milestone JSON parsing (#3316) +- **metrics**: deduplicate idle-watchdog entries and fix forensics false-positives (#1973) +- prevent milestone/slice artifact rendering corruption (#3293) +- **doctor**: strip --fix flag before positional parse (#1919) (#1926) +- resolve external-state worktree DB path (#2952) (#3303) +- **gsd**: worktree teardown path validation prevents data loss (#3311) +- prevent auto-mode from dispatching deferred slices (#3309) +- preserve completed slice status on plan-milestone re-plan (#3318) +- reopen DB on cold resume, recognize heavy check mark (#3319) +- dashboard model label shows dispatched model, not stale previous unit (#3320) + +### Changed +- **gsd**: remove copyright line from test file +- **gsd**: trim promptGuidelines to 1 line to reduce per-turn token cost +- **web**: consolidate subprocess boilerplate into shared runner (#1899) + +## [2.63.0] - 2026-04-05 + +### Added +- **mcp-server**: add 6 read-only tools for project state queries (#3515) + +### Fixed +- **gsd**: enrich vague diagnostic messages with root-cause context +- **test**: reset dedup cache between ask-user-freetext tests +- **db**: delete orphaned WAL/SHM files alongside empty gsd.db (#2478) +- **gsd**: prevent auto-wrapup from interrupting in-flight tool calls (#3512) +- **gsd**: handle bare model IDs in resolveDefaultSessionModel (#3517) +- **gsd**: wrap decision and requirement saves in transaction to prevent ID races +- **gsd**: prefer PREFERENCES.md over settings.json for session bootstrap model (#3517) +- **gsd**: add Claude Code official skill directories to skill resolution +- **dedup**: hash full question payload, not just IDs +- **gsd**: prevent duplicate ask_user_questions dispatches with per-turn dedup cache +- **pi-ai**: extend repairToolJson to handle XML tags and truncated numbers +- **pi-coding-agent**: cancel stale retries after model switch + +### Changed +- untrack .repowise/ and add to .gitignore + +## [2.62.1] - 2026-04-05 + +### Fixed +- **gsd**: gate steer worktree routing on active session, fix messaging +- **gsd**: resolve steer overrides to worktree path when worktree is active + +## [2.62.0] - 2026-04-04 + +### Added +- **gsd**: enhance /gsd codebase with preferences, --collapse-threshold, and auto-init +- **01-05**: fire before_model_select hook, add verbose scoring output, load capability overrides +- **01-04**: register before_model_select placeholder handler in GSD hooks +- **01-04**: add BeforeModelSelectEvent to extension API and wire emission +- **01-03**: wire taskMetadata from selectAndApplyModel to resolveModelForComplexity +- **01-03**: insert STEP 2 capability scoring into resolveModelForComplexity +- **01-01**: add taskMetadata to ClassificationResult and export extractTaskMetadata +- **01-01**: add capability types, data tables, and scoring functions to model-router + +### Fixed +- **gsd**: add codebase validation in validatePreferences so preferences are not silently dropped +- **test**: update db-path-worktree-symlink test for simplified diagnostic logging +- **gsd**: update tests for errors-only audit persistence, fix empty catch blocks +- **gsd**: harden audit log persistence — errors-only, sanitized, demote probe warnings +- **gsd**: address adversarial review findings on workflow-logger migration +- **gsd**: fail-closed stop guard, harden backtrack parsing, fix prompt params +- **gsd**: add diagnostic logging to empty catch blocks in auto-mode +- **lsp**: add legacy alias for renamed kotlin-language-server key +- break infinite notes loop when selecting "None of the above" +- align defaultRoutingConfig capability_routing to true +- **pi-coding-agent**: upgrade Kotlin LSP to official Kotlin/kotlin-lsp +- **test**: use correct RequirementCounts type fields in edge case tests +- **remote-questions**: fire configured channels in interactive mode + +### Changed +- **gsd**: migrate all catch blocks to centralized workflow-logger +- init gsd + +## [2.61.0] - 2026-04-04 + +### Added +- stop/backtrack capture classifications for milestone regression (#3488) +- GSD context optimization with model routing and context masking + +## [2.60.0] - 2026-04-04 + +### Added +- add /btw skill — ephemeral side questions from conversation context + +### Fixed +- **btw**: remove LLM-specific references from skill description + +## [2.59.0] - 2026-04-03 + +### Added +- **extensions**: add Ollama extension for first-class local LLM support (#3371) +- **doctor**: stale commit safety check with gsd snapshot and auto-cleanup +- **extensions**: wire up topological sort and unified registry filtering (#3152) +- **widget**: add last commit display and dashboard layout improvements (#3226) +- **model-routing**: enable dynamic routing by default (#3120) +- **vscode**: sidebar redesign, SCM provider, checkpoints, diagnostics [3/3] +- **splash**: add remote channel indicator to welcome screen tools row +- stream full text and thinking output in headless verbose mode (#2934) +- **gsd**: add codebase map — structural orientation for fresh agent contexts + +### Fixed +- **worktree**: resolve merge conflict for PR #3322 — adopt comprehensive pre-merge cleanup +- **merge**: clean stale MERGE_HEAD before squash merge (#2912) +- **state**: always run disk→DB reconciliation when DB is available (#2631) +- **git-service**: fix merge-base ancestry check and .gsd/ leakage in snapshot absorption +- **extensions**: update provides.hooks in 7 extension manifests to match actual registrations (#3157) +- surface nativeCommit errors in reconcileMergeState instead of silently swallowing (#3052) +- **parallel**: scope commits to milestone boundaries in parallel mode (#3047) +- add windowsHide to all web-mode subprocess spawns (#2628) (#3046) +- skip auto-mode pause on empty-content aborted messages (#2695) (#3045) +- detect and remove nested .git dirs in worktree cleanup to prevent data loss (#3044) +- prevent data loss when git isolation default changes (#2625) (#3043) +- **read-tool**: clamp offset to file bounds instead of throwing (#3007) (#3042) +- **gsd**: preserve queued milestones with worktrees in ghost detection (#3041) +- **compaction**: add chunked fallback when messages exceed model context window (#3038) +- preserve interactive terminal across tab switches and project changes (#3055) +- call cleanupQuickBranch on turn_end to squash-merge quick branch back (#3054) +- align run-uat artifact path to ASSESSMENT, preventing false stuck retries (#3053) +- replace invalid Discord invite links with canonical URL (#3056) +- add Windows shell guard to remaining spawn sites (#3058) +- route `gsd auto` to headless runner to prevent hang on piped stdin/stdout (#3057) +- respect .gitignore for .gsd/ in rethink prompt (#3059) +- migrate unit ownership from JSON to SQLite to eliminate read-modify-write race (#3061) +- **roadmap**: handle numbered, bracketed, and indented prose H3 headers in slice parser (#3063) +- add worktree-merge to resolveModelWithFallbacksForUnit switch and update KNOWN_UNIT_TYPES (#3066) +- clean up MERGE_HEAD on all error paths in mergeMilestoneToMain (#2912) (#3068) +- prevent LLM from confusing background task output with user input (#3069) +- add openai-codex provider and modern OpenAI models to MODEL_CAPABILITY_TIER and cost tables (#3070) +- preserve active tab when switching projects (#3071) +- include project name in desktop notifications (#3072) +- recover from many-image dimension overflow by stripping older images (#3075) +- resolve bare model IDs to anthropic over claude-code provider (#3076) +- **auto**: move selectAndApplyModel before updateProgressWidget (#3079) +- detect project relocation and recover state without data loss (#3080) +- add free-text input to ask-user-questions when "None of the above" is selected (#3081) +- block work execution during /gsd queue mode (#2545) (#3082) +- detect worktree basePath in gsdRoot() to prevent escaping to project root (#3083) +- invalidate stale quick-task captures across milestone boundaries (#3084) +- defer model validation until after extensions register (#3089) +- repair YAML bullet lists in malformed tool-call JSON (#3090) +- unify SUMMARY.md render paths for projection fidelity (#3091) +- chat mode misrepresents terminal output, looks stuck, omits user messages (#3092) +- resolve 4 state corruption bugs in milestone/slice completion (#2945) (#3093) +- isolate guided-flow session state and key discussion milestone queries (#2985) (#3094) +- **guided-flow**: route dispatchWorkflow through dynamic routing pipeline (#3153) +- skip external state migration inside git worktrees (#2970) (#3227) +- coerce non-numeric strings in DB columns during manifest serialization (#2962) (#3229) +- route allDiscussed and zero-slices paths to queued milestone discussion (#3150) (#3230) +- use loose equality for null checks in secure_env_collect (#2997) (#3231) +- prevent prompt explosion from $' in template replacement values (#2968) (#3232) +- resolve OAuth API key in buildMemoryLLMCall via modelRegistry (#2959) (#3233) +- **forensics**: read completion status from DB instead of legacy file (#3129) (#3234) +- use camelCase parameter names in execute-task and complete-slice prompts (#2933) (#3236) +- check bootstrap completeness in init wizard gate, not just .gsd/ existence (#2942) (#3237) +- specify write tool for PROJECT.md in milestone/slice prompts (#3238) +- widen completing-milestone gate to accept "None required" and similar phrasings (#2931) (#3239) +- prevent ask_user_questions from poisoning auto-mode dispatch (#2936) (#3240) +- guard null s.currentUnit in runUnitPhase closeout after stopAuto race (#2939) (#3241) +- replace `web_search` with `search-the-web` in prompts and agent frontmatter (#2920) (#3245) +- preserve milestone title in upsertMilestonePlanning when DB row pre-exists (#2879) (#3247) +- invalidate stale milestone validation on roadmap reassessment (#2957) (#3242) +- **discuss**: add roadmap fallback when DB is open but empty (#2892) (#3244) +- integrate Codex & Gemini CLI into provider routes and rate-limit handling (#2922) (#3246) +- **error-classifier**: widen STREAM_RE to cover all 7 V8 JSON parse error variants (#2916) (#3243) +- prevent git stash from destroying queued milestone CONTEXT files (#2505) (#3273) +- skip staleness rebuild in npm tarball installs (#2877) (#3250) +- **parallel**: check worktree DB for milestone completion in merge (#2812) (#3256) +- make claude-code provider stateful with full context and sidechain events (#2859) (#3254) +- **worktree**: preserve non-empty gsd.db during sync to prevent truncation (#2815) (#3255) +- align @gsd/native module type with compiled output (#3253) +- parse hook/* completed-unit keys correctly in forensics + doctor (#2826) (#3252) +- copy mcp.json into auto-mode worktrees (#2791) (#3251) +- add gsd_requirement_save and upsert path for requirement updates (#3249) +- handle pause_turn stop reason to prevent 400 errors with native web search (#2869) (#3248) +- use authoritative milestone status in web roadmap (#2807) (#3258) +- classify long-context entitlement 429 as quota_exhausted, not rate_limit (#2803) (#3257) +- **docs**: use ~/.pi/agent/extensions/ for community extension install path (#3131) (#3259) +- add disk→DB slice reconciliation in deriveStateFromDb (#2533) (#3262) +- run forensics duplicate detection before investigation (#2704) (#3260) +- skip TUI render loop on non-TTY stdout to prevent CPU burn (#3095) (#3263) +- persist forensics report context across follow-up turns (#2941) (#3261) +- invalidate workspace state on turn_end so milestones list stays current (#2706) (#3266) +- eliminate 3 recurring doctor audit false positives (#3105) (#3264) +- **web**: reconcile auto-mode state with on-disk lock in dashboard (#2705) (#3265) +- treat ghost milestones as ineligible for parallel execution (#2501) (#3268) +- redirect auto-mode to headless when stdout is piped (#2732) (#3269) +- attempt VACUUM recovery when initSchema fails with corrupt freelist (#2519) (#3270) +- resolve db_unavailable loop in worktree/symlink layouts (#2517) (#3271) +- correct OAuth fallback request shape for google_search (#2963) (#3272) +- prevent UAT stuck-loop and orphaned worktree after milestone completion (#3065) +- **mcp**: handle server names with spaces in mcp_discover (#3037) +- **gsd**: detect markdown body verdicts and guard plan-milestone against completed slices (#2960) (#3035) +- **error-classifier**: replace STREAM_RE whack-a-mole with catch-all V8 JSON.parse pattern +- type _borderColorKey as 'dim' | 'bashMode' to match ThemeColor +- **tui**: comprehensive TUI review — layout, flow, rendering, and state fixes +- **gsd**: harden codebase-map — bug fixes, UX polish, and expanded tests + +### Changed +- **state**: centralize pipeline logging through workflow logger (#3282) +- **gitignore**: exclude src/ build artifacts, scratch files, and .plans/ +- **complexity**: reclassify planning phases from standard to heavy tier + ## [2.58.0] - 2026-03-28 ### Added @@ -2154,7 +2740,24 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed - License updated to MIT -[Unreleased]: https://github.com/gsd-build/gsd-2/compare/v2.58.0...HEAD +[Unreleased]: https://github.com/gsd-build/gsd-2/compare/v2.71.0...HEAD +[2.71.0]: https://github.com/gsd-build/gsd-2/compare/v2.70.1...v2.71.0 +[2.70.1]: https://github.com/gsd-build/gsd-2/compare/v2.70.0...v2.70.1 +[2.70.0]: https://github.com/gsd-build/gsd-2/compare/v2.69.0...v2.70.0 +[2.69.0]: https://github.com/gsd-build/gsd-2/compare/v2.68.1...v2.69.0 +[2.68.1]: https://github.com/gsd-build/gsd-2/compare/v2.68.0...v2.68.1 +[2.68.0]: https://github.com/gsd-build/gsd-2/compare/v2.67.0...v2.68.0 +[2.67.0]: https://github.com/gsd-build/gsd-2/compare/v2.66.1...v2.67.0 +[2.66.1]: https://github.com/gsd-build/gsd-2/compare/v2.66.0...v2.66.1 +[2.66.0]: https://github.com/gsd-build/gsd-2/compare/v2.65.0...v2.66.0 +[2.65.0]: https://github.com/gsd-build/gsd-2/compare/v2.64.0...v2.65.0 +[2.64.0]: https://github.com/gsd-build/gsd-2/compare/v2.63.0...v2.64.0 +[2.63.0]: https://github.com/gsd-build/gsd-2/compare/v2.62.1...v2.63.0 +[2.62.1]: https://github.com/gsd-build/gsd-2/compare/v2.62.0...v2.62.1 +[2.62.0]: https://github.com/gsd-build/gsd-2/compare/v2.61.0...v2.62.0 +[2.61.0]: https://github.com/gsd-build/gsd-2/compare/v2.60.0...v2.61.0 +[2.60.0]: https://github.com/gsd-build/gsd-2/compare/v2.59.0...v2.60.0 +[2.59.0]: https://github.com/gsd-build/gsd-2/compare/v2.58.0...v2.59.0 [2.58.0]: https://github.com/gsd-build/gsd-2/compare/v2.57.0...v2.58.0 [2.57.0]: https://github.com/gsd-build/gsd-2/compare/v2.56.0...v2.57.0 [2.56.0]: https://github.com/gsd-build/gsd-2/compare/v2.55.0...v2.56.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0f0db894..335cf7842 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -146,9 +146,14 @@ The codebase is organized into these areas. All are open to contributions: | AI/LLM layer | `packages/pi-ai` | Provider integrations, model handling | | Agent core | `packages/pi-agent-core` | Agent orchestration — RFC required for changes | | Coding agent | `packages/pi-coding-agent` | The main coding agent | +| MCP server | `packages/mcp-server` | Project state tools and MCP protocol | | GSD extension | `src/resources/extensions/gsd/` | GSD workflow — RFC required for auto-mode | -| Native bindings | `native/` | Platform-specific native code | +| Other extensions | `src/resources/extensions/` | Browser, search, voice, MCP client, etc. | +| Native engine | `native/` | Rust N-API modules (grep, git, AST, etc.) | +| VS Code extension | `vscode-extension/` | Chat participant, sidebar, RPC integration | +| Web interface | `web/` | Browser-based dashboard | | CI/Build | `.github/`, `scripts/` | Workflows, build scripts | +| Documentation | `docs/` | User guides, ADRs, SDK docs | ## Review process diff --git a/README.md b/README.md index 6ecc9c053..1af83f33a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![npm version](https://img.shields.io/npm/v/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi) [![npm downloads](https://img.shields.io/npm/dm/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi) [![GitHub stars](https://img.shields.io/github/stars/gsd-build/GSD-2?style=for-the-badge&logo=github&color=181717)](https://github.com/gsd-build/GSD-2) -[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd) +[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/nKXTsAcmbT) [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE) [![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv) @@ -21,187 +21,107 @@ One command. Walk away. Come back to a built project with clean git history. > GSD now provisions a managed [RTK](https://github.com/rtk-ai/rtk) binary on supported macOS, Linux, and Windows installs to compress shell-command output in `bash`, `async_bash`, `bg_shell`, and verification flows. GSD forces `RTK_TELEMETRY_DISABLED=1` for all managed invocations. Set `GSD_RTK_DISABLED=1` to disable the integration. -> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues. +> **📋 NOTICE: New to Node on Mac?** If you installed Node.js via Homebrew, you may be running a development release instead of LTS. **[Read this guide](./docs/user-docs/node-lts-macos.md)** to pin Node 24 LTS and avoid compatibility issues. --- -## What's New in v2.52.0 +## What's New in v2.71 -### VS Code Extension & Web UI +### MCP Secure Env Collect -- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens. (#2651) -- **Dark mode contrast** — raised token floor and flattened opacity tier system for better readability. (#2734) -- **Auth token gate** — synthetic 401 on missing token, unauthenticated boot state, and recovery screen. (#2740) +- **Secure credential collection over MCP** — the new `secure_env_collect` tool uses MCP form elicitation to collect secrets (API keys, tokens) from external clients without exposing values in tool output. Masks input in interactive mode. +- **Hardened elicitation schema** — MCP elicitation schema handling is stricter, with proper validation and fallback for providers that don't support forms. -### Capability Metadata & Model Routing +### MCP Reliability -- **Capability-based model selection** — replaced model-ID pattern matching with capability metadata, making custom provider integration more reliable. (#2548) +- **Stream ordering preserved** — MCP tool output now renders in the correct order, fixing interleaved output in Claude Code and other MCP clients. +- **isError flag propagation** — workflow tool execution failures now correctly return `isError: true`, so MCP clients can distinguish success from failure. +- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates. -### Key Changes +### TUI Fixes -- **`--bare` mode** — wired across headless, pi-coding-agent, and resource-loader for minimal-output operation. -- **RPC protocol v2** — new types, init handshake with version detection, and runId generation on prompt/steer/follow_up commands. -- **PREFERENCES.md rename** — `preferences.md` renamed to `PREFERENCES.md` for consistency. (#2700, #2738) -- **Comprehensive SQLite audit** — indexes, caching, safety, and reconciliation fixes across gsd-db. -- **Unified error classifier** — three overlapping error classifiers consolidated into a single classify-decide-act pipeline. +- **Pinned output restored** — pinned output bar displays above the editor during tool execution again. +- **Turn completion cleanup** — pinned latest output is cleared on turn completion, preventing stale output from persisting. +- **Secure input masking** — extension input values are masked in interactive mode when collecting secrets. -### Key Fixes +### Reliability & Internals -- **Auto-mode stops on provider errors** — auto loop now halts after provider errors instead of retrying indefinitely. (#2762, #2764) -- **Transaction safety** — state machine guards moved inside transactions in 5 tool handlers (#2752), and `transaction()` made re-entrant. -- **Worktree seeding** — `preferences.md` seeded into auto-mode worktrees and included in worktree sync. (#2693) -- **Idle watchdog** — interactive tools exempted from stall detection (#2676), and filesystem activity no longer overrides stalled-tool detection. (#2697) -- **Milestone guards** — `allSlicesDone` guarded against vacuous truth on empty slice arrays (#2679), and `complete-milestone` dispatch blocked when validation is `needs-remediation`. (#2682) -- **Docker overhaul** — fragile setup replaced with proven container patterns. (#2716) -- **Windows** — EINVAL prevented by disabling detached process groups on Win32. (#2744) -- **Audit log** — `setLogBasePath` wired into engine init to resurrect audit logging. (#2745) +- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition. +- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers. +- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI. +- **Model routing transparency** — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner. +- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction. +- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths. -### v2.51.0 — Skills, RTK, and Verification +See the full [Changelog](./CHANGELOG.md) for details on every release. -- **`/terminal` command** — direct shell execution from the slash command interface. (#2349) -- **Managed RTK integration** — RTK binary auto-provisioned with opt-in preference and web UI toggle. (#2620) -- **Verification classes** — compliance checked before milestone completion, with classes injected into validation prompts. (#2621, #2623) -- **Skills overhaul** — 30+ new skill packs covering major frameworks, databases, and cloud platforms; curated catalog with `~/.agents/skills/` as primary directory. +
+Previous highlights (v2.70 and earlier) -### v2.50.0 — Quality Gates +- **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP +- **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically +- **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state +- **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations +- **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction +- **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions +- **Anthropic subscription routing** — auto-routed through Claude Code CLI provider with proper display names +- **5-wave state machine hardening** — critical data integrity fixes across atomic writes, event log reconciliation, session recovery +- **Discussion gate enforcement** — mechanical enforcement with fail-closed behavior +- **Slice-level parallelism** — dependency-aware parallel dispatch within a milestone +- **Persistent notification panel** — TUI overlay, widget, and web API for real-time notifications +- **MCP server** — 6 read-only project state tools for external integrations, auto-wrapup guard, and question dedup +- **Ollama extension** — first-class local LLM support via Ollama, with dynamic routing enabled by default +- **Discord bot & daemon** — dedicated daemon package, Discord bot, and headless text mode with tool calls +- **Capability-aware model routing (ADR-004)** — capability scoring, `before_model_select` hook, and task metadata extraction +- **VS Code sidebar redesign** — SCM provider, checkpoints, diagnostics panel, activity feed, workflow controls, session forking +- **`/gsd parallel watch`** — native TUI overlay for real-time worker monitoring +- **Codebase map** — automatic codebase map injection for fresh agent contexts +- **`--resume` flag** — resume previous sessions from the CLI +- **Concurrent invocation guard** — prevents overlapping auto-mode runs +- **VS Code integration** — status bar, file decorations, bash terminal, session tree, conversation history, and code lens +- **Skills overhaul** — 30+ skill packs covering major frameworks, databases, and cloud platforms +- **Single-writer state engine** — disciplined state transitions with machine guards and TOCTOU hardening +- **DB-backed planning tools** — atomic SQLite tool calls for state transitions +- **Declarative workflow engine** — YAML workflows through auto-loop +- **Doctor: worktree lifecycle checks** — validates worktree health, detects orphans, consolidates cleanup -- **Quality gates** — 8-question quality gates added to planning and completion templates, with parallel evaluation via `evaluating-gates` phase. -- **Structured error propagation** — errors wired through `UnitResult` for better diagnostics. - -### v2.49.0 — Git Trailers & Yolo Mode - -- **`--yolo` flag** — `/gsd auto --yolo` for non-interactive project init. -- **Git trailers** — GSD metadata moved from commit subject scopes to git trailers. - -### v2.48.0 — Forensics & Discussion - -- **`/gsd discuss` for queued milestones** — target milestones still in the queue. (#2349) -- **Enhanced forensics** — journal and activity log awareness added to `/gsd forensics`. - -### v2.47.0 — External Providers - -- **External tool execution mode** — `externalToolExecution` mode for external providers in agent-core. -- **Claude Code CLI provider** — new provider extension for Claude Code CLI. (#2382) - -### Previous highlights (v2.42–v2.46) - -- **Single-writer state engine** — disciplined state transitions with machine guards, actor identity, reversibility, and TOCTOU hardening. (#2494) -- **`/gsd rethink`** — conversational project reorganization. (#2459) -- **`/gsd mcp`** — MCP server status and connectivity. (#2362) -- **Complete offline mode** — fully offline with local models. (#2429) -- **Global KNOWLEDGE.md injection** — cross-project knowledge via `~/.gsd/agent/KNOWLEDGE.md`. (#2331) -- **Mobile-responsive web UI** — browser interface works on phones and tablets. (#2354) -- **Default isolation mode changed to `none`** — set `git.isolation: worktree` explicitly if needed. (#2481) -- **Non-API-key provider extensions** — support for Claude Code CLI and similar providers. (#2382) -- **Docker sandbox template** — official Docker template for isolated auto mode. (#2360) -- **DB-backed planning tools** — write-side state transitions use atomic SQLite tool calls. (#2141) -- **Declarative workflow engine** — YAML workflows through auto-loop. (#2024) -- **`/gsd fast`** — toggle service tier for prioritized API routing. (#1862) - ---- - -## What's New in v2.41.0 - -### New Features - -- **Browser-based web interface** — run GSD from the browser with `gsd --web`. Full project management, real-time progress, and multi-project support via server-sent events. (#1717) -- **Doctor: worktree lifecycle checks** — `/gsd doctor` now validates worktree health, detects orphaned worktrees, consolidates cleanup, and enhances `/worktree list` with lifecycle status. (#1814) -- **CI: docs-only PR detection** — PRs that only change documentation skip build and test steps, with a new prompt injection scan for security. (#1699) -- **Custom Models guide** — new documentation for adding custom providers (Ollama, vLLM, LM Studio, proxies) via `models.json`. (#1670) - -### Data Loss Prevention (Critical Fixes) - -This release includes 7 fixes preventing silent data loss in auto-mode: - -- **Hallucination guard** — execute-task agents that complete with zero tool calls are now rejected as hallucinated. Previously, agents could produce detailed but fabricated summaries without writing any code, wasting ~$25/milestone. (#1838) -- **Merge anchor verification** — before deleting a milestone worktree/branch, GSD now verifies the code is actually on the integration branch. Prevents orphaning commits when squash-merge produces an empty diff. (#1829) -- **Dirty working tree detection** — `nativeMergeSquash` now distinguishes dirty-tree rejections from content conflicts, preventing silent commit loss when synced `.gsd/` files block the merge. (#1752) -- **Doctor cleanup safety** — the `orphaned_completed_units` check no longer auto-fixes during post-task health checks. Previously, timing races could cause the doctor to remove valid completion keys, reverting users to earlier tasks. (#1825) -- **Root file reverse-sync** — worktree teardown now syncs root-level `.gsd/` files (PROJECT.md, REQUIREMENTS.md, completed-units.json) back to the project root. Previously these were lost on milestone closeout. (#1831) -- **Empty merge guard** — milestone branches with unanchored code changes are preserved instead of deleted when squash-merge produces nothing to commit. (#1755) -- **Crash-safe task closeout** — orphaned checkboxes in PLAN.md are unchecked on retry, preventing phantom task completion. (#1759) - -### Auto-Mode Stability - -- **Terminal hang fix** — `stopAuto()` now resolves pending promises, preventing the terminal from freezing permanently after stopping auto-mode. (#1818) -- **Signal handler coverage** — SIGHUP and SIGINT now clean up lock files, not just SIGTERM. Prevents stranded locks on VS-Code crash. (#1821) -- **Needs-discussion routing** — milestones in `needs-discussion` phase now route to the smart entry UI instead of hard-stopping, breaking the infinite loop. (#1820) -- **Infrastructure error handling** — auto-mode stops immediately on ENOSPC, ENOMEM, and similar unrecoverable errors instead of retrying. (#1780) -- **Dependency-aware dispatch** — slice dispatch now uses declared `depends_on` instead of positional ordering. (#1770) -- **Queue mode depth verification** — the write gate now processes depth verification in queue mode, fixing a deadlock where CONTEXT.md writes were permanently blocked. (#1823) - -### Roadmap Parser Improvements - -- **Table format support** — roadmaps using markdown tables (`| S01 | Title | Risk | Status |`) are now parsed correctly. (#1741) -- **Prose header fallback** — when `## Slices` contains H3 headers instead of checkboxes, the prose parser is invoked as a fallback. (#1744) -- **Completion marker detection** — prose headers with `✓` or `(Complete)` markers are correctly identified as done. (#1816) -- **Zero-slice stub handling** — stub roadmaps from `/gsd queue` return `pre-planning` instead of `blocked`. (#1826) -- **Immediate roadmap fix** — roadmap checkbox and UAT stub are fixed immediately after last task instead of deferring to `complete-slice`. (#1819) - -### State & Git Improvements - -- **CONTEXT-DRAFT.md fallback** — `depends_on` is read from CONTEXT-DRAFT.md when CONTEXT.md doesn't exist, preventing draft milestones from being promoted past dependency constraints. (#1743) -- **Unborn branch support** — `nativeBranchExists` handles repos with zero commits, preventing dispatch deadlock on new repos. (#1815) -- **Ghost milestone detection** — empty `.gsd/milestones/` directories are skipped instead of crashing `deriveState()`. (#1817) -- **Default branch detection** — milestone merge detects `master` vs `main` instead of hardcoding. (#1669) -- **Milestone title extraction** — titles are pulled from CONTEXT.md headings when no ROADMAP exists. (#1729) - -### Windows & Platform - -- **Windows path handling** — 8.3 short paths, `pathToFileURL` for ESM imports, and `realpathSync.native` fixes across the test suite and verification gate. (#1804) -- **DEP0190 fix** — `spawnSync` deprecation warning eliminated by passing commands to shell explicitly. (#1827) -- **Web build skip on Windows** — Next.js webpack EPERM errors on system directories are handled gracefully. - -### Developer Experience - -- **@ file finder fix** — typing `@` no longer freezes the TUI. The fix adds debounce, dedup, and empty-query short-circuit. (#1832) -- **Tool-call loop guard** — detects and breaks infinite tool-call loops within a single unit, preventing stack overflow. (#1801) -- **Completion deferral fix** — roadmap checkbox and UAT stub are fixed at task level, closing the fragile handoff window between last task and `complete-slice`. (#1819) - -See the full [Changelog](./CHANGELOG.md) for all 70+ fixes in this release. - -### Previous highlights (v2.39–v2.41) - -- **Browser-based web interface** — run GSD from the browser with `gsd --web` -- **GitHub sync extension** — auto-sync milestones to GitHub Issues, PRs, and Milestones -- **Skill tool resolution** — skills auto-activate in dispatched prompts -- **Health check phase 2** — real-time doctor issues in dashboard and visualizer -- **Forensics upgrade** — full-access GSD debugger with anomaly detection -- **7 data-loss prevention fixes** — hallucination guard, merge anchor verification, dirty tree detection, and more -- **Pipeline decomposition** — auto-loop rewritten as linear phase pipeline -- **Sliding-window stuck detection** — pattern-aware, fewer false positives -- **Data-loss recovery** — automatic detection and recovery from v2.30–v2.38 migration issues +
--- ## Documentation -Full documentation is available at **[gsd.build](https://gsd.build)** (powered by Mintlify) and in the [`docs/`](./docs/) directory: +Full documentation is in the [`docs/`](./docs/) directory: -- **[Getting Started](./docs/getting-started.md)** — install, first run, basic usage -- **[Auto Mode](./docs/auto-mode.md)** — autonomous execution deep-dive -- **[Configuration](./docs/configuration.md)** — all preferences, models, git, and hooks -- **[Custom Models](./docs/custom-models.md)** — add custom providers (Ollama, vLLM, LM Studio, proxies) -- **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing -- **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections -- **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior -- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously -- **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts -- **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring -- **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts -- **[Architecture](./docs/architecture.md)** — system design and dispatch pipeline -- **[Troubleshooting](./docs/troubleshooting.md)** — common issues, doctor, forensics, recovery -- **[CI/CD Pipeline](./docs/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod) -- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration -- **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status -- **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed -- **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure -- **[Web Interface](./docs/web-interface.md)** — browser-based project management and real-time progress -- **[Pipeline Simplification (ADR-003)](./docs/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion +### User Guides + +- **[Getting Started](./docs/user-docs/getting-started.md)** — install, first run, basic usage +- **[Auto Mode](./docs/user-docs/auto-mode.md)** — autonomous execution deep-dive +- **[Configuration](./docs/user-docs/configuration.md)** — all preferences, models, git, and hooks +- **[Custom Models](./docs/user-docs/custom-models.md)** — add custom providers (Ollama, vLLM, LM Studio, proxies) +- **[Token Optimization](./docs/user-docs/token-optimization.md)** — profiles, context compression, complexity routing +- **[Cost Management](./docs/user-docs/cost-management.md)** — budgets, tracking, projections +- **[Git Strategy](./docs/user-docs/git-strategy.md)** — worktree isolation, branching, merge behavior +- **[Parallel Orchestration](./docs/user-docs/parallel-orchestration.md)** — run multiple milestones simultaneously +- **[Working in Teams](./docs/user-docs/working-in-teams.md)** — unique IDs, shared artifacts +- **[Skills](./docs/user-docs/skills.md)** — bundled skills, discovery, custom authoring +- **[Commands Reference](./docs/user-docs/commands.md)** — all commands and keyboard shortcuts +- **[Troubleshooting](./docs/user-docs/troubleshooting.md)** — common issues, doctor, forensics, recovery +- **[Visualizer](./docs/user-docs/visualizer.md)** — workflow visualizer with stats and discussion status +- **[Remote Questions](./docs/user-docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed +- **[Dynamic Model Routing](./docs/user-docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure +- **[Web Interface](./docs/user-docs/web-interface.md)** — browser-based project management and real-time progress +- **[Migration from v1](./docs/user-docs/migration.md)** — `.planning` → `.gsd` migration - **[Docker Sandbox](./docker/README.md)** — run GSD auto mode in an isolated Docker container -- **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration + +### Developer Docs + +- **[Architecture](./docs/dev/architecture.md)** — system design and dispatch pipeline +- **[CI/CD Pipeline](./docs/dev/ci-cd-pipeline.md)** — three-stage promotion pipeline (Dev → Test → Prod) +- **[Pipeline Simplification (ADR-003)](./docs/dev/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion +- **[VS Code Extension](./vscode-extension/README.md)** — chat participant, sidebar dashboard, RPC integration --- @@ -417,7 +337,7 @@ gsd headless query gsd headless dispatch plan ``` -Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed. +Headless auto-responds to interactive prompts, detects completion, and exits with structured codes: `0` complete, `1` error/timeout, `2` blocked. Auto-restarts on crash with exponential backoff. Use `gsd headless query` for instant, machine-readable state inspection — returns phase, next dispatch preview, and parallel worker costs as a single JSON object without spawning an LLM session. Pair with [remote questions](./docs/user-docs/remote-questions.md) to route decisions to Slack or Discord when human input is needed. **Multi-session orchestration** — headless mode supports file-based IPC in `.gsd/parallel/` for coordinating multiple GSD workers across milestones. Build orchestrators that spawn, monitor, and budget-cap a fleet of GSD workers. @@ -590,9 +510,8 @@ auto_report: true | `verification_commands`| Array of shell commands to run after task execution (e.g., `["npm run lint", "npm run test"]`) | | `verification_auto_fix`| Auto-retry on verification failures (default: true) | | `verification_max_retries` | Max retries for verification failures (default: 2) | -| `require_slice_discussion` | Pause auto-mode before each slice for human discussion review | +| `phases.require_slice_discussion` | Pause auto-mode before each slice for human discussion review | | `auto_report` | Auto-generate HTML reports after milestone completion (default: true) | -| `searchExcludeDirs` | Directories to exclude from `@` file autocomplete (e.g., `["node_modules", ".git", "dist"]`) | ### Agent Instructions @@ -622,11 +541,11 @@ token_profile: budget # or balanced (default), quality **Budget pressure** graduates model downgrading as you approach your budget ceiling — 50%, 75%, and 90% thresholds progressively shift work to cheaper tiers. -See the full [Token Optimization Guide](./docs/token-optimization.md) for details. +See the full [Token Optimization Guide](./docs/user-docs/token-optimization.md) for details. ### Bundled Tools -GSD ships with 19 extensions, all loaded automatically: +GSD ships with 24 extensions, all loaded automatically: | Extension | What it provides | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | @@ -648,17 +567,24 @@ GSD ships with 19 extensions, all loaded automatically: | **Remote Questions** | Route decisions to Slack/Discord when human input is needed in headless/CI mode | | **Universal Config** | Discover and import MCP servers and rules from other AI coding tools | | **AWS Auth** | Automatic Bedrock credential refresh for AWS-hosted models | -| **TTSR** | Tool-use type-safe runtime validation | +| **Ollama** | First-class local LLM support via Ollama | +| **Claude Code CLI** | External provider extension for Claude Code CLI | +| **cmux** | Claude multiplexer integration — desktop notifications, sidebar metadata, visual subagent splits | +| **GitHub Sync** | Auto-sync milestones to GitHub Issues, PRs, and Milestones | +| **LSP** | Language Server Protocol — diagnostics, definitions, references, hover, rename | +| **TTSR** | Tool-triggered system rules — conditional context injection based on tool usage | ### Bundled Agents -Three specialized subagents for delegated work: +Five specialized subagents for delegated work: -| Agent | Role | -| -------------- | ------------------------------------------------------------ | -| **Scout** | Fast codebase recon — returns compressed context for handoff | -| **Researcher** | Web research — finds and synthesizes current information | -| **Worker** | General-purpose execution in an isolated context window | +| Agent | Role | +| ------------------- | ------------------------------------------------------------ | +| **Scout** | Fast codebase recon — returns compressed context for handoff | +| **Researcher** | Web research — finds and synthesizes current information | +| **Worker** | General-purpose execution in an isolated context window | +| **JavaScript Pro** | JavaScript-specialized execution and debugging | +| **TypeScript Pro** | TypeScript-specialized execution and debugging | --- @@ -733,9 +659,8 @@ gsd (CLI binary) ├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/ └─ src/resources/ ├─ extensions/gsd/ Core GSD extension (auto, state, commands, ...) - ├─ extensions/... 18 supporting extensions - ├─ agents/ scout, researcher, worker - ├─ AGENTS.md Agent routing instructions + ├─ extensions/... 21 supporting extensions + ├─ agents/ scout, researcher, worker, javascript-pro, typescript-pro └─ GSD-WORKFLOW.md Manual bootstrap protocol ``` diff --git a/docs/README.md b/docs/README.md index c6c3b4692..e74a67039 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,51 +4,67 @@ Welcome to the GSD documentation. This covers everything from getting started to ## User Documentation +Guides for installing, configuring, and using GSD day-to-day. Located in [`user-docs/`](./user-docs/). + | Guide | Description | |-------|-------------| -| [Getting Started](./getting-started.md) | Installation, first run, and basic usage | -| [Auto Mode](./auto-mode.md) | How autonomous execution works — the state machine, crash recovery, and steering | -| [Commands Reference](./commands.md) | All commands, keyboard shortcuts, and CLI flags | -| [Remote Questions](./remote-questions.md) | Discord and Slack integration for headless auto-mode | -| [Configuration](./configuration.md) | Preferences, model selection, git settings, and token profiles | -| [Custom Models](./custom-models.md) | Add custom providers (Ollama, vLLM, LM Studio, proxies) via models.json | -| [Token Optimization](./token-optimization.md) | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) | -| [Dynamic Model Routing](./dynamic-model-routing.md) | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) | -| [Captures & Triage](./captures-triage.md) | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) | -| [Workflow Visualizer](./visualizer.md) | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) | -| [Cost Management](./cost-management.md) | Budget ceilings, cost tracking, projections, and enforcement modes | -| [Git Strategy](./git-strategy.md) | Worktree isolation, branching model, and merge behavior | -| [Parallel Orchestration](./parallel-orchestration.md) | Run multiple milestones simultaneously with worker isolation and coordination | -| [Working in Teams](./working-in-teams.md) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts | -| [Skills](./skills.md) | Bundled skills, skill discovery, and custom skill authoring | -| [Migration from v1](./migration.md) | Migrating `.planning` directories from the original GSD | -| [Troubleshooting](./troubleshooting.md) | Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures | -| [Web Interface](./web-interface.md) | Browser-based project management with `gsd --web` (v2.41) | +| [Getting Started](./user-docs/getting-started.md) | Installation, first run, and basic usage | +| [Auto Mode](./user-docs/auto-mode.md) | How autonomous execution works — the state machine, crash recovery, and steering | +| [Commands Reference](./user-docs/commands.md) | All commands, keyboard shortcuts, and CLI flags | +| [Remote Questions](./user-docs/remote-questions.md) | Discord and Slack integration for headless auto-mode | +| [Configuration](./user-docs/configuration.md) | Preferences, model selection, git settings, and token profiles | +| [Provider Setup](./user-docs/providers.md) | Step-by-step setup for OpenRouter, Ollama, LM Studio, vLLM, and all supported providers | +| [Custom Models](./user-docs/custom-models.md) | Advanced model configuration — models.json schema, compat flags, overrides | +| [Token Optimization](./user-docs/token-optimization.md) | Token profiles, context compression, complexity routing, and adaptive learning (v2.17) | +| [Dynamic Model Routing](./user-docs/dynamic-model-routing.md) | Complexity-based model selection, cost tables, escalation, and budget pressure (v2.19) | +| [Captures & Triage](./user-docs/captures-triage.md) | Fire-and-forget thought capture during auto-mode with automated triage (v2.19) | +| [Workflow Visualizer](./user-docs/visualizer.md) | Interactive TUI overlay for progress, dependencies, metrics, and timeline (v2.19) | +| [Cost Management](./user-docs/cost-management.md) | Budget ceilings, cost tracking, projections, and enforcement modes | +| [Git Strategy](./user-docs/git-strategy.md) | Worktree isolation, branching model, and merge behavior | +| [Parallel Orchestration](./user-docs/parallel-orchestration.md) | Run multiple milestones simultaneously with worker isolation and coordination | +| [Working in Teams](./user-docs/working-in-teams.md) | Unique milestone IDs, `.gitignore` setup, and shared planning artifacts | +| [Skills](./user-docs/skills.md) | Bundled skills, skill discovery, and custom skill authoring | +| [Migration from v1](./user-docs/migration.md) | Migrating `.planning` directories from the original GSD | +| [Troubleshooting](./user-docs/troubleshooting.md) | Common issues, `/gsd doctor` (real-time visibility v2.40), `/gsd forensics` (full debugger v2.40), and recovery procedures | +| [Web Interface](./user-docs/web-interface.md) | Browser-based project management with `gsd --web` (v2.41) | | [VS Code Extension](../vscode-extension/README.md) | Chat participant, sidebar dashboard, and RPC integration for VS Code | ## Architecture & Internals +Design documents, ADRs, and internal references. Located in [`dev/`](./dev/). + | Guide | Description | |-------|-------------| -| [Architecture Overview](./architecture.md) | System design, extension model, state-on-disk, and dispatch pipeline | +| [Architecture Overview](./dev/architecture.md) | System design, extension model, state-on-disk, and dispatch pipeline | | [Native Engine](../native/README.md) | Rust N-API modules for performance-critical operations | -| [ADR-001: Branchless Worktree Architecture](./ADR-001-branchless-worktree-architecture.md) | Decision record for the v2.14 git architecture | -| [ADR-003: Pipeline Simplification](./ADR-003-pipeline-simplification.md) | Research merged into planning, mechanical completion (v2.30) | -| [ADR-004: Capability-Aware Model Routing](./ADR-004-capability-aware-model-routing.md) | Extend routing from tier/cost selection to task-capability matching | +| [ADR-001: Branchless Worktree Architecture](./dev/ADR-001-branchless-worktree-architecture.md) | Decision record for the v2.14 git architecture | +| [ADR-003: Pipeline Simplification](./dev/ADR-003-pipeline-simplification.md) | Research merged into planning, mechanical completion (v2.30) | +| [ADR-004: Capability-Aware Model Routing](./dev/ADR-004-capability-aware-model-routing.md) | Extend routing from tier/cost selection to task-capability matching | +| [ADR-007: Model Catalog Split](./dev/ADR-007-model-catalog-split.md) | Separate model metadata from routing logic for extensibility | +| [ADR-008: GSD Tools over MCP](./dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md) | Native tools over MCP for provider parity | +| [ADR-008: Implementation Plan](./dev/ADR-008-IMPLEMENTATION-PLAN.md) | Implementation plan for ADR-008 | +| [Context Optimization Opportunities](./dev/pi-context-optimization-opportunities.md) | Analysis of context window usage and optimization strategies | +| [File System Map](./dev/FILE-SYSTEM-MAP.md) | Complete file system reference | +| [CI/CD Pipeline](./dev/ci-cd-pipeline.md) | Continuous integration and deployment pipeline | +| [Frontier Techniques](./dev/FRONTIER-TECHNIQUES.md) | Advanced techniques and research | +| [PRD: Branchless Worktree](./dev/PRD-branchless-worktree-architecture.md) | Product requirements for branchless worktree architecture | +| [Agent Knowledge Index](./dev/agent-knowledge-index.md) | Index of agent knowledge resources | ## Pi SDK Documentation -These guides cover the underlying Pi SDK that GSD is built on. Useful if you want to extend GSD or build your own agent application. +Guides for the underlying Pi SDK that GSD is built on. Located in [`dev/`](./dev/). | Guide | Description | |-------|-------------| -| [What is Pi](./what-is-pi/README.md) | Core concepts — modes, agent loop, sessions, tools, providers | -| [Extending Pi](./extending-pi/README.md) | Building extensions — tools, commands, UI, events, state | -| [Context & Hooks](./context-and-hooks/README.md) | Context pipeline, hook reference, inter-extension communication | -| [Pi UI / TUI](./pi-ui-tui/README.md) | Terminal UI components, theming, keyboard input, rendering | +| [What is Pi](./dev/what-is-pi/README.md) | Core concepts — modes, agent loop, sessions, tools, providers | +| [Extending Pi](./dev/extending-pi/README.md) | Building extensions — tools, commands, UI, events, state | +| [Context & Hooks](./dev/context-and-hooks/README.md) | Context pipeline, hook reference, inter-extension communication | +| [Pi UI / TUI](./dev/pi-ui-tui/README.md) | Terminal UI components, theming, keyboard input, rendering | ## Research | Guide | Description | |-------|-------------| -| [Building Coding Agents](./building-coding-agents/README.md) | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs | +| [Building Coding Agents](./dev/building-coding-agents/README.md) | Research notes on agent design — decomposition, context engineering, cost/quality tradeoffs | +| [Proposals](./dev/proposals/) | Feature proposals and workflow definitions | +| [Superpowers](./dev/superpowers/) | Plans and specs for superpower features | diff --git a/docs/ADR-001-branchless-worktree-architecture.md b/docs/dev/ADR-001-branchless-worktree-architecture.md similarity index 100% rename from docs/ADR-001-branchless-worktree-architecture.md rename to docs/dev/ADR-001-branchless-worktree-architecture.md diff --git a/docs/ADR-003-pipeline-simplification.md b/docs/dev/ADR-003-pipeline-simplification.md similarity index 100% rename from docs/ADR-003-pipeline-simplification.md rename to docs/dev/ADR-003-pipeline-simplification.md diff --git a/docs/ADR-004-capability-aware-model-routing.md b/docs/dev/ADR-004-capability-aware-model-routing.md similarity index 99% rename from docs/ADR-004-capability-aware-model-routing.md rename to docs/dev/ADR-004-capability-aware-model-routing.md index 93d28f862..c2ce3d2d2 100644 --- a/docs/ADR-004-capability-aware-model-routing.md +++ b/docs/dev/ADR-004-capability-aware-model-routing.md @@ -1,8 +1,8 @@ # ADR-004: Capability-Aware Model Routing -**Status:** Proposed (Revised) +**Status:** Implemented (Phase 2) **Date:** 2026-03-26 -**Revised:** 2026-03-26 +**Revised:** 2026-04-03 **Deciders:** Jeremy McSpadden **Related:** ADR-003 (pipeline simplification), [Issue #2655](https://github.com/gsd-build/gsd-2/issues/2655), `docs/dynamic-model-routing.md` diff --git a/docs/dev/ADR-005-multi-model-provider-tool-strategy.md b/docs/dev/ADR-005-multi-model-provider-tool-strategy.md new file mode 100644 index 000000000..bdf00706a --- /dev/null +++ b/docs/dev/ADR-005-multi-model-provider-tool-strategy.md @@ -0,0 +1,67 @@ +# ADR-005: Multi-Model, Multi-Provider, and Tool Strategy + +**Status:** Accepted +**Date:** 2026-03-27 +**Deciders:** Jeremy McSpadden +**Related:** ADR-004 (capability-aware model routing), ADR-003 (pipeline simplification), [Issue #2790](https://github.com/gsd-build/gsd-2/issues/2790) + +## Context + +PR #2755 lands capability-aware model routing (ADR-004), extending the router from a one-dimensional complexity-tier system to a two-dimensional system that scores models across 7 capability dimensions. GSD can now intelligently pick the best model for a task from a heterogeneous pool. + +But model selection is only one piece of the multi-model puzzle. The system faces structural gaps as users configure diverse provider pools: + +1. **Tool compatibility is assumed, not verified** — Every registered tool is sent to every model regardless of provider capabilities. +2. **No tool-aware model routing** — ADR-004 scores 7 capability dimensions but none encode whether a model can actually use the tools a task requires. +3. **Provider failover loses context fidelity** — Cross-provider switches silently degrade conversation quality (thinking blocks dropped, tool IDs remapped). +4. **Tool availability is static across a session** — The same tools are presented regardless of the selected model's capabilities. +5. **No provider capability registry** — Provider quirks are scattered across `*-shared.ts` files. + +## Decision + +Introduce a provider capability registry and tool compatibility layer that integrates with ADR-004's capability-aware model router. + +### Design Principles + +1. **Layered on ADR-004, not replacing it.** Capability scoring remains primary. This adds tool compatibility as a hard constraint. +2. **Hard constraints filter; soft scores rank.** Tool support is binary — it filters the eligible set before scoring. +3. **Provider knowledge is declarative, not scattered.** Provider capabilities move to an explicit registry. +4. **Tool sets adapt to model capabilities.** Active tool set adjusts when the router selects a different model. +5. **Graceful degradation preserved.** Unknown providers get full tool access — same as today. + +### Implementation Phases + +1. **Phase 1:** Provider Capabilities Registry (`packages/pi-ai/src/providers/provider-capabilities.ts`) +2. **Phase 2:** Tool Compatibility Metadata (extend `ToolDefinition` with `compatibility` field) +3. **Phase 3:** Tool-compatibility filter in routing pipeline + `ProviderSwitchReport` in `transform-messages.ts` +4. **Phase 4:** `adjustToolSet` extension hook + +## Consequences + +### Positive +- Eliminates silent tool failures when routing to incompatible providers +- Makes cross-provider routing safe by default +- Provider knowledge becomes queryable (registry vs scattered code) +- Cross-provider context loss becomes visible via `ProviderSwitchReport` + +### Negative +- More metadata to maintain (provider capabilities, tool compatibility) +- Tool filtering adds a pipeline step (sub-millisecond, O(models × tools)) +- Risk of over-filtering (mitigated: opt-in per tool, permissive defaults) + +### Neutral +- Existing behavior unchanged without metadata +- ADR-004 scoring is unmodified +- Provider implementations simplify over time as registry replaces scattered workarounds + +## Appendix: Architecture Reference + +| File | Role | +|------|------| +| `packages/pi-ai/src/providers/register-builtins.ts` | Provider registration | +| `packages/pi-ai/src/providers/*-shared.ts` | Provider-specific handling | +| `packages/pi-ai/src/providers/transform-messages.ts` | Cross-provider normalization | +| `packages/pi-ai/src/types.ts` | Core types | +| `packages/pi-coding-agent/src/core/extensions/types.ts` | ToolDefinition, ExtensionAPI | +| `src/resources/extensions/gsd/model-router.ts` | Capability scoring (ADR-004) | +| `src/resources/extensions/gsd/auto-model-selection.ts` | Model selection orchestration | diff --git a/docs/dev/ADR-007-model-catalog-split.md b/docs/dev/ADR-007-model-catalog-split.md new file mode 100644 index 000000000..8ed426add --- /dev/null +++ b/docs/dev/ADR-007-model-catalog-split.md @@ -0,0 +1,285 @@ +# ADR-007: Model Catalog Split and Provider API Encapsulation + +**Status:** Proposed +**Date:** 2026-04-03 +**Deciders:** Jeremy McSpadden +**Related:** ADR-004 (capability-aware model routing), [ADR-005](https://github.com/gsd-build/gsd-2/issues/2790), [ADR-006](https://github.com/gsd-build/gsd-2/issues/2995), `packages/pi-ai/src/providers/`, `packages/pi-ai/src/models.ts` + +## Context + +The model/provider system in `pi-ai` has two structural problems worth fixing — but the system is **not fundamentally broken**. The heavy lifting (lazy SDK imports, registry-based dispatch, extension-based registration) is already well-designed. This ADR targets the two areas where the current design creates real friction without proposing unnecessary runtime changes. + +### Current Architecture + +``` +stream.ts + └─ import "./providers/register-builtins.js" ← side-effect import at load time + ├─ import anthropic.ts (6.8 KB) + ├─ import anthropic-vertex.ts (3.9 KB) + ├─ import openai-completions.ts (26 KB) + ├─ import openai-responses.ts (6.4 KB) + ├─ import openai-codex-responses.ts (29 KB) + ├─ import azure-openai-responses.ts (7.8 KB) + ├─ import google.ts (13.6 KB) + ├─ import google-vertex.ts (14.5 KB) + ├─ import google-gemini-cli.ts (30 KB) + ├─ import mistral.ts (18.9 KB) + └─ amazon-bedrock.ts (24 KB) ← only lazy-loaded provider + +models.ts + └─ import models.generated.ts ← 13,848 lines, ALL providers, loaded at init + └─ import models.custom.ts ← 197 lines, additional providers +``` + +### What Already Works Well + +1. **SDK lazy loading.** Every provider file uses `async function getXxxClass()` with a cached dynamic `import()`. The heavy npm packages (`@anthropic-ai/sdk`, `openai`, `@google/genai`, `@aws-sdk/*`, `@mistralai/*`) are only loaded on first API call. This is where the real startup cost would be — and it's already handled. + +2. **Registry-based dispatch.** `api-registry.ts` cleanly maps API types to stream functions. Callers use `stream(model, context)` and the registry routes to the right provider. This pattern is sound. + +3. **Extension registration.** Ollama and Claude Code CLI register via `registerApiProvider()` at runtime. This extensibility point works correctly. + +4. **Provider implementation code loading (~200KB total).** While all providers load eagerly, V8 parses local `.js` files in single-digit milliseconds each. The total parse cost for all provider files is ~10-30ms — not a user-visible bottleneck on a CLI that's about to make a multi-second API call anyway. + +### What's Actually Worth Fixing + +#### Problem 1: Monolithic model catalog — developer experience, not runtime + +`models.generated.ts` is **13,848 lines in a single file**. This creates real friction: + +- **PR reviews are painful.** When the generation script runs, the diff is a wall of changes across unrelated providers. Reviewers can't tell what actually changed for a specific provider. +- **Navigation is slow.** Finding a specific model requires scrolling or searching through thousands of lines of static object literals. +- **Merge conflicts are frequent.** Any two PRs that touch model generation will conflict on the same monolithic file. +- **Git blame is useless.** Every line was "last changed" by the generation script, obscuring the history of individual provider additions. + +The runtime cost of loading all model definitions is negligible — a Map of ~200 model objects is maybe 50-100KB of heap. The problem is purely about code organization and developer workflow. + +#### Problem 2: Barrel export leaks provider internals — API design + +`packages/pi-ai/src/index.ts` re-exports every provider module's internals: + +```typescript +export * from "./providers/anthropic.js"; +export * from "./providers/google.js"; +export * from "./providers/google-gemini-cli.js"; +export * from "./providers/google-vertex.js"; +export * from "./providers/mistral.js"; +export * from "./providers/openai-completions.js"; +export * from "./providers/openai-responses.js"; +// ... etc +``` + +This is a public API problem: + +- **Consumers can bypass the registry.** Any code that `import { streamAnthropic } from "pi-ai"` has a direct dependency on an implementation detail that should be internal. +- **Refactoring is blocked.** Renaming a function inside a provider file is a breaking change because it's re-exported from the package root. +- **API surface is unnecessarily large.** The public API should be `stream()`, `streamSimple()`, `registerApiProvider()`, model utilities, and types. Provider-specific stream functions are implementation details. + +### What Is NOT Worth Changing + +**Lazy provider loading (converting `register-builtins.ts` to async on-demand loading).** This was considered and rejected because: + +1. **The SDKs are already lazy.** The heavy cost is handled. Provider implementation code (~200KB of local `.js`) parses in ~10-30ms total. +2. **Async resolution adds complexity to the hot path.** `stream.ts` currently does a synchronous `Map.get()`. Making `resolveApiProvider` async adds a microtask hop to every API call — not just the first. Small but measurable, and for no user-visible gain. +3. **High blast radius, low payoff.** Touching `stream.ts`, `api-registry.ts`, and the registration lifecycle simultaneously risks regressions in the core streaming path for an optimization that wouldn't show up in profiling. +4. **Bedrock's lazy loading is a special case, not a template.** It exists because `@aws-sdk/client-bedrock-runtime` is uniquely massive. Generalizing this pattern to providers where the SDK is already lazy-imported doesn't compound the benefit. + +## Decision + +**Make two targeted improvements to code organization and API hygiene. Do not change runtime loading behavior.** + +### Change 1: Split `models.generated.ts` into per-provider files + +Replace the monolithic 13,848-line generated file with per-provider files: + +``` +packages/pi-ai/src/models/ + ├── index.ts ← re-exports combined registry, same public API + ├── generated/ + │ ├── anthropic.ts ← Anthropic model definitions + │ ├── openai.ts ← OpenAI model definitions + │ ├── google.ts ← Google model definitions + │ ├── mistral.ts ← Mistral model definitions + │ ├── amazon-bedrock.ts ← Bedrock model definitions + │ ├── groq.ts ← Groq model definitions + │ ├── xai.ts ← xAI model definitions + │ ├── cerebras.ts ← Cerebras model definitions + │ ├── openrouter.ts ← OpenRouter model definitions + │ └── ... ← one file per provider in the catalog + ├── custom.ts ← replaces models.custom.ts (unchanged content) + └── capability-patches.ts ← CAPABILITY_PATCHES extracted for clarity +``` + +**`models/index.ts` keeps the exact same synchronous public API:** + +```typescript +// models/index.ts +// GSD-2 — Model registry (split by provider for maintainability) + +import { ANTHROPIC_MODELS } from "./generated/anthropic.js"; +import { OPENAI_MODELS } from "./generated/openai.js"; +import { GOOGLE_MODELS } from "./generated/google.js"; +// ... one import per provider + +import { CUSTOM_MODELS } from "./custom.js"; +import { CAPABILITY_PATCHES, applyCapabilityPatches } from "./capability-patches.js"; +import type { Api, KnownProvider, Model, Usage } from "../types.js"; + +// Combine all generated models into single registry — same as today +const MODELS = { + ...ANTHROPIC_MODELS, + ...OPENAI_MODELS, + ...GOOGLE_MODELS, + // ... +}; + +// Rest of the file is identical to current models.ts: +// modelRegistry Map construction, capability patch application, +// getModel(), getProviders(), getModels(), calculateCost(), +// supportsXhigh(), modelsAreEqual() +``` + +**Key constraint: loading stays synchronous and eager.** All model files are statically imported. The Map is built at module init exactly as today. No async, no lazy loading, no runtime behavior change. This is purely a file organization change. + +**Update `generate-models.ts`** to emit one file per provider instead of a single `models.generated.ts`. The script already groups models by provider internally — it just needs to write separate files instead of one. + +#### Why this matters + +| Before | After | +|--------|-------| +| PR diffs show 13K-line file changes | PR diffs scoped to the provider that changed | +| Merge conflicts on any concurrent model update | Conflicts only when same provider is touched | +| `git blame` shows "regenerate models" for every line | `git blame` shows per-provider history | +| Finding a model = search through 13K lines | Finding a model = open the provider file | +| One reviewer must understand all providers | Reviewers only need context for affected provider | + +### Change 2: Stop barrel-exporting provider internals + +**Update `packages/pi-ai/src/index.ts`:** + +```typescript +// Before (current — 17 re-exports including all providers): +export * from "./providers/anthropic.js"; +export * from "./providers/azure-openai-responses.js"; +export * from "./providers/google.js"; +export * from "./providers/google-gemini-cli.js"; +export * from "./providers/google-vertex.js"; +export * from "./providers/mistral.js"; +export * from "./providers/openai-completions.js"; +export * from "./providers/openai-responses.js"; +export * from "./providers/register-builtins.js"; +// ... + +// After (clean public API): +export * from "./api-registry.js"; +export * from "./env-api-keys.js"; +export * from "./models/index.js"; +export * from "./providers/register-builtins.js"; // resetApiProviders() is public +export * from "./stream.js"; +export * from "./types.js"; +export * from "./utils/event-stream.js"; +export * from "./utils/json-parse.js"; +export type { OAuthAuthInfo, OAuthCredentials, /* ... */ } from "./utils/oauth/types.js"; +export * from "./utils/overflow.js"; +export * from "./utils/typebox-helpers.js"; +export * from "./utils/repair-tool-json.js"; +export * from "./utils/validation.js"; +``` + +Provider-specific exports (`streamAnthropic`, `streamGoogle`, etc.) are removed from the public API. Any external consumer that imported them directly should use the registry-based `stream()` / `streamSimple()` functions instead — which is how all internal callers already work. + +#### Why this matters + +- **Enforces the registry pattern.** The correct way to call a provider is `stream(model, context)`. Direct provider function imports create fragile coupling. +- **Enables future refactoring.** Provider internal function signatures can change without breaking the package API. Today, renaming `streamAnthropic` would be a semver-breaking change. +- **Reduces API surface.** Consumers see only what they need: `stream`, `streamSimple`, `registerApiProvider`, model utilities, and types. + +### What Does NOT Change + +- **Runtime behavior** — all providers still load eagerly, same as today +- **The `Model` type system** — all types, interfaces, and generics stay the same +- **The `ApiProvider` interface** — providers still implement `{ api, stream, streamSimple }` +- **The `api-registry.ts` registry** — synchronous `Map.get()` dispatch, unchanged +- **`stream.ts`** — no changes to the streaming entry point +- **`register-builtins.ts`** — still eagerly imports and registers all providers (only `resetApiProviders` remains in barrel export) +- **The extension system** — `registerApiProvider()` continues to work for Ollama, Claude Code CLI, etc. +- **`models.json` user config** — custom models, overrides, provider settings are unaffected +- **Model discovery** — discovery adapters are already lazy and independent +- **Model routing** — ADR-004's capability-aware routing is orthogonal + +## Consequences + +### Positive + +1. **Cleaner PRs.** Model catalog changes are scoped to the provider that changed. Reviewers see a 200-line diff in `models/generated/openai.ts` instead of a 13K-line diff in `models.generated.ts`. + +2. **Fewer merge conflicts.** Two PRs that update different providers no longer conflict on the same file. + +3. **Better navigability.** Developers can jump directly to `models/generated/anthropic.ts` to see Anthropic's model definitions instead of searching through a monolith. + +4. **Cleaner package API.** `pi-ai` exports only what consumers need. Provider internals are properly encapsulated. + +5. **Future-proofs refactoring.** Provider implementation details can evolve without breaking the public API contract. + +6. **Zero runtime risk.** No changes to loading, registration, streaming, or dispatch. The refactor is purely structural. + +### Negative + +1. **More files.** Instead of 1 generated file + 1 custom file, we'll have ~15-20 generated files. Marginal complexity increase, but each file is focused and small. + +2. **Generation script update.** `generate-models.ts` needs to write per-provider files. The script already groups by provider, so this is straightforward but requires testing. + +3. **Import audit for barrel export change.** Any code that directly imports `streamAnthropic` (etc.) from `pi-ai` needs to be updated. Based on research, the main consumer is `register-builtins.ts` itself, which imports providers directly (not through the barrel). External usage should be minimal. + +## Alternatives Considered + +### 1. Full lazy provider loading (original ADR-005 proposal) + +Make all providers load on-demand via async dynamic imports, generalizing the Bedrock pattern. **Rejected** because: +- SDK imports are already lazy — the heavy cost is handled +- Provider implementation parsing is ~10-30ms total — not a bottleneck +- Adds async complexity to the synchronous stream dispatch hot path +- High migration effort and regression risk for unmeasurable performance gain + +### 2. Plugin architecture with separate npm packages + +Move each provider to its own package (`@gsd/provider-anthropic`, etc.). Maximum isolation but dramatically more complex build/release/versioning. Overkill for a monorepo where all providers ship together. + +### 3. Do nothing + +The current architecture works. This is a valid choice. The split is justified by the developer experience friction (13K-line file, merge conflicts, unusable git blame) and the API hygiene issue (leaking provider internals), not by a runtime problem. If the team is not experiencing these friction points, deferring is reasonable. + +## Implementation Plan + +### Wave 1: Split Model Catalog (Low-Medium Risk) +1. Update `generate-models.ts` to emit per-provider files into `models/generated/` +2. Create `models/index.ts` that imports all per-provider files and builds the same registry +3. Extract `CAPABILITY_PATCHES` into `models/capability-patches.ts` +4. Move `models.custom.ts` to `models/custom.ts` +5. Update imports in `models.ts` (or replace it with the new `models/index.ts`) +6. Verify `npm run build` and `npm run test` pass +7. Delete `models.generated.ts` and `models.custom.ts` + +### Wave 2: Clean Up Barrel Export (Low Risk) +1. Remove provider re-exports from `index.ts` +2. Grep for direct provider imports from `"pi-ai"` across the codebase +3. Migrate any found usages to use `stream()` / `streamSimple()` through the registry +4. Verify build and tests + +### Wave 3: Validate +1. Run full test suite +2. Verify extension registration (Ollama, Claude Code CLI) still works +3. Verify `resetApiProviders()` test helper still works +4. Spot-check a few providers end-to-end + +## References + +- Current model catalog: `packages/pi-ai/src/models.generated.ts` (13,848 lines) +- Current barrel export: `packages/pi-ai/src/index.ts` +- Model registry: `packages/pi-ai/src/models.ts` +- API provider registry: `packages/pi-ai/src/api-registry.ts` +- Eager registration: `packages/pi-ai/src/providers/register-builtins.ts` +- Stream dispatch: `packages/pi-ai/src/stream.ts` +- Generation script: `packages/pi-ai/scripts/generate-models.ts` +- Extension registration: `packages/pi-coding-agent/src/core/model-registry.ts` +- ADR-004: `docs/ADR-004-capability-aware-model-routing.md` diff --git a/docs/dev/ADR-008-IMPLEMENTATION-PLAN.md b/docs/dev/ADR-008-IMPLEMENTATION-PLAN.md new file mode 100644 index 000000000..23a1f8c5b --- /dev/null +++ b/docs/dev/ADR-008-IMPLEMENTATION-PLAN.md @@ -0,0 +1,335 @@ +# ADR-008 Implementation Plan + +**Related ADR:** [ADR-008-gsd-tools-over-mcp-for-provider-parity.md](/Users/jeremymcspadden/Github/gsd-2/docs/ADR-008-gsd-tools-over-mcp-for-provider-parity.md) +**Status:** Draft +**Date:** 2026-04-09 + +## Objective + +Implement the ADR-008 decision by exposing the core GSD workflow tool contract over MCP, then wiring MCP-backed access into provider paths that cannot use the native in-process GSD tool registry directly. + +The first usable outcome is: + +- a Claude Code-backed execution session can complete a task using canonical GSD tools +- no manual summary-writing fallback is needed +- native provider behavior remains unchanged + +## Non-Goals + +- Replacing native in-process GSD tools with MCP +- Exporting every historical alias in the first rollout +- Reworking the entire session-oriented MCP server before proving the workflow-tool surface +- Supporting every provider path before Claude Code is working end-to-end + +## Constraints + +- Native and MCP tool paths must share business logic +- MCP must not bypass write-gate or discussion-gate protections +- Canonical GSD state transitions must remain DB-backed +- Provider capability mismatches must fail early, not degrade silently + +## Workstreams + +### 1. Shared Handler Extraction + +Goal: separate business logic from transport registration. + +Targets: + +- `src/resources/extensions/gsd/bootstrap/db-tools.ts` +- `src/resources/extensions/gsd/bootstrap/query-tools.ts` +- `src/resources/extensions/gsd/tools/complete-task.ts` +- sibling modules used by planning/summary/validation tools + +Deliverables: + +- transport-neutral handler entrypoints for the minimum workflow tool set +- thin native registration wrappers that call those handlers +- thin MCP registration wrappers that call those handlers + +Exit criteria: + +- native tool behavior is unchanged +- no workflow tool logic is duplicated in MCP server code + +### 2. Workflow-Tool MCP Surface + +Goal: add an MCP server surface for real GSD workflow tools, distinct from the current session/read API. + +Preferred first-cut tool set: + +- `gsd_summary_save` +- `gsd_decision_save` +- `gsd_plan_milestone` +- `gsd_plan_slice` +- `gsd_plan_task` +- `gsd_task_complete` +- `gsd_slice_complete` +- `gsd_complete_milestone` +- `gsd_validate_milestone` +- `gsd_replan_slice` +- `gsd_reassess_roadmap` +- `gsd_save_gate_result` +- `gsd_milestone_status` + +Likely files: + +- `packages/mcp-server/src/server.ts` or a new sibling server package +- `packages/mcp-server/src/...` supporting modules +- shared tool-definition metadata if needed + +Decisions to make during implementation: + +- extend existing MCP package vs create `packages/mcp-gsd-tools-server` +- canonical names only vs selected alias export +- single combined server vs separate “session” and “workflow” server modes + +Exit criteria: + +- MCP tool discovery shows the minimum tool set +- each MCP tool invokes the shared handlers successfully in isolation + +### 3. Safety and Policy Parity + +Goal: ensure MCP mutations enforce the same rules as native tool calls. + +Targets: + +- `src/resources/extensions/gsd/bootstrap/write-gate.ts` +- any current tool-call gating hooks tied to native runtime only +- MCP wrapper layer before shared handler invocation + +Required protections: + +- discussion gate blocking +- queue-mode restrictions +- write-path restrictions +- canonical DB/file rendering order + +Exit criteria: + +- MCP cannot be used to bypass native write restrictions +- blocked native scenarios remain blocked over MCP + +### 4. Claude Code Provider Integration + +Goal: attach the GSD workflow-tool MCP surface to Claude Code sessions. + +Targets: + +- `src/resources/extensions/claude-code-cli/stream-adapter.ts` +- `src/resources/extensions/claude-code-cli/index.ts` + +Expected work: + +- build a GSD-managed `mcpServers` config for the Claude SDK session +- attach the workflow MCP server only when the session requires GSD tools +- keep current Claude Code streaming behavior intact + +Exit criteria: + +- Claude Code session can discover the GSD workflow MCP tools +- task execution path can call `gsd_task_complete` successfully + +### 5. Capability Detection and Failure Path + +Goal: refuse to start tool-dependent workflows when required capabilities are unavailable. + +Targets: + +- GSD dispatch / auto-mode preflight +- provider selection and routing checks +- user-facing compatibility errors + +Required behavior: + +- if native GSD tools are available, proceed +- else if GSD workflow MCP tools are available, proceed +- else fail fast with a precise message + +Exit criteria: + +- no execution prompt is sent that requires unavailable tools +- users with only unsupported capability combinations get a hard error, not a fake fallback + +### 6. Prompt and Documentation Alignment + +Goal: keep the workflow contract strict while removing transport assumptions from docs and runtime messaging. + +Targets: + +- `src/resources/extensions/gsd/prompts/execute-task.md` +- related planning/discuss prompts that reference tool availability +- provider and MCP docs + +Rules: + +- prompts should keep requiring canonical GSD completion/planning tools +- prompts should not imply “native in-process tool only” +- docs should explain native vs MCP-backed fulfillment paths + +Exit criteria: + +- prompt contract matches runtime reality +- no provider is told to use a tool surface it cannot access + +## Phase Plan + +## Phase 1: Spike and Handler Extraction + +Scope: + +- extract shared logic for `gsd_summary_save`, `gsd_task_complete`, and `gsd_milestone_status` +- prove native wrappers still work + +Why first: + +- these tools are enough to test end-to-end completion semantics without migrating the full catalog + +Verification: + +- existing native tests still pass +- new unit tests cover shared handler entrypoints directly + +## Phase 2: Minimal Workflow MCP Server + +Scope: + +- expose the three extracted tools over MCP +- ensure discovery schemas are clean and canonical + +Verification: + +- MCP discovery returns all three tools +- direct MCP calls succeed against a fixture project + +## Phase 3: Claude Code End-to-End Proof + +Scope: + +- wire the minimal workflow MCP server into the Claude SDK session +- run a single execution path that ends with task completion + +Verification: + +- Claude Code can call `gsd_task_complete` +- summary file, DB state, and plan checkbox update correctly + +## Phase 4: Expand to Full Minimum Workflow Set + +Scope: + +- add planning, slice completion, milestone completion, roadmap reassessment, and gate result tools + +Verification: + +- discuss/plan/execute/complete lifecycle works over MCP for the supported flow set + +## Phase 5: Capability Gating and UX Hardening + +Scope: + +- add preflight capability checks +- add clear error messaging for unsupported setups + +Verification: + +- unsupported provider/session combinations fail before execution starts + +## Phase 6: Prompt and Doc Cleanup + +Scope: + +- align prompts and docs with the new transport-neutral contract + +Verification: + +- prompt references are accurate +- docs describe the supported architecture and limitations + +## File-Level Starting Map + +High-probability files for the first implementation: + +- `src/resources/extensions/gsd/bootstrap/db-tools.ts` +- `src/resources/extensions/gsd/bootstrap/query-tools.ts` +- `src/resources/extensions/gsd/bootstrap/write-gate.ts` +- `src/resources/extensions/gsd/tools/complete-task.ts` +- `src/resources/extensions/claude-code-cli/stream-adapter.ts` +- `src/resources/extensions/claude-code-cli/index.ts` +- `packages/mcp-server/src/server.ts` +- `packages/mcp-server/src/session-manager.ts` +- `packages/mcp-server/README.md` +- `src/resources/extensions/gsd/prompts/execute-task.md` + +## Testing Strategy + +### Unit + +- shared handlers +- MCP wrapper adapters +- gating / capability-check helpers + +### Integration + +- direct MCP tool invocation against fixture projects +- native tool invocation regression coverage +- Claude Code provider path with MCP attached + +### End-to-End + +- plan or execute a small fixture task and complete it through canonical GSD tools +- confirm DB row, rendered summary, and plan state stay in sync + +## Risks + +### Risk 1: Logic Drift + +If native and MCP wrappers each evolve their own behavior, parity will collapse quickly. + +Mitigation: + +- shared handler extraction before broad MCP exposure + +### Risk 2: Safety Regression + +If MCP becomes a side door around native gating, the architecture is worse than before. + +Mitigation: + +- centralize or reuse gating checks before shared handler invocation + +### Risk 3: Overly Broad First Rollout + +Exporting every tool and alias immediately increases scope and test burden. + +Mitigation: + +- ship a minimal workflow tool set first + +### Risk 4: Claude SDK Session Wiring Complexity + +Attaching MCP servers dynamically may expose edge cases around cwd, permissions, or subprocess lifecycle. + +Mitigation: + +- prove a narrow spike with 2-3 tools before expanding + +## Exit Criteria for ADR-008 + +ADR-008 is considered implemented when: + +1. Claude Code-backed execution can use canonical GSD workflow tools over MCP. +2. Native provider behavior remains intact. +3. Shared handlers back both native and MCP invocation. +4. Gating and state integrity protections apply equally to MCP mutations. +5. Capability checks prevent prompts from requiring unavailable tools. + +## Recommended Next Task + +Start with a narrow spike: + +1. Extract shared handlers for `gsd_summary_save`, `gsd_task_complete`, and `gsd_milestone_status`. +2. Expose those tools through a minimal workflow MCP server. +3. Attach that MCP server to Claude Code sessions. +4. Prove end-to-end task completion on a fixture project. diff --git a/docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md b/docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md new file mode 100644 index 000000000..6e17e5873 --- /dev/null +++ b/docs/dev/ADR-008-gsd-tools-over-mcp-for-provider-parity.md @@ -0,0 +1,240 @@ +# ADR-008: Expose GSD Workflow Tools Over MCP for Provider Parity + +**Status:** Proposed +**Date:** 2026-04-09 +**Deciders:** Jeremy McSpadden +**Related:** ADR-004 (capability-aware model routing), ADR-007 (model catalog split and provider API encapsulation), `src/resources/extensions/gsd/bootstrap/db-tools.ts`, `src/resources/extensions/claude-code-cli/stream-adapter.ts`, `packages/mcp-server/src/server.ts` + +## Context + +GSD currently has two different tool surfaces: + +1. **In-process extension tools** registered directly into the runtime via `pi.registerTool(...)`. +2. **An external MCP server** that exposes session orchestration and read-only project inspection. + +This split is now creating a real provider compatibility problem. + +### What exists today + +The core GSD workflow tools are internal extension tools. Examples include: + +- `gsd_summary_save` +- `gsd_plan_milestone` +- `gsd_plan_slice` +- `gsd_plan_task` +- `gsd_task_complete` / `gsd_complete_task` +- `gsd_slice_complete` +- `gsd_complete_milestone` +- `gsd_validate_milestone` +- `gsd_replan_slice` +- `gsd_reassess_roadmap` + +These are registered in `src/resources/extensions/gsd/bootstrap/db-tools.ts` and related bootstrap files. GSD prompts assume these tools are available during discuss, plan, and execute flows. + +Separately, `packages/mcp-server/src/server.ts` exposes a different tool surface: + +- session control: `gsd_execute`, `gsd_status`, `gsd_result`, `gsd_cancel`, `gsd_query`, `gsd_resolve_blocker` +- read-only inspection: `gsd_progress`, `gsd_roadmap`, `gsd_history`, `gsd_doctor`, `gsd_captures`, `gsd_knowledge` + +That MCP server is useful, but it is **not** a transport for the internal workflow/mutation tools. + +### The current failure mode + +The Claude Code CLI provider uses the Anthropic Agent SDK through `src/resources/extensions/claude-code-cli/stream-adapter.ts`. That adapter starts a Claude SDK session, but it does not forward the internal GSD tool registry into the SDK session, nor does it attach a GSD MCP server for those tools. + +As a result: + +- prompts tell the model to call tools like `gsd_complete_task` +- the tools exist in GSD +- but Claude Code sessions do not actually receive those tools + +This produces a contract mismatch: the model is required to use tools that are unavailable in that provider path. + +### Why this matters + +This is not a one-off Claude Code bug. It reveals a deeper architectural issue: + +- GSD’s core workflow contract is transport-specific +- prompt authors assume “internal extension tool availability” +- provider integrations do not all share the same execution surface + +If GSD wants provider parity, its workflow tools need a transport-neutral exposure model. + +## Decision + +**Expose the GSD workflow tool contract over MCP as a first-class transport, and make MCP the compatibility layer for providers that cannot directly access the in-process GSD tool registry.** + +This means: + +1. GSD will keep its existing in-process tool registration for native runtime use. +2. GSD will add an MCP execution surface for the same workflow tools. +3. Both surfaces must call the same underlying business logic. +4. Provider integrations such as Claude Code will use the MCP surface when they cannot access native in-process tools directly. + +The decision is explicitly **not** to replace the native tool system with MCP everywhere. MCP is the parity and portability layer, not the only runtime path. + +## Decision Details + +### 1. One handler layer, multiple transports + +GSD tool behavior must not be implemented twice. + +The transport-neutral business logic for workflow tools should be shared by: + +- native extension tool registration (`pi.registerTool(...)`) +- MCP server tool registration + +The MCP server should wrap the same handlers used by `db-tools.ts`, `query-tools.ts`, and related modules. This avoids logic drift and keeps validation, DB writes, file rendering, and recovery behavior consistent. + +### 2. Add a workflow-tool MCP surface + +GSD will expose the workflow tools required for discuss, planning, execution, and completion over MCP. + +Initial minimum set: + +- `gsd_summary_save` +- `gsd_decision_save` +- `gsd_plan_milestone` +- `gsd_plan_slice` +- `gsd_plan_task` +- `gsd_task_complete` +- `gsd_slice_complete` +- `gsd_complete_milestone` +- `gsd_validate_milestone` +- `gsd_replan_slice` +- `gsd_reassess_roadmap` +- `gsd_save_gate_result` +- selected read/query tools such as `gsd_milestone_status` + +Aliases should be treated conservatively. MCP should prefer canonical names unless compatibility requires exposing aliases. + +### 3. Preserve safety semantics + +The current GSD safety model includes write gates, discussion gates, queue-mode restrictions, and state integrity guarantees. + +Those guarantees must continue to apply when tools are invoked over MCP. In particular: + +- MCP must not create a path that bypasses write gating +- MCP mutations must preserve the same DB/file/state invariants as native tools +- provider-specific fallback behavior must not allow manual summary writing in place of canonical completion tools + +### 4. Make provider capability checks explicit + +Before dispatching a workflow that requires GSD workflow tools, GSD should check whether the selected provider/session can access the required tool surface. + +If a provider cannot access either: + +- native in-process GSD tools, or +- the GSD MCP workflow tool surface + +then GSD must fail early with a clear compatibility error rather than allowing execution to continue in a degraded, state-breaking mode. + +### 5. Keep the existing session/read MCP server + +The existing MCP server in `packages/mcp-server` remains valid. It serves a different purpose: + +- remote session orchestration +- status/result polling +- filesystem-backed project inspection + +The new workflow-tool MCP surface is complementary, not a replacement. + +## Alternatives Considered + +### Alternative A: Reroute away from Claude Code whenever tool-backed execution is needed + +This would fix the immediate failure for multi-provider users, but it does not solve provider parity. It also fails completely for users who only have Claude Code configured. + +**Rejected** because it treats the symptom, not the architectural gap. + +### Alternative B: Hard-fail Claude Code and require another provider + +This is a valid short-term guardrail and may still be used before MCP support is complete. + +**Rejected as the long-term architecture** because it permanently excludes a supported provider from first-class GSD execution. + +### Alternative C: Inject the internal GSD tool registry directly into the Claude Agent SDK without MCP + +This would tightly couple GSD’s internal extension runtime to a provider-specific integration path. It would not generalize well to other providers or external tool clients. + +**Rejected** because it creates a provider-specific bridge instead of a transport-neutral contract. + +### Alternative D: Replace native GSD tools entirely with MCP + +This would simplify the conceptual model, but it would force all runtimes through an external protocol boundary even when the native in-process path is faster and already works well. + +**Rejected** because MCP is needed for portability, not because the native tool system is flawed. + +## Consequences + +### Positive + +1. **Provider parity improves.** Providers that can consume MCP tools can participate in full GSD workflow execution. +2. **The workflow contract becomes transport-neutral.** Prompts can rely on capabilities rather than a specific runtime implementation detail. +3. **One compatibility story for external clients.** Claude Code, Cursor, and other MCP-capable clients can use the same workflow tool surface. +4. **Better long-term architecture.** Internal tools and external transports converge on shared handlers instead of diverging implementations. + +### Negative + +1. **Larger surface area to secure and test.** Mutation tools over MCP are higher risk than read-only inspection tools. +2. **Migration complexity.** Tool registration, gating, and handler extraction must be refactored carefully. +3. **Two transport paths must remain aligned.** Native and MCP invocation semantics must stay behaviorally identical. + +### Neutral / Tradeoff + +The system will now support: + +- native in-process tool execution when available +- MCP-backed tool execution when native access is unavailable + +That is more complex than a single-path system, but it is the cost of provider portability without sacrificing native runtime quality. + +## Migration Plan + +### Phase 1: Extract shared handlers + +Refactor workflow tools so MCP and native registration can call the same transport-neutral functions. + +Priority targets: + +- `gsd_summary_save` +- `gsd_task_complete` +- `gsd_plan_milestone` +- `gsd_plan_slice` +- `gsd_plan_task` + +### Phase 2: Stand up the workflow-tool MCP server + +Add a new MCP surface for workflow tool execution. This may extend the existing MCP package or live as a sibling package, but it must be clearly separated from the current session/read API. + +### Phase 3: Port safety enforcement + +Move or centralize write gates and related policy checks so MCP mutations cannot bypass the existing safety model. + +### Phase 4: Attach MCP workflow tools to Claude Code sessions + +Update the Claude Code provider integration to pass a GSD-managed `mcpServers` configuration into the Claude Agent SDK session when required. + +### Phase 5: Add provider capability gating + +Before tool-dependent flows begin, verify that the active provider can access the required GSD workflow tools via either native registration or MCP. + +### Phase 6: Update prompts and docs + +Prompt contracts should remain strict about using canonical GSD completion/planning tools, but documentation and runtime messaging must no longer assume that only native in-process tool registration satisfies that contract. + +## Validation + +Success is defined by all of the following: + +1. A Claude Code-backed execution session can complete a task using canonical GSD workflow tools without manual summary writing. +2. Native provider behavior remains unchanged. +3. MCP-invoked workflow tools produce the same DB updates, rendered artifacts, and state transitions as native tool calls. +4. Write-gate and discussion-gate protections still hold under MCP invocation. +5. When required capabilities are unavailable, GSD fails early with a precise compatibility error. + +## Scope Notes + +This ADR establishes the architectural direction. It does **not** require full MCP exposure of every historical alias or every auxiliary tool in the first implementation. + +The first implementation should prioritize the minimum workflow tool set needed to make discuss/plan/execute/complete flows work safely for MCP-capable providers. diff --git a/docs/FILE-SYSTEM-MAP.md b/docs/dev/FILE-SYSTEM-MAP.md similarity index 100% rename from docs/FILE-SYSTEM-MAP.md rename to docs/dev/FILE-SYSTEM-MAP.md diff --git a/docs/FRONTIER-TECHNIQUES.md b/docs/dev/FRONTIER-TECHNIQUES.md similarity index 100% rename from docs/FRONTIER-TECHNIQUES.md rename to docs/dev/FRONTIER-TECHNIQUES.md diff --git a/docs/PRD-branchless-worktree-architecture.md b/docs/dev/PRD-branchless-worktree-architecture.md similarity index 100% rename from docs/PRD-branchless-worktree-architecture.md rename to docs/dev/PRD-branchless-worktree-architecture.md diff --git a/docs/agent-knowledge-index.md b/docs/dev/agent-knowledge-index.md similarity index 100% rename from docs/agent-knowledge-index.md rename to docs/dev/agent-knowledge-index.md diff --git a/docs/architecture.md b/docs/dev/architecture.md similarity index 90% rename from docs/architecture.md rename to docs/dev/architecture.md index a166c148b..381029731 100644 --- a/docs/architecture.md +++ b/docs/dev/architecture.md @@ -14,7 +14,7 @@ gsd (CLI binary) ├─ resource-loader.ts Syncs bundled extensions + agents to ~/.gsd/agent/ └─ src/resources/ ├─ extensions/gsd/ Core GSD extension - ├─ extensions/... 12 supporting extensions + ├─ extensions/... 23 supporting extensions ├─ agents/ scout, researcher, worker ├─ AGENTS.md Agent routing instructions └─ GSD-WORKFLOW.md Manual bootstrap protocol @@ -73,6 +73,12 @@ Every dispatch creates a new agent session. The LLM starts with a clean context | **Remote Questions** | Discord, Slack, and Telegram integration for headless question routing | | **TTSR** | Tool-triggered system rules — conditional context injection based on tool usage | | **Universal Config** | Discovery of existing AI tool configurations (Claude Code, Cursor, Windsurf, etc.) | +| **AWS Auth** | AWS credential management and authentication | +| **Claude Code CLI** | Claude Code CLI integration | +| **cmux** | Context multiplexing for multi-session coordination | +| **GitHub Sync** | GitHub issue and PR synchronization | +| **Ollama** | Local Ollama model integration | +| **Shared** | Shared utilities across extensions | ## Bundled Agents @@ -122,7 +128,7 @@ The auto mode dispatch pipeline: Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the corresponding unit type is never dispatched. -## Key Modules (v2.33) +## Key Modules (v2.67) | Module | Purpose | |--------|---------| @@ -160,3 +166,11 @@ Phase skipping (from token profile) gates steps 2-3: if a phase is skipped, the | `memory-extractor.ts` | Extract reusable knowledge from session transcripts | | `memory-store.ts` | Persistent memory store for cross-session knowledge | | `queue-order.ts` | Milestone queue ordering | +| `context-masker.ts` | Context masking for model routing optimization | +| `phase-anchor.ts` | Phase anchoring for dispatch pipeline | +| `slice-parallel-orchestrator.ts` | Slice-level parallelism with dependency-aware dispatch | +| `slice-parallel-eligibility.ts` | Slice parallel eligibility checks | +| `slice-parallel-conflict.ts` | Slice parallel conflict detection | +| `preferences-models.ts` | Model preferences configuration | +| `preferences-validation.ts` | Preferences validation | +| `preferences-types.ts` | Preferences type definitions | diff --git a/docs/building-coding-agents/01-work-decomposition.md b/docs/dev/building-coding-agents/01-work-decomposition.md similarity index 100% rename from docs/building-coding-agents/01-work-decomposition.md rename to docs/dev/building-coding-agents/01-work-decomposition.md diff --git a/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md b/docs/dev/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md similarity index 100% rename from docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md rename to docs/dev/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md diff --git a/docs/building-coding-agents/03-state-machine-context-management.md b/docs/dev/building-coding-agents/03-state-machine-context-management.md similarity index 100% rename from docs/building-coding-agents/03-state-machine-context-management.md rename to docs/dev/building-coding-agents/03-state-machine-context-management.md diff --git a/docs/building-coding-agents/04-optimal-storage-for-project-context.md b/docs/dev/building-coding-agents/04-optimal-storage-for-project-context.md similarity index 100% rename from docs/building-coding-agents/04-optimal-storage-for-project-context.md rename to docs/dev/building-coding-agents/04-optimal-storage-for-project-context.md diff --git a/docs/building-coding-agents/05-parallelization-strategy.md b/docs/dev/building-coding-agents/05-parallelization-strategy.md similarity index 100% rename from docs/building-coding-agents/05-parallelization-strategy.md rename to docs/dev/building-coding-agents/05-parallelization-strategy.md diff --git a/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md b/docs/dev/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md similarity index 100% rename from docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md rename to docs/dev/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md diff --git a/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md b/docs/dev/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md similarity index 100% rename from docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md rename to docs/dev/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md diff --git a/docs/building-coding-agents/08-speed-optimization.md b/docs/dev/building-coding-agents/08-speed-optimization.md similarity index 100% rename from docs/building-coding-agents/08-speed-optimization.md rename to docs/dev/building-coding-agents/08-speed-optimization.md diff --git a/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md b/docs/dev/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md similarity index 100% rename from docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md rename to docs/dev/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md diff --git a/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md b/docs/dev/building-coding-agents/10-top-10-pitfalls-to-avoid.md similarity index 100% rename from docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md rename to docs/dev/building-coding-agents/10-top-10-pitfalls-to-avoid.md diff --git a/docs/building-coding-agents/11-god-tier-context-engineering.md b/docs/dev/building-coding-agents/11-god-tier-context-engineering.md similarity index 100% rename from docs/building-coding-agents/11-god-tier-context-engineering.md rename to docs/dev/building-coding-agents/11-god-tier-context-engineering.md diff --git a/docs/building-coding-agents/12-handling-ambiguity-contradiction.md b/docs/dev/building-coding-agents/12-handling-ambiguity-contradiction.md similarity index 100% rename from docs/building-coding-agents/12-handling-ambiguity-contradiction.md rename to docs/dev/building-coding-agents/12-handling-ambiguity-contradiction.md diff --git a/docs/building-coding-agents/13-long-running-memory-fidelity.md b/docs/dev/building-coding-agents/13-long-running-memory-fidelity.md similarity index 100% rename from docs/building-coding-agents/13-long-running-memory-fidelity.md rename to docs/dev/building-coding-agents/13-long-running-memory-fidelity.md diff --git a/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md b/docs/dev/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md similarity index 100% rename from docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md rename to docs/dev/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md diff --git a/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md b/docs/dev/building-coding-agents/15-legacy-code-brownfield-onboarding.md similarity index 100% rename from docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md rename to docs/dev/building-coding-agents/15-legacy-code-brownfield-onboarding.md diff --git a/docs/building-coding-agents/16-encoding-taste-aesthetics.md b/docs/dev/building-coding-agents/16-encoding-taste-aesthetics.md similarity index 100% rename from docs/building-coding-agents/16-encoding-taste-aesthetics.md rename to docs/dev/building-coding-agents/16-encoding-taste-aesthetics.md diff --git a/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md b/docs/dev/building-coding-agents/17-irreversible-operations-safety-architecture.md similarity index 100% rename from docs/building-coding-agents/17-irreversible-operations-safety-architecture.md rename to docs/dev/building-coding-agents/17-irreversible-operations-safety-architecture.md diff --git a/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md b/docs/dev/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md similarity index 100% rename from docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md rename to docs/dev/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md diff --git a/docs/building-coding-agents/19-when-to-scrap-and-start-over.md b/docs/dev/building-coding-agents/19-when-to-scrap-and-start-over.md similarity index 100% rename from docs/building-coding-agents/19-when-to-scrap-and-start-over.md rename to docs/dev/building-coding-agents/19-when-to-scrap-and-start-over.md diff --git a/docs/building-coding-agents/20-error-taxonomy-routing.md b/docs/dev/building-coding-agents/20-error-taxonomy-routing.md similarity index 100% rename from docs/building-coding-agents/20-error-taxonomy-routing.md rename to docs/dev/building-coding-agents/20-error-taxonomy-routing.md diff --git a/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md b/docs/dev/building-coding-agents/21-cost-quality-tradeoff-model-routing.md similarity index 100% rename from docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md rename to docs/dev/building-coding-agents/21-cost-quality-tradeoff-model-routing.md diff --git a/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md b/docs/dev/building-coding-agents/22-cross-project-learning-reusable-intelligence.md similarity index 100% rename from docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md rename to docs/dev/building-coding-agents/22-cross-project-learning-reusable-intelligence.md diff --git a/docs/building-coding-agents/23-evolution-across-project-scale.md b/docs/dev/building-coding-agents/23-evolution-across-project-scale.md similarity index 100% rename from docs/building-coding-agents/23-evolution-across-project-scale.md rename to docs/dev/building-coding-agents/23-evolution-across-project-scale.md diff --git a/docs/building-coding-agents/24-security-trust-boundaries.md b/docs/dev/building-coding-agents/24-security-trust-boundaries.md similarity index 100% rename from docs/building-coding-agents/24-security-trust-boundaries.md rename to docs/dev/building-coding-agents/24-security-trust-boundaries.md diff --git a/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md b/docs/dev/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md similarity index 100% rename from docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md rename to docs/dev/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md diff --git a/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md b/docs/dev/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md similarity index 100% rename from docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md rename to docs/dev/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md diff --git a/docs/building-coding-agents/README.md b/docs/dev/building-coding-agents/README.md similarity index 100% rename from docs/building-coding-agents/README.md rename to docs/dev/building-coding-agents/README.md diff --git a/docs/ci-cd-pipeline.md b/docs/dev/ci-cd-pipeline.md similarity index 100% rename from docs/ci-cd-pipeline.md rename to docs/dev/ci-cd-pipeline.md diff --git a/docs/context-and-hooks/01-the-context-pipeline.md b/docs/dev/context-and-hooks/01-the-context-pipeline.md similarity index 100% rename from docs/context-and-hooks/01-the-context-pipeline.md rename to docs/dev/context-and-hooks/01-the-context-pipeline.md diff --git a/docs/context-and-hooks/02-hook-reference.md b/docs/dev/context-and-hooks/02-hook-reference.md similarity index 100% rename from docs/context-and-hooks/02-hook-reference.md rename to docs/dev/context-and-hooks/02-hook-reference.md diff --git a/docs/context-and-hooks/03-context-injection-patterns.md b/docs/dev/context-and-hooks/03-context-injection-patterns.md similarity index 100% rename from docs/context-and-hooks/03-context-injection-patterns.md rename to docs/dev/context-and-hooks/03-context-injection-patterns.md diff --git a/docs/context-and-hooks/04-message-types-and-llm-visibility.md b/docs/dev/context-and-hooks/04-message-types-and-llm-visibility.md similarity index 100% rename from docs/context-and-hooks/04-message-types-and-llm-visibility.md rename to docs/dev/context-and-hooks/04-message-types-and-llm-visibility.md diff --git a/docs/context-and-hooks/05-inter-extension-communication.md b/docs/dev/context-and-hooks/05-inter-extension-communication.md similarity index 100% rename from docs/context-and-hooks/05-inter-extension-communication.md rename to docs/dev/context-and-hooks/05-inter-extension-communication.md diff --git a/docs/context-and-hooks/06-advanced-patterns-from-source.md b/docs/dev/context-and-hooks/06-advanced-patterns-from-source.md similarity index 100% rename from docs/context-and-hooks/06-advanced-patterns-from-source.md rename to docs/dev/context-and-hooks/06-advanced-patterns-from-source.md diff --git a/docs/context-and-hooks/07-the-system-prompt-anatomy.md b/docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md similarity index 100% rename from docs/context-and-hooks/07-the-system-prompt-anatomy.md rename to docs/dev/context-and-hooks/07-the-system-prompt-anatomy.md diff --git a/docs/context-and-hooks/README.md b/docs/dev/context-and-hooks/README.md similarity index 100% rename from docs/context-and-hooks/README.md rename to docs/dev/context-and-hooks/README.md diff --git a/docs/extending-pi/01-what-are-extensions.md b/docs/dev/extending-pi/01-what-are-extensions.md similarity index 100% rename from docs/extending-pi/01-what-are-extensions.md rename to docs/dev/extending-pi/01-what-are-extensions.md diff --git a/docs/extending-pi/02-architecture-mental-model.md b/docs/dev/extending-pi/02-architecture-mental-model.md similarity index 100% rename from docs/extending-pi/02-architecture-mental-model.md rename to docs/dev/extending-pi/02-architecture-mental-model.md diff --git a/docs/extending-pi/03-getting-started.md b/docs/dev/extending-pi/03-getting-started.md similarity index 100% rename from docs/extending-pi/03-getting-started.md rename to docs/dev/extending-pi/03-getting-started.md diff --git a/docs/extending-pi/04-extension-locations-discovery.md b/docs/dev/extending-pi/04-extension-locations-discovery.md similarity index 100% rename from docs/extending-pi/04-extension-locations-discovery.md rename to docs/dev/extending-pi/04-extension-locations-discovery.md diff --git a/docs/extending-pi/05-extension-structure-styles.md b/docs/dev/extending-pi/05-extension-structure-styles.md similarity index 100% rename from docs/extending-pi/05-extension-structure-styles.md rename to docs/dev/extending-pi/05-extension-structure-styles.md diff --git a/docs/extending-pi/06-the-extension-lifecycle.md b/docs/dev/extending-pi/06-the-extension-lifecycle.md similarity index 100% rename from docs/extending-pi/06-the-extension-lifecycle.md rename to docs/dev/extending-pi/06-the-extension-lifecycle.md diff --git a/docs/extending-pi/07-events-the-nervous-system.md b/docs/dev/extending-pi/07-events-the-nervous-system.md similarity index 100% rename from docs/extending-pi/07-events-the-nervous-system.md rename to docs/dev/extending-pi/07-events-the-nervous-system.md diff --git a/docs/extending-pi/08-extensioncontext-what-you-can-access.md b/docs/dev/extending-pi/08-extensioncontext-what-you-can-access.md similarity index 100% rename from docs/extending-pi/08-extensioncontext-what-you-can-access.md rename to docs/dev/extending-pi/08-extensioncontext-what-you-can-access.md diff --git a/docs/extending-pi/09-extensionapi-what-you-can-do.md b/docs/dev/extending-pi/09-extensionapi-what-you-can-do.md similarity index 100% rename from docs/extending-pi/09-extensionapi-what-you-can-do.md rename to docs/dev/extending-pi/09-extensionapi-what-you-can-do.md diff --git a/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md b/docs/dev/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md similarity index 100% rename from docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md rename to docs/dev/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md diff --git a/docs/extending-pi/11-custom-commands-user-facing-actions.md b/docs/dev/extending-pi/11-custom-commands-user-facing-actions.md similarity index 100% rename from docs/extending-pi/11-custom-commands-user-facing-actions.md rename to docs/dev/extending-pi/11-custom-commands-user-facing-actions.md diff --git a/docs/extending-pi/12-custom-ui-visual-components.md b/docs/dev/extending-pi/12-custom-ui-visual-components.md similarity index 100% rename from docs/extending-pi/12-custom-ui-visual-components.md rename to docs/dev/extending-pi/12-custom-ui-visual-components.md diff --git a/docs/extending-pi/13-state-management-persistence.md b/docs/dev/extending-pi/13-state-management-persistence.md similarity index 100% rename from docs/extending-pi/13-state-management-persistence.md rename to docs/dev/extending-pi/13-state-management-persistence.md diff --git a/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md b/docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md similarity index 100% rename from docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md rename to docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md diff --git a/docs/extending-pi/15-system-prompt-modification.md b/docs/dev/extending-pi/15-system-prompt-modification.md similarity index 100% rename from docs/extending-pi/15-system-prompt-modification.md rename to docs/dev/extending-pi/15-system-prompt-modification.md diff --git a/docs/extending-pi/16-compaction-session-control.md b/docs/dev/extending-pi/16-compaction-session-control.md similarity index 100% rename from docs/extending-pi/16-compaction-session-control.md rename to docs/dev/extending-pi/16-compaction-session-control.md diff --git a/docs/extending-pi/17-model-provider-management.md b/docs/dev/extending-pi/17-model-provider-management.md similarity index 100% rename from docs/extending-pi/17-model-provider-management.md rename to docs/dev/extending-pi/17-model-provider-management.md diff --git a/docs/extending-pi/18-remote-execution-tool-overrides.md b/docs/dev/extending-pi/18-remote-execution-tool-overrides.md similarity index 100% rename from docs/extending-pi/18-remote-execution-tool-overrides.md rename to docs/dev/extending-pi/18-remote-execution-tool-overrides.md diff --git a/docs/extending-pi/19-packaging-distribution.md b/docs/dev/extending-pi/19-packaging-distribution.md similarity index 100% rename from docs/extending-pi/19-packaging-distribution.md rename to docs/dev/extending-pi/19-packaging-distribution.md diff --git a/docs/extending-pi/20-mode-behavior.md b/docs/dev/extending-pi/20-mode-behavior.md similarity index 100% rename from docs/extending-pi/20-mode-behavior.md rename to docs/dev/extending-pi/20-mode-behavior.md diff --git a/docs/extending-pi/21-error-handling.md b/docs/dev/extending-pi/21-error-handling.md similarity index 100% rename from docs/extending-pi/21-error-handling.md rename to docs/dev/extending-pi/21-error-handling.md diff --git a/docs/extending-pi/22-key-rules-gotchas.md b/docs/dev/extending-pi/22-key-rules-gotchas.md similarity index 100% rename from docs/extending-pi/22-key-rules-gotchas.md rename to docs/dev/extending-pi/22-key-rules-gotchas.md diff --git a/docs/extending-pi/23-file-reference-documentation.md b/docs/dev/extending-pi/23-file-reference-documentation.md similarity index 100% rename from docs/extending-pi/23-file-reference-documentation.md rename to docs/dev/extending-pi/23-file-reference-documentation.md diff --git a/docs/extending-pi/24-file-reference-example-extensions.md b/docs/dev/extending-pi/24-file-reference-example-extensions.md similarity index 100% rename from docs/extending-pi/24-file-reference-example-extensions.md rename to docs/dev/extending-pi/24-file-reference-example-extensions.md diff --git a/docs/extending-pi/25-slash-command-subcommand-patterns.md b/docs/dev/extending-pi/25-slash-command-subcommand-patterns.md similarity index 100% rename from docs/extending-pi/25-slash-command-subcommand-patterns.md rename to docs/dev/extending-pi/25-slash-command-subcommand-patterns.md diff --git a/docs/extending-pi/README.md b/docs/dev/extending-pi/README.md similarity index 100% rename from docs/extending-pi/README.md rename to docs/dev/extending-pi/README.md diff --git a/docs/dev/pi-context-optimization-opportunities.md b/docs/dev/pi-context-optimization-opportunities.md new file mode 100644 index 000000000..9e34cc44c --- /dev/null +++ b/docs/dev/pi-context-optimization-opportunities.md @@ -0,0 +1,198 @@ +# pi-coding-agent: Context Optimization Opportunities + +> **Status**: Research only — not planned for implementation. +> Scope: `packages/pi-coding-agent` and `packages/pi-agent-core` infrastructure. +> These changes would benefit every consumer of the pi engine, not just GSD. + +--- + +## 1. Prompt Caching (`cache_control`) — Highest Impact + +**Current state**: Every LLM call re-pays full input token cost for the system prompt, tool definitions, and context files. No `cache_control` breakpoints are set anywhere in the API call path. + +**Opportunity**: Anthropic's KV cache delivers 90% cost reduction on cached tokens (0.1x input rate). Claude Code achieves 92–98% cache hit rates by placing stable content before volatile content. + +**Where to instrument** (`packages/pi-ai/src/providers/anthropic.ts`): +- Set `cache_control: { type: "ephemeral" }` on the last tool definition block +- Set `cache_control` after the static system prompt sections (base boilerplate + context files) +- Leave the per-turn user message uncached + +**Critical constraint**: The cache breakpoint must be placed *after* all static content and *before* any dynamic content (timestamps, per-request variables). Moving a timestamp before a cache breakpoint defeats it on every call. + +**Cache hierarchy**: Tools → system → messages. Changing a tool definition invalidates system and message caches. Tool definitions should be sorted deterministically (alphabetically) to prevent spurious cache misses. + +**Expected savings**: 80–90% reduction in input token cost for multi-turn sessions (the dominant cost pattern in GSD auto-mode). + +--- + +## 2. Observation Masking in the Message Pipeline + +**Current state**: `agent-loop.ts` passes the full `context.messages` array to the LLM on every turn. Tool results from 50 turns ago are re-read in full on every subsequent call. The `transformContext` hook exists on `AgentContext` and fires before every LLM call, but has no default implementation — extensions are responsible for any pruning. + +**Opportunity**: Replace old tool result content with lightweight placeholders after N turns. JetBrains Research tested this on SWE-bench Verified (500 tasks, up to 250-turn trajectories) and found: +- 50%+ cost reduction vs. unmanaged history +- Performance matched or slightly exceeded LLM summarization +- Zero overhead (no extra LLM call required) + +**Proposed implementation** (default `transformContext` in `pi-agent-core`): +```typescript +// Keep last KEEP_RECENT_TURNS verbatim; mask older tool results +const KEEP_RECENT_TURNS = 8; + +function defaultObservationMask(messages: AgentMessage[]): AgentMessage[] { + const cutoff = findTurnBoundary(messages, KEEP_RECENT_TURNS); + return messages.map((m, i) => { + if (i >= cutoff) return m; + if (m.type === "toolResult" || m.type === "bashExecution") { + return { ...m, content: "[result masked — within summarized history]", excludeFromContext: false }; + } + return m; + }); +} +``` + +**Compaction interaction**: Observation masking reduces the token accumulation rate, pushing the compaction threshold further out. The two mechanisms are complementary — masking handles the steady state, compaction handles the rare deep-session case. + +--- + +## 3. Earlier Compaction Threshold + +**Current state** (`packages/pi-coding-agent/src/core/constants.ts`): +```typescript +COMPACTION_RESERVE_TOKENS = 16_384 // triggers at contextWindow - 16K +COMPACTION_KEEP_RECENT_TOKENS = 20_000 +``` + +For a 200K context window, compaction fires at ~183K tokens — 91.5% utilization. + +**Problem**: Context drift (not raw exhaustion) causes ~65% of enterprise agent failures. Performance degrades measurably beyond ~30K tokens per Zylos production data. The current threshold lets sessions run degraded for a long stretch before compaction fires. + +**Opportunity**: Lower the trigger to 70% utilization. For a 200K window, this means compacting at ~140K tokens — 43K tokens earlier. + +```typescript +// Proposed +COMPACTION_THRESHOLD_PERCENT = 0.70 // fire at 70% of contextWindow +COMPACTION_RESERVE_TOKENS = contextWindow * (1 - COMPACTION_THRESHOLD_PERCENT) +``` + +**Trade-off**: More frequent compactions, each happening earlier when there's more "fresh" content to keep. Summary quality improves because less material needs to be discarded at each cut. + +--- + +## 4. Tool Result Truncation at Write Time + +**Current state**: `TOOL_RESULT_MAX_CHARS = 2_000` in `constants.ts`, but this limit is only applied *during compaction summarization*, not when the tool result enters the message store. A bash result returning 50KB of log output is stored and re-sent verbatim until compaction fires. + +**Opportunity**: Truncate at write time in `messages.ts` → `convertToLlm()` or in the tool result handler. Two strategies: + +- **Hard truncation**: Slice at N chars, append `"\n[truncated — {original_length} chars]"`. Simple, zero overhead. +- **Semantic head/tail**: Keep first 500 chars (context, command echo) + last 1000 chars (final output, errors). Better for bash results where the end contains the error. + +**Recommendation**: Semantic head/tail as the default, configurable per tool type. File read results benefit from head; bash/test output benefits from head+tail. + +--- + +## 5. Context File Deduplication and Trim + +**Current state** (`packages/pi-coding-agent/src/core/resource-loader.ts`, lines 84–109): +- Searches from `~/.gsd/agent/` → ancestor dirs → cwd +- Deduplicates by *file path* but not by *content* +- Entire file content concatenated verbatim into system prompt — no trimming, no summarization + +**Anti-pattern**: A project with AGENTS.md at 3 ancestor levels (repo root, workspace, home) injects all three in full. If they share common boilerplate, that content is re-injected multiple times. + +**Opportunities**: +1. **Content deduplication**: Hash paragraph-level chunks; skip any chunk already seen in a previously-loaded file +2. **Section-aware loading**: Parse `## ` headings in AGENTS.md; only include sections relevant to the current task type (e.g., `## Testing` section only when running tests) +3. **Token budget enforcement**: If total context files exceed N tokens, summarize oldest/most-distant file rather than including verbatim + +--- + +## 6. Skill Content Lazy Loading and Summarization + +**Current state**: When `/skill:name` is invoked, the full skill file content is injected inline as `...` in the user message. No chunking, no summarization. A 10KB skill file adds ~2,500 tokens to that turn. + +**Opportunity**: +- **Cached skill injection**: If the same skill is used across multiple turns (rare but possible), it's re-injected each time. Cache with `cache_control` after first injection. +- **Skill digest mode**: Inject a 200-token summary of the skill on first reference; full content only if the model requests it via a `get_skill_detail` tool call. Reduces cost for skills that don't end up being followed. +- **Skill prefetching**: Before a known long session (e.g., auto-mode start), pre-inject all likely skills with `cache_control` so they're cached for the entire session. + +--- + +## 7. Token Estimation Accuracy + +**Current state** (`compaction.ts`, line 216): `chars / 4` heuristic. This overestimates token count for English prose (~3.5 chars/token) and underestimates for code with short identifiers or Unicode. + +**Opportunity**: Use a proper tokenizer. +- `@anthropic-ai/tokenizer` (tiktoken-compatible, ships with the SDK) — accurate but ~5ms per call +- Tiered approach: use chars/4 for display; use proper tokenizer only for compaction threshold decisions (where accuracy matters) + +**Impact**: More accurate compaction timing, fewer unnecessary compactions, slightly better `COMPACTION_KEEP_RECENT_TOKENS` boundary placement. + +--- + +## 8. Format: Markdown over XML for Internal Context + +**Current state**: The message pipeline uses ``, ``, `` XML wrappers in several places. System prompt sections are largely prose Markdown. + +**Findings**: XML tags carry 15–40% more tokens than equivalent Markdown for the same semantic content, due to paired open/close tags. However, Claude was optimized for XML and shows higher accuracy on tasks requiring precise section parsing. + +**Recommendation**: Audit XML usage in the pipeline and convert to Markdown where the content is: +- Non-nested (flat instructions, status messages) +- Human-readable rather than machine-parsed by the model +- Not requiring precise boundary detection + +Keep XML for: few-shot examples with ambiguous boundaries, skill content (requires precise isolation from surrounding text), compaction summaries that the model must treat as authoritative history. + +**Estimated savings**: 5–15% reduction in system prompt token count. + +--- + +## 9. Dynamic Tool Set Delivery + +**Current state**: All tool definitions are included in every LLM request. Tool descriptions consume 60–80% of input tokens in static configurations. As new extensions register tools, the baseline grows linearly. + +**Opportunity** (higher complexity): Implement the three-function Dynamic Toolset pattern: +1. `search_tools(query)` — semantic search over tool catalog +2. `describe_tools(ids[])` — fetch full schemas on demand +3. `execute_tool(id, params)` — unchanged execution + +Speakeasy measured 91–97% token reduction with 100% task success rate. Trade-off: 2–3x more tool calls, ~50% longer wall time. Net cost dramatically lower. + +**Feasibility for pi**: The tool registry (`packages/pi-coding-agent/src/core/tool-registry.ts`) already stores tool metadata separately from definitions. The primary engineering work is the semantic search index and the `describe_tools` / `search_tools` tool implementations. + +--- + +## 10. Cost Attribution and Per-Phase Reporting + +**Current state**: `SessionManager.getUsageTotals()` accumulates cost across the entire session. No per-phase or per-agent breakdown is stored. Cost visibility is limited to the footer total and `GSD_SHOW_TOKEN_COST=1` per-turn display. + +**Opportunity**: Emit structured cost events that extensions can subscribe to: +```typescript +interface CostCheckpointEvent { + type: "cost_checkpoint"; + label: string; // "discuss-phase", "execute-slice-3" + deltaTokens: Usage; // tokens since last checkpoint + cumulativeTokens: Usage; + cumulativeCost: number; +} +``` + +GSD extension could consume these events to surface per-milestone cost in `/gsd stats` and flag milestones that are disproportionately expensive — enabling budget-aware planning. + +--- + +## Implementation Ordering (if pursued) + +| Priority | Item | Effort | Expected Impact | +|----------|------|--------|-----------------| +| 1 | Prompt caching (`cache_control`) | Low | 80–90% input cost reduction | +| 2 | Earlier compaction threshold (70%) | Trivial | Reduces drift in long sessions | +| 3 | Tool result truncation at write time | Low | Reduces context bloat between compactions | +| 4 | Context file deduplication | Medium | Variable — high for multi-level AGENTS.md setups | +| 5 | Observation masking (default `transformContext`) | Medium | 50%+ on long-running agents | +| 6 | Token estimation (proper tokenizer) | Low | Accuracy improvement, minor cost impact | +| 7 | Markdown over XML audit | Low | 5–15% system prompt reduction | +| 8 | Skill caching with `cache_control` | Low | Meaningful for skill-heavy sessions | +| 9 | Dynamic tool set delivery | High | 90%+ on large tool catalogs; major architecture change | +| 10 | Per-phase cost attribution events | Medium | Visibility only; enables future budget routing | diff --git a/docs/pi-ui-tui/01-the-ui-architecture.md b/docs/dev/pi-ui-tui/01-the-ui-architecture.md similarity index 100% rename from docs/pi-ui-tui/01-the-ui-architecture.md rename to docs/dev/pi-ui-tui/01-the-ui-architecture.md diff --git a/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md b/docs/dev/pi-ui-tui/02-the-component-interface-foundation-of-everything.md similarity index 100% rename from docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md rename to docs/dev/pi-ui-tui/02-the-component-interface-foundation-of-everything.md diff --git a/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md b/docs/dev/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md similarity index 100% rename from docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md rename to docs/dev/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md diff --git a/docs/pi-ui-tui/04-built-in-dialog-methods.md b/docs/dev/pi-ui-tui/04-built-in-dialog-methods.md similarity index 100% rename from docs/pi-ui-tui/04-built-in-dialog-methods.md rename to docs/dev/pi-ui-tui/04-built-in-dialog-methods.md diff --git a/docs/pi-ui-tui/05-persistent-ui-elements.md b/docs/dev/pi-ui-tui/05-persistent-ui-elements.md similarity index 100% rename from docs/pi-ui-tui/05-persistent-ui-elements.md rename to docs/dev/pi-ui-tui/05-persistent-ui-elements.md diff --git a/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md b/docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md similarity index 100% rename from docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md rename to docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md diff --git a/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md b/docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md similarity index 100% rename from docs/pi-ui-tui/07-built-in-components-the-building-blocks.md rename to docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md diff --git a/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md b/docs/dev/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md similarity index 100% rename from docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md rename to docs/dev/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md diff --git a/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md b/docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md similarity index 100% rename from docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md rename to docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md diff --git a/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md b/docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md similarity index 100% rename from docs/pi-ui-tui/10-line-width-the-cardinal-rule.md rename to docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md diff --git a/docs/pi-ui-tui/11-theming-colors-and-styles.md b/docs/dev/pi-ui-tui/11-theming-colors-and-styles.md similarity index 100% rename from docs/pi-ui-tui/11-theming-colors-and-styles.md rename to docs/dev/pi-ui-tui/11-theming-colors-and-styles.md diff --git a/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md b/docs/dev/pi-ui-tui/12-overlays-floating-modals-and-panels.md similarity index 100% rename from docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md rename to docs/dev/pi-ui-tui/12-overlays-floating-modals-and-panels.md diff --git a/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md b/docs/dev/pi-ui-tui/13-custom-editors-replacing-the-input.md similarity index 100% rename from docs/pi-ui-tui/13-custom-editors-replacing-the-input.md rename to docs/dev/pi-ui-tui/13-custom-editors-replacing-the-input.md diff --git a/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md b/docs/dev/pi-ui-tui/14-tool-rendering-custom-tool-display.md similarity index 100% rename from docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md rename to docs/dev/pi-ui-tui/14-tool-rendering-custom-tool-display.md diff --git a/docs/pi-ui-tui/15-message-rendering-custom-message-display.md b/docs/dev/pi-ui-tui/15-message-rendering-custom-message-display.md similarity index 100% rename from docs/pi-ui-tui/15-message-rendering-custom-message-display.md rename to docs/dev/pi-ui-tui/15-message-rendering-custom-message-display.md diff --git a/docs/pi-ui-tui/16-performance-caching-and-invalidation.md b/docs/dev/pi-ui-tui/16-performance-caching-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/16-performance-caching-and-invalidation.md rename to docs/dev/pi-ui-tui/16-performance-caching-and-invalidation.md diff --git a/docs/pi-ui-tui/17-theme-changes-and-invalidation.md b/docs/dev/pi-ui-tui/17-theme-changes-and-invalidation.md similarity index 100% rename from docs/pi-ui-tui/17-theme-changes-and-invalidation.md rename to docs/dev/pi-ui-tui/17-theme-changes-and-invalidation.md diff --git a/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md b/docs/dev/pi-ui-tui/18-ime-support-the-focusable-interface.md similarity index 100% rename from docs/pi-ui-tui/18-ime-support-the-focusable-interface.md rename to docs/dev/pi-ui-tui/18-ime-support-the-focusable-interface.md diff --git a/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md b/docs/dev/pi-ui-tui/19-building-a-complete-component-step-by-step.md similarity index 100% rename from docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md rename to docs/dev/pi-ui-tui/19-building-a-complete-component-step-by-step.md diff --git a/docs/pi-ui-tui/20-real-world-patterns-from-examples.md b/docs/dev/pi-ui-tui/20-real-world-patterns-from-examples.md similarity index 100% rename from docs/pi-ui-tui/20-real-world-patterns-from-examples.md rename to docs/dev/pi-ui-tui/20-real-world-patterns-from-examples.md diff --git a/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md b/docs/dev/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md similarity index 100% rename from docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md rename to docs/dev/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md diff --git a/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md b/docs/dev/pi-ui-tui/22-quick-reference-all-ui-apis.md similarity index 100% rename from docs/pi-ui-tui/22-quick-reference-all-ui-apis.md rename to docs/dev/pi-ui-tui/22-quick-reference-all-ui-apis.md diff --git a/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md b/docs/dev/pi-ui-tui/23-file-reference-example-extensions-with-ui.md similarity index 100% rename from docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md rename to docs/dev/pi-ui-tui/23-file-reference-example-extensions-with-ui.md diff --git a/docs/pi-ui-tui/README.md b/docs/dev/pi-ui-tui/README.md similarity index 100% rename from docs/pi-ui-tui/README.md rename to docs/dev/pi-ui-tui/README.md diff --git a/docs/proposals/698-browser-tools-feature-additions.md b/docs/dev/proposals/698-browser-tools-feature-additions.md similarity index 100% rename from docs/proposals/698-browser-tools-feature-additions.md rename to docs/dev/proposals/698-browser-tools-feature-additions.md diff --git a/docs/proposals/rfc-gitops-branching-strategy.md b/docs/dev/proposals/rfc-gitops-branching-strategy.md similarity index 100% rename from docs/proposals/rfc-gitops-branching-strategy.md rename to docs/dev/proposals/rfc-gitops-branching-strategy.md diff --git a/docs/proposals/workflows/README.md b/docs/dev/proposals/workflows/README.md similarity index 100% rename from docs/proposals/workflows/README.md rename to docs/dev/proposals/workflows/README.md diff --git a/docs/proposals/workflows/backmerge.yml b/docs/dev/proposals/workflows/backmerge.yml similarity index 100% rename from docs/proposals/workflows/backmerge.yml rename to docs/dev/proposals/workflows/backmerge.yml diff --git a/docs/proposals/workflows/create-release.yml b/docs/dev/proposals/workflows/create-release.yml similarity index 100% rename from docs/proposals/workflows/create-release.yml rename to docs/dev/proposals/workflows/create-release.yml diff --git a/docs/proposals/workflows/sync-next.yml b/docs/dev/proposals/workflows/sync-next.yml similarity index 100% rename from docs/proposals/workflows/sync-next.yml rename to docs/dev/proposals/workflows/sync-next.yml diff --git a/docs/superpowers/plans/2026-03-17-cicd-pipeline.md b/docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md similarity index 100% rename from docs/superpowers/plans/2026-03-17-cicd-pipeline.md rename to docs/dev/superpowers/plans/2026-03-17-cicd-pipeline.md diff --git a/docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md b/docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md similarity index 100% rename from docs/superpowers/specs/2026-03-17-cicd-pipeline-design.md rename to docs/dev/superpowers/specs/2026-03-17-cicd-pipeline-design.md diff --git a/docs/what-is-pi/01-what-pi-is.md b/docs/dev/what-is-pi/01-what-pi-is.md similarity index 100% rename from docs/what-is-pi/01-what-pi-is.md rename to docs/dev/what-is-pi/01-what-pi-is.md diff --git a/docs/what-is-pi/02-design-philosophy.md b/docs/dev/what-is-pi/02-design-philosophy.md similarity index 100% rename from docs/what-is-pi/02-design-philosophy.md rename to docs/dev/what-is-pi/02-design-philosophy.md diff --git a/docs/what-is-pi/03-the-four-modes-of-operation.md b/docs/dev/what-is-pi/03-the-four-modes-of-operation.md similarity index 100% rename from docs/what-is-pi/03-the-four-modes-of-operation.md rename to docs/dev/what-is-pi/03-the-four-modes-of-operation.md diff --git a/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md b/docs/dev/what-is-pi/04-the-architecture-how-everything-fits-together.md similarity index 100% rename from docs/what-is-pi/04-the-architecture-how-everything-fits-together.md rename to docs/dev/what-is-pi/04-the-architecture-how-everything-fits-together.md diff --git a/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md b/docs/dev/what-is-pi/05-the-agent-loop-how-pi-thinks.md similarity index 100% rename from docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md rename to docs/dev/what-is-pi/05-the-agent-loop-how-pi-thinks.md diff --git a/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md b/docs/dev/what-is-pi/06-tools-how-pi-acts-on-the-world.md similarity index 100% rename from docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md rename to docs/dev/what-is-pi/06-tools-how-pi-acts-on-the-world.md diff --git a/docs/what-is-pi/07-sessions-memory-that-branches.md b/docs/dev/what-is-pi/07-sessions-memory-that-branches.md similarity index 100% rename from docs/what-is-pi/07-sessions-memory-that-branches.md rename to docs/dev/what-is-pi/07-sessions-memory-that-branches.md diff --git a/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md b/docs/dev/what-is-pi/08-compaction-how-pi-manages-context-limits.md similarity index 100% rename from docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md rename to docs/dev/what-is-pi/08-compaction-how-pi-manages-context-limits.md diff --git a/docs/what-is-pi/09-the-customization-stack.md b/docs/dev/what-is-pi/09-the-customization-stack.md similarity index 100% rename from docs/what-is-pi/09-the-customization-stack.md rename to docs/dev/what-is-pi/09-the-customization-stack.md diff --git a/docs/what-is-pi/10-providers-models-multi-model-by-default.md b/docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md similarity index 100% rename from docs/what-is-pi/10-providers-models-multi-model-by-default.md rename to docs/dev/what-is-pi/10-providers-models-multi-model-by-default.md diff --git a/docs/what-is-pi/11-the-interactive-tui.md b/docs/dev/what-is-pi/11-the-interactive-tui.md similarity index 100% rename from docs/what-is-pi/11-the-interactive-tui.md rename to docs/dev/what-is-pi/11-the-interactive-tui.md diff --git a/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md b/docs/dev/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md similarity index 100% rename from docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md rename to docs/dev/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md diff --git a/docs/what-is-pi/13-context-files-project-instructions.md b/docs/dev/what-is-pi/13-context-files-project-instructions.md similarity index 100% rename from docs/what-is-pi/13-context-files-project-instructions.md rename to docs/dev/what-is-pi/13-context-files-project-instructions.md diff --git a/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md b/docs/dev/what-is-pi/14-the-sdk-rpc-embedding-pi.md similarity index 100% rename from docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md rename to docs/dev/what-is-pi/14-the-sdk-rpc-embedding-pi.md diff --git a/docs/what-is-pi/15-pi-packages-the-ecosystem.md b/docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md similarity index 94% rename from docs/what-is-pi/15-pi-packages-the-ecosystem.md rename to docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md index 4e19de60a..7116cca99 100644 --- a/docs/what-is-pi/15-pi-packages-the-ecosystem.md +++ b/docs/dev/what-is-pi/15-pi-packages-the-ecosystem.md @@ -38,6 +38,6 @@ Or just use conventional directory names (`extensions/`, `skills/`, `prompts/`, - [Package gallery](https://shittycodingagent.ai/packages) - [npm search](https://www.npmjs.com/search?q=keywords%3Api-package) -- [Discord community](https://discord.com/invite/3cU7Bz4UPx) +- [Discord community](https://discord.com/invite/nKXTsAcmbT) --- diff --git a/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md b/docs/dev/what-is-pi/16-why-pi-matters-what-makes-it-different.md similarity index 100% rename from docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md rename to docs/dev/what-is-pi/16-why-pi-matters-what-makes-it-different.md diff --git a/docs/what-is-pi/17-file-reference-all-documentation.md b/docs/dev/what-is-pi/17-file-reference-all-documentation.md similarity index 100% rename from docs/what-is-pi/17-file-reference-all-documentation.md rename to docs/dev/what-is-pi/17-file-reference-all-documentation.md diff --git a/docs/what-is-pi/18-quick-reference-commands-shortcuts.md b/docs/dev/what-is-pi/18-quick-reference-commands-shortcuts.md similarity index 100% rename from docs/what-is-pi/18-quick-reference-commands-shortcuts.md rename to docs/dev/what-is-pi/18-quick-reference-commands-shortcuts.md diff --git a/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md b/docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md similarity index 100% rename from docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md rename to docs/dev/what-is-pi/19-building-branded-apps-on-top-of-pi.md diff --git a/docs/what-is-pi/README.md b/docs/dev/what-is-pi/README.md similarity index 100% rename from docs/what-is-pi/README.md rename to docs/dev/what-is-pi/README.md diff --git a/docs/dynamic-model-routing.md b/docs/dynamic-model-routing.md deleted file mode 100644 index 9d0d5525e..000000000 --- a/docs/dynamic-model-routing.md +++ /dev/null @@ -1,127 +0,0 @@ -# Dynamic Model Routing - -*Introduced in v2.19.0* - -Dynamic model routing automatically selects cheaper models for simple work and reserves expensive models for complex tasks. This reduces token consumption by 20-50% on capped plans without sacrificing quality where it matters. - -## How It Works - -Each unit dispatched by auto-mode is classified into a complexity tier: - -| Tier | Typical Work | Default Model Level | -|------|-------------|-------------------| -| **Light** | Slice completion, UAT, hooks | Haiku-class | -| **Standard** | Research, planning, execution, milestone completion | Sonnet-class | -| **Heavy** | Replanning, roadmap reassessment, complex execution | Opus-class | - -The router then selects a model for that tier. The key rule: **downgrade-only semantics**. The user's configured model is always the ceiling — routing never upgrades beyond what you've configured. - -## Enabling - -Dynamic routing is off by default. Enable it in preferences: - -```yaml ---- -version: 1 -dynamic_routing: - enabled: true ---- -``` - -## Configuration - -```yaml -dynamic_routing: - enabled: true - tier_models: # explicit model per tier (optional) - light: claude-haiku-4-5 - standard: claude-sonnet-4-6 - heavy: claude-opus-4-6 - escalate_on_failure: true # bump tier on task failure (default: true) - budget_pressure: true # auto-downgrade when approaching budget ceiling (default: true) - cross_provider: true # consider models from other providers (default: true) - hooks: true # apply routing to post-unit hooks (default: true) -``` - -### `tier_models` - -Override which model is used for each tier. When omitted, the router uses a built-in capability mapping that knows common model families: - -- **Light:** `claude-haiku-4-5`, `gpt-4o-mini`, `gemini-2.0-flash` -- **Standard:** `claude-sonnet-4-6`, `gpt-4o`, `gemini-2.5-pro` -- **Heavy:** `claude-opus-4-6`, `gpt-4.5-preview`, `gemini-2.5-pro` - -### `escalate_on_failure` - -When a task fails at a given tier, the router escalates to the next tier on retry. Light → Standard → Heavy. This prevents cheap models from burning retries on work that needs more reasoning. - -### `budget_pressure` - -When approaching the budget ceiling, the router progressively downgrades: - -| Budget Used | Effect | -|------------|--------| -| < 50% | No adjustment | -| 50-75% | Standard → Light | -| 75-90% | More aggressive downgrading | -| > 90% | Nearly everything → Light; only Heavy stays at Standard | - -### `cross_provider` - -When enabled, the router may select models from providers other than your primary. This uses the built-in cost table to find the cheapest model at each tier. Requires the target provider to be configured. - -## Complexity Classification - -Units are classified using pure heuristics — no LLM calls, sub-millisecond: - -### Unit Type Defaults - -| Unit Type | Default Tier | -|-----------|-------------| -| `complete-slice`, `run-uat` | Light | -| `research-*`, `plan-*`, `complete-milestone` | Standard | -| `execute-task` | Standard (upgraded by task analysis) | -| `replan-slice`, `reassess-roadmap` | Heavy | -| `hook/*` | Light | - -### Task Plan Analysis - -For `execute-task` units, the classifier analyzes the task plan: - -| Signal | Simple → Light | Complex → Heavy | -|--------|---------------|----------------| -| Step count | ≤ 3 | ≥ 8 | -| File count | ≤ 3 | ≥ 8 | -| Description length | < 500 chars | > 2000 chars | -| Code blocks | — | ≥ 5 | -| Complexity keywords | None | Present | - -**Complexity keywords:** `research`, `investigate`, `refactor`, `migrate`, `integrate`, `complex`, `architect`, `redesign`, `security`, `performance`, `concurrent`, `parallel`, `distributed`, `backward compat` - -### Adaptive Learning - -The routing history (`.gsd/routing-history.json`) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20% for a given pattern, future classifications are bumped up. User feedback (`over`/`under`/`ok`) is weighted 2× vs automatic outcomes. - -## Interaction with Token Profiles - -Dynamic routing and token profiles are complementary: - -- **Token profiles** (`budget`/`balanced`/`quality`) control phase skipping and context compression -- **Dynamic routing** controls per-unit model selection within the configured phase model - -When both are active, token profiles set the baseline models and dynamic routing further optimizes within those baselines. The `budget` token profile + dynamic routing provides maximum cost savings. - -## Cost Table - -The router includes a built-in cost table for common models, used for cross-provider cost comparison. Costs are per-million tokens (input/output): - -| Model | Input | Output | -|-------|-------|--------| -| claude-haiku-4-5 | $0.80 | $4.00 | -| claude-sonnet-4-6 | $3.00 | $15.00 | -| claude-opus-4-6 | $15.00 | $75.00 | -| gpt-4o-mini | $0.15 | $0.60 | -| gpt-4o | $2.50 | $10.00 | -| gemini-2.0-flash | $0.10 | $0.40 | - -The cost table is used for comparison only — actual billing comes from your provider. diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 4c2392556..000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,198 +0,0 @@ -# Getting Started - -## Install - -```bash -npm install -g gsd-pi -``` - -Requires Node.js ≥ 22.0.0 (24 LTS recommended) and Git. - -> **`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [Troubleshooting](./troubleshooting.md#command-not-found-gsd-after-install) for details. - -GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`. - -### Set up API keys - -If you use a non-Anthropic model, you'll need a search API key for web search. Run `/gsd config` to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects: - -```bash -# Inside any GSD session: -/gsd config -``` - -See [Global API Keys](./configuration.md#global-api-keys-gsd-config) for details on supported keys. - -### Set up custom MCP servers - -If you want GSD to call local or external MCP servers, add project-local config in `.mcp.json` or `.gsd/mcp.json`. - -See [Configuration → MCP Servers](./configuration.md#mcp-servers) for examples and verification steps. - -### VS Code Extension - -GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides: - -- **`@gsd` chat participant** — talk to the agent in VS Code Chat -- **Sidebar dashboard** — connection status, model info, token usage, quick actions -- **Full command palette** — start/stop agent, switch models, export sessions - -The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC. - -### Web Interface - -GSD also has a browser-based interface. Run `gsd --web` to start a local web server with a visual dashboard, real-time progress, and multi-project support. See [Web Interface](./web-interface.md) for details. - -## First Launch - -Run `gsd` in any directory: - -```bash -gsd -``` - -GSD displays a welcome screen showing your version, active model, and available tool keys. Then on first launch, it runs a setup wizard: - -1. **LLM Provider** — select from 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). OAuth flows handle Claude Max and Copilot subscriptions automatically; otherwise paste an API key. -2. **Tool API Keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any. - -If you have an existing Pi installation, provider credentials are imported automatically. - -Re-run the wizard anytime with: - -```bash -gsd config -``` - -## Choose a Model - -GSD auto-selects a default model after login. Switch later with: - -``` -/model -``` - -Or configure per-phase models in preferences — see [Configuration](./configuration.md). - -## Two Ways to Work - -### Step Mode — `/gsd` - -Type `/gsd` inside a session. GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. - -- **No `.gsd/` directory** → starts a discussion flow to capture your project vision -- **Milestone exists, no roadmap** → discuss or research the milestone -- **Roadmap exists, slices pending** → plan the next slice or execute a task -- **Mid-task** → resume where you left off - -Step mode is the on-ramp. You stay in the loop, reviewing output between each step. - -### Auto Mode — `/gsd auto` - -Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. - -``` -/gsd auto -``` - -See [Auto Mode](./auto-mode.md) for full details. - -## Two Terminals, One Project - -The recommended workflow: auto mode in one terminal, steering from another. - -**Terminal 1 — let it build:** - -```bash -gsd -/gsd auto -``` - -**Terminal 2 — steer while it works:** - -```bash -gsd -/gsd discuss # talk through architecture decisions -/gsd status # check progress -/gsd queue # queue the next milestone -``` - -Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically. - -## Project Structure - -GSD organizes work into a hierarchy: - -``` -Milestone → a shippable version (4-10 slices) - Slice → one demoable vertical capability (1-7 tasks) - Task → one context-window-sized unit of work -``` - -The iron rule: **a task must fit in one context window.** If it can't, it's two tasks. - -All state lives on disk in `.gsd/`: - -``` -.gsd/ - PROJECT.md — what the project is right now - REQUIREMENTS.md — requirement contract (active/validated/deferred) - DECISIONS.md — append-only architectural decisions - KNOWLEDGE.md — cross-session rules, patterns, and lessons - RUNTIME.md — runtime context: API endpoints, env vars, services (v2.39) - STATE.md — quick-glance status - milestones/ - M001/ - M001-ROADMAP.md — slice plan with risk levels and dependencies - M001-CONTEXT.md — scope and goals from discussion - slices/ - S01/ - S01-PLAN.md — task decomposition - S01-SUMMARY.md — what happened - S01-UAT.md — human test script - tasks/ - T01-PLAN.md - T01-SUMMARY.md -``` - -## Resume a Session - -```bash -gsd --continue # or gsd -c -``` - -Resumes the most recent session for the current directory. - -To browse and pick from all saved sessions: - -```bash -gsd sessions -``` - -Shows each session's date, message count, and first-message preview so you can choose which one to resume. - -## Next Steps - -- [Auto Mode](./auto-mode.md) — deep dive into autonomous execution -- [Configuration](./configuration.md) — model selection, timeouts, budgets -- [Commands Reference](./commands.md) — all commands and shortcuts - -## Troubleshooting - -### `gsd` command runs `git svn dcommit` instead of GSD - -The [oh-my-zsh git plugin](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git) defines `alias gsd='git svn dcommit'`, which shadows the GSD binary. - -**Option 1** — Remove the alias in your `~/.zshrc` (add after the `source $ZSH/oh-my-zsh.sh` line): - -```bash -unalias gsd 2>/dev/null -``` - -**Option 2** — Use the alternative binary name: - -```bash -gsd-cli -``` - -Both `gsd` and `gsd-cli` point to the same binary. diff --git a/docs/auto-mode.md b/docs/user-docs/auto-mode.md similarity index 100% rename from docs/auto-mode.md rename to docs/user-docs/auto-mode.md diff --git a/docs/captures-triage.md b/docs/user-docs/captures-triage.md similarity index 100% rename from docs/captures-triage.md rename to docs/user-docs/captures-triage.md diff --git a/docs/user-docs/claude-code-auth-compliance.md b/docs/user-docs/claude-code-auth-compliance.md new file mode 100644 index 000000000..0c6b77466 --- /dev/null +++ b/docs/user-docs/claude-code-auth-compliance.md @@ -0,0 +1,177 @@ +# Claude Code Auth Compliance Research + +Date: 2026-04-10 + +## Executive Summary + +Anthropic's current public guidance draws a hard line: + +- Native Anthropic apps, including Claude Code, may use Claude subscription authentication. +- Third-party tools should prefer API key authentication through Claude Console or a supported cloud provider. +- Apps that misrepresent their identity, route third-party traffic against subscription limits, or otherwise violate Anthropic terms are explicitly prohibited. + +For GSD2, the safe path is: + +1. Treat local Claude Code as an external authenticated runtime. +2. Never ask GSD users to sign into Claude subscriptions through GSD-managed Anthropic OAuth. +3. Never exchange Claude.ai subscription OAuth into a bearer token and call Anthropic APIs as if GSD were Claude Code. +4. If GSD needs direct Anthropic API access, require a Claude Console API key, Bedrock, Vertex, or another explicitly supported provider path. + +## What Anthropic Explicitly Allows + +### 1. Claude Code itself can use Claude subscription auth + +Anthropic's help center says Claude Pro/Max users should install Claude Code, run `claude`, and "log in with the same credentials you use for Claude." It also says this connects the subscription directly to Claude Code, and that `/login` is the way to switch account types. The Team/Enterprise article gives the same flow for org accounts. + +Implication for GSD2: + +- Letting users authenticate inside the real `claude` CLI is aligned with Anthropic's documented flow. +- Detecting `claude auth status` and routing work through the local CLI or official Claude Code SDK is the lowest-risk pattern. + +### 2. Claude Code supports both subscription OAuth and API credentials + +Anthropic's Claude Code docs say supported auth types include Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth. The docs also define auth precedence: + +1. cloud provider credentials +2. `ANTHROPIC_AUTH_TOKEN` +3. `ANTHROPIC_API_KEY` +4. `apiKeyHelper` +5. subscription OAuth from `/login` + +Implication for GSD2: + +- If GSD2 shells out to or embeds Claude Code, it should respect Claude Code's own credential selection instead of inventing a parallel Anthropic OAuth flow. +- `apiKeyHelper` is the clean enterprise escape hatch when an org wants dynamic short-lived keys without handing raw API keys to the tool. + +### 3. Anthropic commercial usage is available through API keys and supported cloud providers + +Anthropic's commercial terms govern API keys and related Anthropic services for customer-built products, including products made available to end users. The authentication docs for teams recommend Claude for Teams/Enterprise, Claude Console, Bedrock, Vertex, or Microsoft Foundry. + +Implication for GSD2: + +- If GSD2 is acting as a product for users, direct Anthropic access should be through commercial auth paths, not subscription-token reuse. + +## What Anthropic Explicitly Warns Against + +Anthropic's current "Logging in to your Claude account" article is the clearest statement: + +- Subscription plans are for ordinary use of native Anthropic apps, including Claude web, desktop, mobile, and Claude Code. +- "The preferred way" for third-party tools, including open-source projects, is API key auth through Claude Console or a supported cloud provider. +- If you're building a product, application, or tool for others, use API key auth through Claude Console or a supported cloud provider. +- Tools that misrepresent identity, route third-party traffic against subscription limits, or otherwise violate terms are prohibited. + +Anthropic's consumer terms add two more constraints: + +- Users may not share account login info, API keys, or account credentials with anyone else. +- Except when accessing services via an Anthropic API key or where Anthropic explicitly permits it, users may not access the services through automated or non-human means. + +Implication for GSD2: + +- A GSD-managed Anthropic OAuth flow for subscription accounts is high risk. +- Reusing user Claude subscription credentials inside GSD's own API client is high risk. +- Any flow that makes Anthropic believe requests come from Claude Code when they actually come from GSD infrastructure is out of bounds. + +## Current GSD2 Findings + +### Low-risk / aligned pieces + +- `src/resources/extensions/claude-code-cli/index.ts` + Registers `claude-code` as an `externalCli` provider and routes through Anthropic's official `@anthropic-ai/claude-agent-sdk`. +- `src/resources/extensions/claude-code-cli/readiness.ts` + Only checks local CLI presence and auth state via `claude --version` and `claude auth status`. +- `src/onboarding.ts` + TUI onboarding already removed Anthropic browser OAuth and labels local Claude Code routing as the TOS-compliant path. +- `src/cli.ts` + Migrates users from `anthropic` to `claude-code` when the local CLI is available. + +These are directionally correct because GSD is using the user's own local Claude Code installation as the authenticated Anthropic surface. + +### Medium/high-risk pieces — RESOLVED + +All Anthropic OAuth code paths have been removed: + +- `packages/pi-ai/src/utils/oauth/anthropic.ts` — **Deleted.** No longer implements Anthropic OAuth flow. +- `packages/pi-ai/src/utils/oauth/index.ts` — **Updated.** `anthropicOAuthProvider` removed from built-in registry. +- `src/web/onboarding-service.ts` — **Updated.** Anthropic set to `supportsOAuth: false`. +- `packages/daemon/src/orchestrator.ts` — **Updated.** OAuth token refresh removed; requires `ANTHROPIC_API_KEY` env var. +- `packages/pi-ai/src/providers/anthropic.ts` — **Updated.** OAuth client branch removed; `isOAuthToken` always returns false. + +## Recommended Policy For GSD2 + +Adopt this as the repo rule: + +- Claude subscription auth is allowed only inside Anthropic-owned surfaces: + - the `claude` CLI + - Claude Code SDK when it is backed by the local authenticated Claude Code install + - other Anthropic-documented native flows +- GSD2 must not implement its own Anthropic subscription OAuth flow for end users. +- GSD2 must not persist Anthropic subscription OAuth tokens for later API use. +- GSD2 must not send Anthropic API traffic using subscription OAuth tokens obtained by GSD. +- GSD2 may support Anthropic direct access only via: + - `ANTHROPIC_API_KEY` + - Claude Console API keys stored in auth storage + - `apiKeyHelper` + - Bedrock / Vertex / Foundry + - the local Claude Code provider + +## Recommended Implementation Plan + +### Option A: Safe minimal compliance cleanup + +1. Remove Anthropic from the built-in OAuth provider registry. +2. Change web onboarding so Anthropic is API-key only. +3. Keep `claude-code` as the recommended path when `claude auth status` succeeds. +4. Add explicit UI copy: + - "Claude subscription users: sign into the local Claude Code app/CLI, not GSD." +5. Block migrations or code paths that convert Anthropic OAuth credentials into API auth for GSD-managed requests. + +This is the fastest path to align the repo with Anthropic's published guidance. + +### Option B: Enterprise-safe Anthropic support + +Support three distinct Anthropic modes: + +- `claude-code` + Uses the local authenticated `claude` runtime only. +- `anthropic-api` + Uses Console API keys or `apiKeyHelper`. +- `anthropic-cloud` + Uses Bedrock, Vertex, or Foundry. + +Then remove any ambiguous `anthropic` browser-login path entirely. + +This is the best long-term UX because it separates: + +- subscription-native usage +- API-billed usage +- cloud-routed usage + +## Concrete Repo Follow-ups — COMPLETED + +1. ~~Delete or disable `packages/pi-ai/src/utils/oauth/anthropic.ts`.~~ **Done** — file deleted. +2. ~~Remove `anthropicOAuthProvider` from `packages/pi-ai/src/utils/oauth/index.ts`.~~ **Done.** +3. ~~Change `src/web/onboarding-service.ts` so Anthropic does not claim OAuth support.~~ **Done.** +4. ~~Audit `packages/daemon/src/orchestrator.ts` and any other callers that treat Anthropic OAuth access tokens as API credentials.~~ **Done** — daemon now requires `ANTHROPIC_API_KEY`. +5. ~~Update docs/UI labels to prefer `anthropic-api` for direct API usage and `claude-code` for subscription usage.~~ **Done** — providers.md and getting-started.md updated. +6. Add tests that fail if Anthropic subscription OAuth is reintroduced through the onboarding/provider registry. — **TODO.** + +## Decision Rule + +If a proposed GSD2 feature needs Anthropic access, ask one question: + +"Is GSD calling Anthropic as GSD, or is GSD delegating to the user's already-authenticated local Claude Code runtime?" + +- If GSD is calling Anthropic as GSD: require API key or supported cloud auth. +- If GSD is delegating to local Claude Code: acceptable, as long as GSD does not intercept, mint, or replay subscription credentials itself. + +## Sources Reviewed + +- Anthropic Help Center: "Logging in to your Claude account" +- Anthropic Help Center: "Using Claude Code with your Pro or Max plan" +- Anthropic Help Center: "Use Claude Code with your Team or Enterprise plan" +- Anthropic Help Center: "Managing API key environment variables in Claude Code" +- Anthropic Help Center: "API Key Best Practices: Keeping Your Keys Safe and Secure" +- Claude Code Docs: getting started / authentication / team / settings / IAM +- Anthropic Commercial Terms of Service +- Anthropic Consumer Terms of Service +- Anthropic Usage Policy diff --git a/docs/commands.md b/docs/user-docs/commands.md similarity index 100% rename from docs/commands.md rename to docs/user-docs/commands.md diff --git a/docs/configuration.md b/docs/user-docs/configuration.md similarity index 89% rename from docs/configuration.md rename to docs/user-docs/configuration.md index 0d8712d5c..b3e873e72 100644 --- a/docs/configuration.md +++ b/docs/user-docs/configuration.md @@ -148,6 +148,7 @@ Recommended verification order: - Use absolute paths for local executables and scripts when possible. - For `stdio` servers, prefer setting required environment variables directly in the MCP config instead of relying on an interactive shell profile. +- GSD and `gsd-mcp-server` both hydrate supported model and tool keys saved in `~/.gsd/agent/auth.json`, so MCP configs can safely reference them through `${ENV_VAR}` placeholders without committing raw credentials. - If a server is team-shared and safe to commit, `.mcp.json` is usually the better home. - If a server depends on machine-local paths, personal services, or local-only secrets, prefer `.gsd/mcp.json`. @@ -159,6 +160,8 @@ Recommended verification order: | `GSD_PROJECT_ID` | (auto-hash) | Override the automatic project identity hash. Per-project state goes to `$GSD_HOME/projects//` instead of the computed hash. Useful for CI/CD or sharing state across clones of the same repo. (v2.39) | | `GSD_STATE_DIR` | `$GSD_HOME` | Per-project state root. Controls where `projects//` directories are created. Takes precedence over `GSD_HOME` for project state. | | `GSD_CODING_AGENT_DIR` | `$GSD_HOME/agent` | Agent directory containing managed resources, extensions, and auth. Takes precedence over `GSD_HOME` for agent paths. | +| `GSD_ALLOWED_COMMAND_PREFIXES` | (built-in list) | Comma-separated command prefixes allowed for `!command` value resolution. Overrides `allowedCommandPrefixes` in settings.json. See [Custom Models — Command Allowlist](custom-models.md#command-allowlist). | +| `GSD_FETCH_ALLOWED_URLS` | (none) | Comma-separated hostnames exempted from `fetch_page` URL blocking. Overrides `fetchAllowedUrls` in settings.json. See [URL Blocking](#url-blocking-fetch_page). | ## All Settings @@ -346,6 +349,43 @@ verification_max_retries: 2 # max retry attempts (default: 2) | `verification_auto_fix` | boolean | `true` | Auto-retry when verification fails | | `verification_max_retries` | number | `2` | Maximum auto-fix retry attempts | +### URL Blocking (`fetch_page`) + +The `fetch_page` tool blocks requests to private and internal network addresses to prevent server-side request forgery (SSRF). This protects against the agent being tricked into accessing internal services, cloud metadata endpoints, or local files. + +**Blocked by default:** + +| Category | Examples | +|----------|----------| +| Private IP ranges | `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`, `127.x.x.x` | +| Link-local / cloud metadata | `169.254.x.x` (AWS/GCP instance metadata) | +| Cloud metadata hostnames | `metadata.google.internal`, `instance-data` | +| Localhost | `localhost` (any port) | +| Non-HTTP protocols | `file://`, `ftp://` | +| IPv6 private ranges | `::1`, `fc00:`, `fd`, `fe80:` | + +Public URLs (`https://example.com`, `http://8.8.8.8`) are not affected. + +**Allowing specific internal hosts:** + +If you need the agent to fetch from internal URLs (self-hosted docs, internal APIs behind a VPN), add their hostnames to `fetchAllowedUrls` in global settings (`~/.gsd/agent/settings.json`): + +```json +{ + "fetchAllowedUrls": ["internal-docs.company.com", "192.168.1.50"] +} +``` + +Alternatively, set the `GSD_FETCH_ALLOWED_URLS` environment variable (comma-separated). The env var takes precedence over settings.json: + +```bash +export GSD_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50" +``` + +Allowed hostnames bypass the blocklist checks. The protocol restriction (HTTP/HTTPS only) still applies — `file://` and `ftp://` cannot be allowlisted. + +> **Note:** This setting is global-only. Project-level settings.json cannot override the URL allowlist — this prevents a cloned repo from directing `fetch_page` at internal infrastructure. + ### `auto_report` (v2.26) Auto-generate HTML reports after milestone completion: @@ -647,6 +687,7 @@ Complexity-based model routing. See [Dynamic Model Routing](./dynamic-model-rout ```yaml dynamic_routing: enabled: true + capability_routing: true # score models by task capability (v2.59) tier_models: light: claude-haiku-4-5 standard: claude-sonnet-4-6 @@ -656,6 +697,18 @@ dynamic_routing: cross_provider: true ``` +### `context_management` (v2.59) + +Controls observation masking and tool result truncation during auto-mode sessions. Reduces context bloat between compactions with zero LLM overhead. + +```yaml +context_management: + observation_masking: true # replace old tool results with placeholders (default: true) + observation_mask_turns: 8 # keep results from last N user turns (1-50, default: 8) + compaction_threshold_percent: 0.70 # target compaction at 70% context usage (0.5-0.95, default: 0.70) + tool_result_max_chars: 800 # cap individual tool result content (200-10000, default: 800) +``` + ### `service_tier` (v2.42) OpenAI service tier preference for supported models. Toggle with `/gsd fast`. diff --git a/docs/cost-management.md b/docs/user-docs/cost-management.md similarity index 100% rename from docs/cost-management.md rename to docs/user-docs/cost-management.md diff --git a/docs/custom-models.md b/docs/user-docs/custom-models.md similarity index 89% rename from docs/custom-models.md rename to docs/user-docs/custom-models.md index 943d213bf..76e949676 100644 --- a/docs/custom-models.md +++ b/docs/user-docs/custom-models.md @@ -131,6 +131,36 @@ The `apiKey` and `headers` fields support three formats: "apiKey": "sk-..." ``` +#### Command Allowlist + +Shell commands (`!command`) are restricted to a set of known credential tools. Only commands starting with one of these are allowed to execute: + +`pass`, `op`, `aws`, `gcloud`, `vault`, `security`, `gpg`, `bw`, `gopass`, `lpass` + +Commands not on this list are blocked and the value resolves to `undefined`. A warning is written to stderr. + +Shell operators (`;`, `|`, `&`, `` ` ``, `$`, `>`, `<`) are also blocked in command arguments to prevent injection. + +**Customizing the allowlist:** + +If you use a credential tool not on the default list, override it in global settings (`~/.gsd/agent/settings.json`): + +```json +{ + "allowedCommandPrefixes": ["pass", "op", "sops", "doppler", "mycli"] +} +``` + +This replaces the default list entirely — include any defaults you still want. + +Alternatively, set the `GSD_ALLOWED_COMMAND_PREFIXES` environment variable (comma-separated). The env var takes precedence over settings.json: + +```bash +export GSD_ALLOWED_COMMAND_PREFIXES="pass,op,sops,doppler" +``` + +> **Note:** This setting is global-only. Project-level settings.json (`/.gsd/settings.json`) cannot override the command allowlist — this prevents a cloned repo from escalating command execution privileges. + ### Custom Headers ```json diff --git a/docs/user-docs/dynamic-model-routing.md b/docs/user-docs/dynamic-model-routing.md new file mode 100644 index 000000000..bc88df2bd --- /dev/null +++ b/docs/user-docs/dynamic-model-routing.md @@ -0,0 +1,285 @@ +# Dynamic Model Routing + +*Introduced in v2.19.0. Capability scoring introduced in v2.52.0.* + +Dynamic model routing automatically selects cheaper models for simple work and reserves expensive models for complex tasks. This reduces token consumption by 20-50% on capped plans without sacrificing quality where it matters. + +Starting in v2.52.0, the router uses **capability-aware scoring** to select the *best fit* model for each task, not just the cheapest one in the tier. + +## How It Works + +Each unit dispatched by auto-mode passes through a two-stage pipeline: + +**Stage 1: Complexity classification** — classifies the work into a tier (light/standard/heavy). + +**Stage 2: Capability scoring** — within the eligible tier, ranks available models by how well their capabilities match the task's requirements. + +The key rule: **downgrade-only semantics**. The user's configured model is always the ceiling — routing never upgrades beyond what you've configured. + +| Tier | Typical Work | Default Model Level | +|------|-------------|-------------------| +| **Light** | Slice completion, UAT, hooks | Haiku-class | +| **Standard** | Research, planning, execution, milestone completion | Sonnet-class | +| **Heavy** | Replanning, roadmap reassessment, complex execution | Opus-class | + +## Enabling + +Dynamic routing is off by default. Enable it in preferences: + +```yaml +--- +version: 1 +dynamic_routing: + enabled: true +--- +``` + +## Configuration + +```yaml +dynamic_routing: + enabled: true + tier_models: # explicit model per tier (optional) + light: claude-haiku-4-5 + standard: claude-sonnet-4-6 + heavy: claude-opus-4-6 + escalate_on_failure: true # bump tier on task failure (default: true) + budget_pressure: true # auto-downgrade when approaching budget ceiling (default: true) + cross_provider: true # consider models from other providers (default: true) + hooks: true # apply routing to post-unit hooks (default: true) + capability_routing: true # enable capability scoring within tier (default: true) +``` + +### `tier_models` + +Override which model is used for each tier. When omitted, the router uses a built-in capability mapping that knows common model families: + +- **Light:** `claude-haiku-4-5`, `gpt-4o-mini`, `gemini-2.0-flash` +- **Standard:** `claude-sonnet-4-6`, `gpt-4o`, `gemini-2.5-pro` +- **Heavy:** `claude-opus-4-6`, `gpt-4.5-preview`, `gemini-2.5-pro` + +### `escalate_on_failure` + +When a task fails at a given tier, the router escalates to the next tier on retry. Light → Standard → Heavy. This prevents cheap models from burning retries on work that needs more reasoning. + +### `budget_pressure` + +When approaching the budget ceiling, the router progressively downgrades: + +| Budget Used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard → Light | +| 75-90% | More aggressive downgrading | +| > 90% | Nearly everything → Light; only Heavy stays at Standard | + +### `cross_provider` + +When enabled, the router may select models from providers other than your primary. This uses the built-in cost table to find the cheapest model at each tier. Requires the target provider to be configured. + +### `capability_routing` + +When enabled (default: true), the router uses capability scoring to pick the best model in a tier rather than always defaulting to the cheapest. Set to `false` to revert to cheapest-in-tier behavior: + +```yaml +dynamic_routing: + enabled: true + capability_routing: false # disable scoring, use cheapest-in-tier +``` + +## Capability Profiles + +Each model has a built-in **capability profile** — a 7-dimension score (0–100) representing how well it handles different task types: + +| Dimension | What It Represents | +|-----------|-------------------| +| `coding` | Code generation and implementation accuracy | +| `debugging` | Diagnosing and fixing errors | +| `research` | Synthesizing information and exploring topics | +| `reasoning` | Multi-step logical reasoning | +| `speed` | Latency and throughput (inverse of capability depth) | +| `longContext` | Handling large codebases and long documents | +| `instruction` | Following structured instructions precisely | + +**Built-in profiles** exist for 9 models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `gpt-4o`, `gpt-4o-mini`, `gemini-2.5-pro`, `gemini-2.0-flash`, `deepseek-chat`, `o3`. + +Models without a built-in profile receive **uniform scores of 50** across all dimensions. This is a cold-start policy — unknown models compete but don't have an advantage. From the user's perspective, routing behaves the same as before capability scoring was introduced for those models. + +**Profiles are heuristic rankings, not benchmarks.** They represent approximate relative strengths, not verified benchmark results. Use user overrides (below) to correct them for models you know well. + +## How Scoring Works + +The routing pipeline within a tier: + +``` +classify complexity tier + ↓ +filter eligible models for tier + ↓ +fire before_model_select hook (optional override) + ↓ +capability score eligible models + ↓ +select winner (or first eligible if scoring is disabled) +``` + +**Scoring formula:** weighted average of capability dimensions + +``` +score = Σ(weight × capability) / Σ(weights) +``` + +**Task requirements** are dynamic — different task types weight dimensions differently: + +| Unit Type | Key Dimensions | +|-----------|---------------| +| `execute-task` | coding (0.9), instruction (0.7), speed (0.3) | +| `research-*` | research (0.9), longContext (0.7), reasoning (0.5) | +| `plan-*` | reasoning (0.9), coding (0.5) | +| `replan-slice` | reasoning (0.9), debugging (0.6), coding (0.5) | +| `complete-slice`, `run-uat` | instruction (0.8), speed (0.7) | + +For `execute-task`, requirements are further refined by task metadata signals: +- Tags like `docs`, `config`, `readme` → boost instruction weight +- Keywords like `concurrency`, `compatibility` → boost debugging and reasoning +- Keywords like `migration`, `architecture` → boost reasoning and coding +- Large file counts (≥6) or large estimated line counts (≥500) → boost coding and reasoning + +**Tie-breaking:** When two models score within 2 points of each other, the cheaper model wins. If costs are equal, lexicographic model ID breaks the tie (deterministic). + +## User Overrides + +Correct built-in capability profiles for models you know well using `modelOverrides` in your models configuration: + +```json +{ + "providers": { + "anthropic": { + "modelOverrides": { + "claude-sonnet-4-6": { + "capabilities": { + "debugging": 90, + "research": 85 + } + } + } + } + } +} +``` + +Overrides are **deep-merged** with built-in defaults — only the specified dimensions are overridden; others retain their built-in values. + +**Use case:** You've found that a model consistently outperforms its built-in profile on specific task types. Override the relevant dimensions to steer the router toward that model for those tasks. + +## Verbose Output + +When verbose mode is active, the router logs its routing decision. When capability scoring was used, the log includes a full scoring breakdown: + +``` +Dynamic routing [S]: claude-sonnet-4-6 (capability-scored) — claude-sonnet-4-6: 82.3, gpt-4o: 78.1, deepseek-chat: 72.0 +``` + +When tier-only routing was used (scoring disabled, single eligible model, or routing guards applied): + +``` +Dynamic routing [S]: claude-sonnet-4-6 (standard complexity, multiple steps) +``` + +The `selectionMethod` field in the routing decision indicates which path was taken: +- `"capability-scored"` — capability scoring selected the winner +- `"tier-only"` — cheapest in tier (or explicit pin) was used + +## Extension Hook + +Extensions can intercept and override model selection using the `before_model_select` hook. + +The hook fires **after** tier filtering (eligible models are known) and **before** capability scoring (scores have not been computed yet). A hook can override selection entirely or return `undefined` to let scoring proceed normally. + +**Registering a handler:** + +```typescript +pi.on("before_model_select", async (event) => { + const { unitType, unitId, classification, taskMetadata, eligibleModels, phaseConfig } = event; + + // Custom routing strategy: always use gemini for research tasks + if (unitType.startsWith("research-")) { + const gemini = eligibleModels.find(id => id.includes("gemini")); + if (gemini) return { modelId: gemini }; + } + + // Return undefined to let capability scoring proceed + return undefined; +}); +``` + +**Event payload:** + +| Field | Type | Description | +|-------|------|-------------| +| `unitType` | `string` | The unit type being dispatched (e.g., `"execute-task"`) | +| `unitId` | `string` | Unique identifier for this unit dispatch | +| `classification` | `{ tier, reason, downgraded }` | The complexity classification result | +| `taskMetadata` | `Record \| undefined` | Task metadata extracted from the unit plan | +| `eligibleModels` | `string[]` | Models eligible for the classified tier | +| `phaseConfig` | `{ primary, fallbacks } \| undefined` | The user's configured model for this phase | + +**Return value:** `{ modelId: string }` to override selection, or `undefined` to defer to capability scoring. + +**First-override-wins:** If multiple extensions register handlers, the first one to return a non-undefined result wins. Subsequent handlers are not called. + +## Complexity Classification + +Units are classified using pure heuristics — no LLM calls, sub-millisecond: + +### Unit Type Defaults + +| Unit Type | Default Tier | +|-----------|-------------| +| `complete-slice`, `run-uat` | Light | +| `research-*`, `plan-*`, `complete-milestone` | Standard | +| `execute-task` | Standard (upgraded by task analysis) | +| `replan-slice`, `reassess-roadmap` | Heavy | +| `hook/*` | Light | + +### Task Plan Analysis + +For `execute-task` units, the classifier analyzes the task plan: + +| Signal | Simple → Light | Complex → Heavy | +|--------|---------------|----------------| +| Step count | ≤ 3 | ≥ 8 | +| File count | ≤ 3 | ≥ 8 | +| Description length | < 500 chars | > 2000 chars | +| Code blocks | — | ≥ 5 | +| Complexity keywords | None | Present | + +**Complexity keywords:** `research`, `investigate`, `refactor`, `migrate`, `integrate`, `complex`, `architect`, `redesign`, `security`, `performance`, `concurrent`, `parallel`, `distributed`, `backward compat` + +### Adaptive Learning + +The routing history (`.gsd/routing-history.json`) tracks success/failure per tier per unit type. If a tier's failure rate exceeds 20% for a given pattern, future classifications are bumped up. User feedback (`over`/`under`/`ok`) is weighted 2× vs automatic outcomes. + +## Interaction with Token Profiles + +Dynamic routing and token profiles are complementary: + +- **Token profiles** (`budget`/`balanced`/`quality`) control phase skipping and context compression +- **Dynamic routing** controls per-unit model selection within the configured phase model + +When both are active, token profiles set the baseline models and dynamic routing further optimizes within those baselines. The `budget` token profile + dynamic routing provides maximum cost savings. + +## Cost Table + +The router includes a built-in cost table for common models, used for cross-provider cost comparison. Costs are per-million tokens (input/output): + +| Model | Input | Output | +|-------|-------|--------| +| claude-haiku-4-5 | $0.80 | $4.00 | +| claude-sonnet-4-6 | $3.00 | $15.00 | +| claude-opus-4-6 | $15.00 | $75.00 | +| gpt-4o-mini | $0.15 | $0.60 | +| gpt-4o | $2.50 | $10.00 | +| gemini-2.0-flash | $0.10 | $0.40 | + +The cost table is used for comparison only — actual billing comes from your provider. diff --git a/docs/user-docs/getting-started.md b/docs/user-docs/getting-started.md new file mode 100644 index 000000000..d095ef8f9 --- /dev/null +++ b/docs/user-docs/getting-started.md @@ -0,0 +1,473 @@ +# Getting Started with GSD + +GSD is an AI coding agent that handles planning, execution, verification, and shipping so you can focus on what to build. This guide walks you through installation on macOS, Windows, and Linux, then gets you running your first session. + +--- + +## Prerequisites + +| Requirement | Minimum | Recommended | +|-------------|---------|-------------| +| **[Node.js](https://nodejs.org/)** | 22.0.0 | 24 LTS | +| **[Git](https://git-scm.com/)** | 2.20+ | Latest | +| **LLM API key** | Any supported provider | Anthropic (Claude) | + +Don't have Node.js or Git yet? Follow the OS-specific instructions below. + +--- + +## Install by Operating System + +### macOS + +> **Downloads:** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/mac) | [Homebrew](https://brew.sh/) + +**Step 1 — Install Homebrew** (skip if you already have it): + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +**Step 2 — Install Node.js and Git:** + +```bash +brew install node git +``` + +**Step 3 — Verify dependencies are installed:** + +```bash +node --version # should print v22.x or higher +git --version # should print 2.20+ +``` + +**Step 4 — Install GSD:** + +```bash +npm install -g gsd-pi +``` + +**Step 5 — Set up your LLM provider:** + +```bash +# Option A: Set an environment variable (Anthropic recommended) +export ANTHROPIC_API_KEY="sk-ant-..." + +# Option B: Use the built-in config wizard +gsd config +``` + +To persist the key, add the export line to `~/.zshrc`: + +```bash +echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc +source ~/.zshrc +``` + +See [Provider Setup Guide](./providers.md) for all 20+ supported providers. + +**Step 6 — Launch GSD:** + +```bash +cd ~/my-project # navigate to any project +gsd # start a session +``` + +**Step 7 — Verify everything works:** + +```bash +gsd --version # prints the installed version +``` + +Inside the session, type `/model` to confirm your LLM is connected. + +> **Apple Silicon PATH fix:** If `gsd` isn't found after install, npm's global bin may not be in your PATH: +> ```bash +> echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc +> source ~/.zshrc +> ``` + +> **oh-my-zsh conflict:** The oh-my-zsh git plugin defines `alias gsd='git svn dcommit'`. Fix with `unalias gsd 2>/dev/null` in `~/.zshrc`, or use `gsd-cli` instead. + +--- + +### Windows + +> **Downloads:** [Node.js](https://nodejs.org/) | [Git for Windows](https://git-scm.com/download/win) | [Windows Terminal](https://aka.ms/terminal) + +#### Option A: winget (recommended for Windows 10/11) + +**Step 1 — Install Node.js and Git:** + +```powershell +winget install OpenJS.NodeJS.LTS +winget install Git.Git +``` + +**Step 2 — Restart your terminal** (close and reopen PowerShell or Windows Terminal). + +**Step 3 — Verify dependencies are installed:** + +```powershell +node --version # should print v22.x or higher +git --version # should print 2.20+ +``` + +**Step 4 — Install GSD:** + +```powershell +npm install -g gsd-pi +``` + +**Step 5 — Set up your LLM provider:** + +```powershell +# Option A: Set an environment variable (current session) +$env:ANTHROPIC_API_KEY = "sk-ant-..." + +# Option B: Use the built-in config wizard +gsd config +``` + +To persist the key permanently, add it via System Settings > Environment Variables, or run: + +```powershell +[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User") +``` + +See [Provider Setup Guide](./providers.md) for all 20+ supported providers. + +**Step 6 — Launch GSD:** + +```powershell +cd C:\Users\you\my-project # navigate to any project +gsd # start a session +``` + +**Step 7 — Verify everything works:** + +```powershell +gsd --version # prints the installed version +``` + +Inside the session, type `/model` to confirm your LLM is connected. + +#### Option B: Manual install + +1. Download and install [Node.js LTS](https://nodejs.org/) — check **"Add to PATH"** during setup +2. Download and install [Git for Windows](https://git-scm.com/download/win) — use default options +3. Open a **new** terminal, then follow Steps 3-7 above + +> **Windows tips:** +> - Use **Windows Terminal** or **PowerShell** for the best experience. Command Prompt works but has limited color support. +> - If `gsd` isn't recognized, restart your terminal. Windows needs a fresh terminal to pick up new PATH entries. +> - **WSL2** also works — install WSL, then follow the Linux instructions inside your distro. + +--- + +### Linux + +> **Downloads:** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/linux) | [nvm](https://github.com/nvm-sh/nvm) + +Pick your distro, then follow the steps. + +#### Ubuntu / Debian + +**Step 1 — Install Node.js and Git:** + +```bash +curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - +sudo apt-get install -y nodejs git +``` + +#### Fedora / RHEL / CentOS + +**Step 1 — Install Node.js and Git:** + +```bash +curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash - +sudo dnf install -y nodejs git +``` + +#### Arch Linux + +**Step 1 — Install Node.js and Git:** + +```bash +sudo pacman -S nodejs npm git +``` + +#### Using nvm (any distro) + +**Step 1 — Install nvm, then Node.js:** + +```bash +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash +source ~/.bashrc # or ~/.zshrc +nvm install 24 +nvm use 24 +``` + +#### All distros: Steps 2-7 + +**Step 2 — Verify dependencies are installed:** + +```bash +node --version # should print v22.x or higher +git --version # should print 2.20+ +``` + +**Step 3 — Install GSD:** + +```bash +npm install -g gsd-pi +``` + +**Step 4 — Set up your LLM provider:** + +```bash +# Option A: Set an environment variable (Anthropic recommended) +export ANTHROPIC_API_KEY="sk-ant-..." + +# Option B: Use the built-in config wizard +gsd config +``` + +To persist the key, add the export line to `~/.bashrc` (or `~/.zshrc`): + +```bash +echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc +source ~/.bashrc +``` + +See [Provider Setup Guide](./providers.md) for all 20+ supported providers. + +**Step 5 — Launch GSD:** + +```bash +cd ~/my-project # navigate to any project +gsd # start a session +``` + +**Step 6 — Verify everything works:** + +```bash +gsd --version # prints the installed version +``` + +Inside the session, type `/model` to confirm your LLM is connected. + +> **Permission errors on `npm install -g`?** Don't use `sudo npm`. Fix npm's global directory instead: +> ```bash +> mkdir -p ~/.npm-global +> npm config set prefix '~/.npm-global' +> echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc +> source ~/.bashrc +> npm install -g gsd-pi +> ``` + +--- + +### Docker (any OS) + +> **Downloads:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) + +Run GSD in an isolated sandbox without installing Node.js on your host. + +**Step 1 — Install Docker Desktop** (4.58+ required). + +**Step 2 — Clone the GSD repo:** + +```bash +git clone https://github.com/gsd-build/gsd-2.git +cd gsd-2/docker +``` + +**Step 3 — Create and enter a sandbox:** + +```bash +docker sandbox create --template . --name gsd-sandbox +docker sandbox exec -it gsd-sandbox bash +``` + +**Step 4 — Set your API key and run GSD:** + +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +gsd auto "implement the feature described in issue #42" +``` + +See [Docker Sandbox docs](../../docker/README.md) for full configuration, resource limits, and compose files. + +--- + +## After Installation + +### Choose a Model + +GSD auto-selects a default model after provider setup. Switch anytime inside a session: + +``` +/model +``` + +Or configure per-phase models in preferences — see [Configuration](./configuration.md). + +--- + +## Two Ways to Work + +### Step Mode — `/gsd` + +Type `/gsd` inside a session. GSD executes one unit of work at a time, pausing between each with a wizard showing what completed and what's next. + +- **No `.gsd/` directory** — starts a discussion flow to capture your project vision +- **Milestone exists, no roadmap** — discuss or research the milestone +- **Roadmap exists, slices pending** — plan the next slice or execute a task +- **Mid-task** — resume where you left off + +Step mode keeps you in the loop, reviewing output between each step. + +### Auto Mode — `/gsd auto` + +Type `/gsd auto` and walk away. GSD autonomously researches, plans, executes, verifies, commits, and advances through every slice until the milestone is complete. + +``` +/gsd auto +``` + +See [Auto Mode](./auto-mode.md) for full details. + +--- + +## Recommended Workflow: Two Terminals + +Run auto mode in one terminal, steer from another. + +**Terminal 1 — let it build:** + +```bash +gsd +/gsd auto +``` + +**Terminal 2 — steer while it works:** + +```bash +gsd +/gsd discuss # talk through architecture decisions +/gsd status # check progress +/gsd queue # queue the next milestone +``` + +Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically. + +--- + +## How GSD Organizes Work + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable vertical capability (1-7 tasks) + Task → one context-window-sized unit of work +``` + +The iron rule: **a task must fit in one context window.** If it can't, it's two tasks. + +All state lives on disk in `.gsd/`: + +``` +.gsd/ + PROJECT.md — what the project is right now + REQUIREMENTS.md — requirement contract + DECISIONS.md — append-only architectural decisions + KNOWLEDGE.md — cross-session rules and patterns + STATE.md — quick-glance status + milestones/ + M001/ + M001-ROADMAP.md — slice plan with dependencies + slices/ + S01/ + S01-PLAN.md — task decomposition + S01-SUMMARY.md — what happened +``` + +--- + +## VS Code Extension + +GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions: + +- **`@gsd` chat participant** — talk to the agent in VS Code Chat +- **Sidebar dashboard** — connection status, model info, token usage +- **Full command palette** — start/stop agent, switch models, export sessions + +The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC. + +--- + +## Web Interface + +GSD has a browser-based interface for visual project management: + +```bash +gsd --web +``` + +See [Web Interface](./web-interface.md) for details. + +--- + +## Resume a Session + +```bash +gsd --continue # or gsd -c +``` + +Resumes the most recent session for the current directory. + +Browse all saved sessions: + +```bash +gsd sessions +``` + +--- + +## Updating GSD + +GSD checks for updates every 24 hours and prompts at startup. You can also update manually: + +```bash +npm update -g gsd-pi +``` + +Or from within a session: + +``` +/gsd update +``` + +--- + +## Quick Troubleshooting + +| Problem | Fix | +|---------|-----| +| `command not found: gsd` | Add npm global bin to PATH (see OS-specific notes above) | +| `gsd` runs `git svn dcommit` | oh-my-zsh conflict — `unalias gsd` or use `gsd-cli` | +| Permission errors on `npm install -g` | Fix npm prefix (see Linux notes) or use nvm | +| Can't connect to LLM | Check API key with `gsd config`, verify network access | +| `gsd` hangs on start | Check Node.js version: `node --version` (need 22+) | + +For more, see [Troubleshooting](./troubleshooting.md). + +--- + +## Next Steps + +- [Auto Mode](./auto-mode.md) — deep dive into autonomous execution +- [Configuration](./configuration.md) — model selection, timeouts, budgets +- [Commands Reference](./commands.md) — all commands and shortcuts +- [Provider Setup](./providers.md) — detailed setup for every provider +- [Working in Teams](./working-in-teams.md) — multi-developer workflows diff --git a/docs/git-strategy.md b/docs/user-docs/git-strategy.md similarity index 100% rename from docs/git-strategy.md rename to docs/user-docs/git-strategy.md diff --git a/docs/migration.md b/docs/user-docs/migration.md similarity index 100% rename from docs/migration.md rename to docs/user-docs/migration.md diff --git a/docs/node-lts-macos.md b/docs/user-docs/node-lts-macos.md similarity index 100% rename from docs/node-lts-macos.md rename to docs/user-docs/node-lts-macos.md diff --git a/docs/parallel-orchestration.md b/docs/user-docs/parallel-orchestration.md similarity index 100% rename from docs/parallel-orchestration.md rename to docs/user-docs/parallel-orchestration.md diff --git a/docs/user-docs/providers.md b/docs/user-docs/providers.md new file mode 100644 index 000000000..cfa3df939 --- /dev/null +++ b/docs/user-docs/providers.md @@ -0,0 +1,653 @@ +# Provider Setup Guide + +Step-by-step setup instructions for every LLM provider GSD supports. If you ran the onboarding wizard (`gsd config`) and picked a provider, you may already be configured — check with `/model` inside a session. + +## Table of Contents + +- [Quick Reference](#quick-reference) +- [Built-in Providers](#built-in-providers) + - [Anthropic (Claude)](#anthropic-claude) + - [OpenAI](#openai) + - [Google Gemini](#google-gemini) + - [OpenRouter](#openrouter) + - [Groq](#groq) + - [xAI (Grok)](#xai-grok) + - [Mistral](#mistral) + - [GitHub Copilot](#github-copilot) + - [Amazon Bedrock](#amazon-bedrock) + - [Anthropic on Vertex AI](#anthropic-on-vertex-ai) + - [Azure OpenAI](#azure-openai) +- [Local Providers](#local-providers) + - [Ollama](#ollama) + - [LM Studio](#lm-studio) + - [vLLM](#vllm) + - [SGLang](#sglang) +- [Custom OpenAI-Compatible Endpoints](#custom-openai-compatible-endpoints) +- [Common Pitfalls](#common-pitfalls) +- [Verifying Your Setup](#verifying-your-setup) + +## Quick Reference + +| Provider | Auth Method | Env Variable | Config File | +|----------|-------------|-------------|-------------| +| Anthropic | API key | `ANTHROPIC_API_KEY` | — | +| OpenAI | API key | `OPENAI_API_KEY` | — | +| Google Gemini | API key | `GEMINI_API_KEY` | — | +| OpenRouter | API key | `OPENROUTER_API_KEY` | Optional `models.json` | +| Groq | API key | `GROQ_API_KEY` | — | +| xAI | API key | `XAI_API_KEY` | — | +| Mistral | API key | `MISTRAL_API_KEY` | — | +| GitHub Copilot | OAuth | `GH_TOKEN` | — | +| Amazon Bedrock | IAM credentials | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` | — | +| Vertex AI | ADC | `GOOGLE_APPLICATION_CREDENTIALS` | — | +| Azure OpenAI | API key | `AZURE_OPENAI_API_KEY` | — | +| Ollama | None (local) | — | `models.json` required | +| LM Studio | None (local) | — | `models.json` required | +| vLLM / SGLang | None (local) | — | `models.json` required | + +--- + +## Built-in Providers + +Built-in providers have models pre-registered in GSD. You only need to supply credentials. + +### Anthropic (Claude) + +**Recommended.** Anthropic models have the deepest integration: built-in web search, extended thinking, and prompt caching. + +**Option A — API key (recommended):** + +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +Or run `gsd config` and paste your key when prompted. + +**Get a key:** [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys) + +**Option B — Claude Code CLI:** + +If you have a Claude Pro or Max subscription, you can authenticate through Anthropic's official Claude Code CLI. Install it, sign in with `claude`, then GSD will detect and route through it automatically: + +```bash +# Install Claude Code CLI (see https://docs.anthropic.com/en/docs/claude-code) +claude +# Sign in when prompted, then start GSD +gsd +``` + +GSD detects your local Claude Code installation and uses it as the authenticated Anthropic surface. This is the TOS-compliant path for subscription users — GSD never handles your subscription credentials directly. + +> **Note:** GSD does not support browser-based OAuth sign-in for Anthropic. Use an API key or the Claude Code CLI instead. + +**Option C — Use your Claude Pro/Max plan with GSD inside Claude Code:** + +If you already have a Claude Pro or Max subscription and want to use GSD's planning, execution, and milestone orchestration directly from Claude Code — without switching to a separate terminal — you can connect GSD as an MCP server. This gives Claude Code access to GSD's full workflow toolset via the [Model Context Protocol](https://modelcontextprotocol.io), so you get GSD's structured project management powered by your existing Claude plan. + +**Automatic setup (recommended):** + +When GSD detects a Claude Code model during startup, it automatically writes a `.mcp.json` file in your project root with the GSD workflow MCP server configured. No manual steps needed — just start GSD once with Claude Code as the provider and the config is created for you. + +You can also trigger this manually from inside a GSD session: + +```bash +/gsd mcp init +``` + +This writes (or updates) the `gsd-workflow` entry in your project's `.mcp.json`. Claude Code discovers this file automatically on its next session start. + +**Manual setup:** + +If you prefer to configure it yourself, add GSD to your project's `.mcp.json`: + +```json +{ + "mcpServers": { + "gsd": { + "command": "npx", + "args": ["gsd-mcp-server"], + "env": { + "GSD_CLI_PATH": "/path/to/gsd" + } + } + } +} +``` + +Or if `gsd-mcp-server` is installed globally: + +```json +{ + "mcpServers": { + "gsd": { + "command": "gsd-mcp-server" + } + } +} +``` + +You can also add this to `~/.claude/settings.json` under `mcpServers` to make GSD available across all projects. + +**What's exposed:** + +The MCP server provides GSD's full workflow tool surface — milestone planning, task completion, slice management, roadmap reassessment, journal queries, and more. Session management tools (`gsd_execute`, `gsd_status`, `gsd_result`, `gsd_cancel`) let Claude Code start and monitor GSD auto-mode sessions. See [Commands → MCP Server Mode](./commands.md#mcp-server-mode) for the full tool list. + +**Verify the connection:** + +From inside a GSD session, check that the MCP server is reachable: + +```bash +/gsd mcp status +``` + +### OpenAI + +```bash +export OPENAI_API_KEY="sk-..." +``` + +Or run `gsd config` and choose "Paste an API key" then "OpenAI". + +**Get a key:** [platform.openai.com/api-keys](https://platform.openai.com/api-keys) + +### Google Gemini + +```bash +export GEMINI_API_KEY="..." +``` + +**Get a key:** [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) + +### OpenRouter + +OpenRouter aggregates 200+ models from multiple providers behind a single API key. + +**Step 1 — Get your API key:** + +Go to [openrouter.ai/keys](https://openrouter.ai/keys) and create a key. + +**Step 2 — Set the key:** + +```bash +export OPENROUTER_API_KEY="sk-or-..." +``` + +Or run `gsd config`, choose "Paste an API key", then "OpenRouter". + +**Step 3 — Switch to an OpenRouter model:** + +Inside a GSD session, type `/model` and select an OpenRouter model. Models are prefixed with `openrouter/` (e.g., `openrouter/anthropic/claude-sonnet-4`). + +**Optional — Add custom OpenRouter models via `models.json`:** + +If you want models not in the built-in list, add them to `~/.gsd/agent/models.json`: + +```json +{ + "providers": { + "openrouter": { + "baseUrl": "https://openrouter.ai/api/v1", + "apiKey": "OPENROUTER_API_KEY", + "api": "openai-completions", + "models": [ + { + "id": "meta-llama/llama-3.3-70b", + "name": "Llama 3.3 70B (OpenRouter)", + "reasoning": false, + "input": ["text"], + "contextWindow": 131072, + "maxTokens": 32768, + "cost": { "input": 0.3, "output": 0.3, "cacheRead": 0, "cacheWrite": 0 } + } + ] + } + } +} +``` + +Note: the `apiKey` field here is the *name* of the environment variable, not the literal key. GSD resolves it automatically. You can also use a literal value or a shell command (see [Value Resolution](./custom-models.md#value-resolution)). + +**Optional — Route through specific providers:** + +Use `modelOverrides` to control which upstream provider OpenRouter uses: + +```json +{ + "providers": { + "openrouter": { + "modelOverrides": { + "anthropic/claude-sonnet-4": { + "compat": { + "openRouterRouting": { + "only": ["amazon-bedrock"] + } + } + } + } + } + } +} +``` + +### Groq + +```bash +export GROQ_API_KEY="gsk_..." +``` + +**Get a key:** [console.groq.com/keys](https://console.groq.com/keys) + +### xAI (Grok) + +```bash +export XAI_API_KEY="xai-..." +``` + +**Get a key:** [console.x.ai](https://console.x.ai) + +### Mistral + +```bash +export MISTRAL_API_KEY="..." +``` + +**Get a key:** [console.mistral.ai/api-keys](https://console.mistral.ai/api-keys) + +### GitHub Copilot + +Uses OAuth — sign in through the browser: + +```bash +gsd config +# Choose "Sign in with your browser" → "GitHub Copilot" +``` + +Requires an active GitHub Copilot subscription. + +### Amazon Bedrock + +Bedrock uses AWS IAM credentials, not API keys. Any of these work: + +```bash +# Option 1: Named profile +export AWS_PROFILE="my-profile" + +# Option 2: IAM keys +export AWS_ACCESS_KEY_ID="AKIA..." +export AWS_SECRET_ACCESS_KEY="..." +export AWS_REGION="us-east-1" + +# Option 3: Bedrock API key (bearer token) +export AWS_BEARER_TOKEN_BEDROCK="..." +``` + +ECS task roles and IRSA (Kubernetes) are also detected automatically. + +### Anthropic on Vertex AI + +Uses Google Cloud Application Default Credentials: + +```bash +gcloud auth application-default login +export ANTHROPIC_VERTEX_PROJECT_ID="my-project-id" +``` + +Or set `GOOGLE_CLOUD_PROJECT` and ensure ADC credentials exist at `~/.config/gcloud/application_default_credentials.json`. + +### Azure OpenAI + +```bash +export AZURE_OPENAI_API_KEY="..." +``` + +--- + +## Local Providers + +Local providers run on your machine. They require a `models.json` configuration file because GSD needs to know the endpoint URL and which models are available. + +**Config file location:** `~/.gsd/agent/models.json` + +The file reloads each time you open `/model` — no restart needed. + +### Ollama + +**Step 1 — Install and start Ollama:** + +```bash +# macOS +brew install ollama +ollama serve + +# Or download from https://ollama.com +``` + +**Step 2 — Pull a model:** + +```bash +ollama pull llama3.1:8b +ollama pull qwen2.5-coder:7b +``` + +**Step 3 — Create `~/.gsd/agent/models.json`:** + +```json +{ + "providers": { + "ollama": { + "baseUrl": "http://localhost:11434/v1", + "api": "openai-completions", + "apiKey": "ollama", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { "id": "llama3.1:8b" }, + { "id": "qwen2.5-coder:7b" } + ] + } + } +} +``` + +The `apiKey` is required by the config schema but Ollama ignores it — any value works. + +**Step 4 — Select the model:** + +Inside GSD, type `/model` and pick your Ollama model. + +**Ollama tips:** +- Ollama does not support the `developer` role or `reasoning_effort` — always set `compat.supportsDeveloperRole: false` and `compat.supportsReasoningEffort: false`. +- If you get empty responses, check that `ollama serve` is running and the model is pulled. +- Context window and max tokens default to 128K / 16K if not specified. Override these if your model has different limits. + +### LM Studio + +**Step 1 — Install LM Studio:** + +Download from [lmstudio.ai](https://lmstudio.ai). + +**Step 2 — Start the local server:** + +In LM Studio, go to the "Local Server" tab, load a model, and click "Start Server". The default port is 1234. + +**Step 3 — Create `~/.gsd/agent/models.json`:** + +```json +{ + "providers": { + "lm-studio": { + "baseUrl": "http://localhost:1234/v1", + "api": "openai-completions", + "apiKey": "lm-studio", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { + "id": "your-model-name", + "name": "My Local Model", + "contextWindow": 32768, + "maxTokens": 4096 + } + ] + } + } +} +``` + +Replace `your-model-name` with the model identifier shown in LM Studio's server tab. + +**LM Studio tips:** +- The model ID in `models.json` must match what LM Studio reports in its server API. Check the server tab for the exact string. +- LM Studio defaults to port 1234. If you changed it, update `baseUrl` accordingly. +- Increase `contextWindow` and `maxTokens` if your model supports larger contexts. + +### vLLM + +```json +{ + "providers": { + "vllm": { + "baseUrl": "http://localhost:8000/v1", + "api": "openai-completions", + "apiKey": "vllm", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false, + "supportsUsageInStreaming": false + }, + "models": [ + { + "id": "meta-llama/Llama-3.1-8B-Instruct", + "contextWindow": 128000, + "maxTokens": 16384 + } + ] + } + } +} +``` + +The model `id` must match the `--model` flag you passed to `vllm serve`. + +### SGLang + +```json +{ + "providers": { + "sglang": { + "baseUrl": "http://localhost:30000/v1", + "api": "openai-completions", + "apiKey": "sglang", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { + "id": "meta-llama/Llama-3.1-8B-Instruct" + } + ] + } + } +} +``` + +--- + +## Custom OpenAI-Compatible Endpoints + +Any server that implements the OpenAI Chat Completions API can work with GSD. This covers proxies (LiteLLM, Portkey, Helicone), self-hosted inference, and new providers. + +**Quickest path — use the onboarding wizard:** + +```bash +gsd config +# Choose "Paste an API key" → "Custom (OpenAI-compatible)" +# Enter: base URL, API key, model ID +``` + +This writes `~/.gsd/agent/models.json` for you automatically. + +**Manual setup:** + +```json +{ + "providers": { + "my-provider": { + "baseUrl": "https://my-endpoint.example.com/v1", + "apiKey": "MY_PROVIDER_API_KEY", + "api": "openai-completions", + "models": [ + { + "id": "model-id-here", + "name": "Friendly Model Name", + "reasoning": false, + "input": ["text"], + "contextWindow": 128000, + "maxTokens": 16384, + "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 } + } + ] + } + } +} +``` + +**Adding custom headers (for proxies):** + +```json +{ + "providers": { + "litellm-proxy": { + "baseUrl": "https://litellm.example.com/v1", + "apiKey": "MY_API_KEY", + "api": "openai-completions", + "headers": { + "x-custom-header": "value" + }, + "models": [...] + } + } +} +``` + +**Qwen models with thinking mode:** + +For Qwen-compatible servers, use `thinkingFormat` to enable thinking mode: + +```json +{ + "compat": { + "thinkingFormat": "qwen", + "supportsDeveloperRole": false + } +} +``` + +Use `"qwen-chat-template"` instead if the server requires `chat_template_kwargs.enable_thinking`. + +For the full reference on `compat` fields, `modelOverrides`, value resolution, and advanced configuration, see [Custom Models](./custom-models.md). + +--- + +## Common Pitfalls + +### "Authentication failed" with a valid key + +**Cause:** The key is set in your shell but not visible to GSD. + +**Fix:** Make sure the environment variable is exported in the same terminal where you run `gsd`. Or use `gsd config` to save the key to `~/.gsd/agent/auth.json` so it persists across sessions. + +### OpenRouter models not appearing in `/model` + +**Cause:** No `OPENROUTER_API_KEY` set, so GSD hides OpenRouter models. + +**Fix:** Set the key and restart GSD: + +```bash +export OPENROUTER_API_KEY="sk-or-..." +gsd +``` + +### Ollama returns empty responses + +**Cause:** Ollama server isn't running, or the model isn't pulled. + +**Fix:** + +```bash +# Verify the server is running +curl http://localhost:11434/v1/models + +# Pull the model if missing +ollama pull llama3.1:8b +``` + +### LM Studio model ID mismatch + +**Cause:** The `id` in `models.json` doesn't match what LM Studio exposes via its API. + +**Fix:** Check the LM Studio server tab for the exact model identifier. It often includes the filename or quantization level (e.g., `lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF`). + +### `developer` role error with local models + +**Cause:** Most local inference servers don't support the OpenAI `developer` message role. + +**Fix:** Add `compat.supportsDeveloperRole: false` to the provider config. This makes GSD send `system` messages instead: + +```json +{ + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + } +} +``` + +### `stream_options` error with local models + +**Cause:** Some servers don't support `stream_options: { include_usage: true }`. + +**Fix:** Add `compat.supportsUsageInStreaming: false`: + +```json +{ + "compat": { + "supportsUsageInStreaming": false + } +} +``` + +### "apiKey is required" validation error + +**Cause:** `models.json` schema requires `apiKey` when `models` are defined. + +**Fix:** For local servers that don't need auth, set a dummy value: + +```json +"apiKey": "not-needed" +``` + +### Cost shows $0.00 for custom models + +**Expected behavior.** GSD defaults cost to zero for custom models. Override with the `cost` field if you want accurate cost tracking: + +```json +"cost": { "input": 0.15, "output": 0.60, "cacheRead": 0.015, "cacheWrite": 0.19 } +``` + +Values are per million tokens. + +--- + +## Verifying Your Setup + +After configuring a provider: + +1. **Launch GSD:** + ```bash + gsd + ``` + +2. **Check available models:** + ``` + /model + ``` + Your provider's models should appear in the list. + +3. **Switch to the model:** + Select it from the `/model` picker. + +4. **Send a test message:** + Type anything to confirm the model responds. + +If the model doesn't appear, check: +- The environment variable is set in the current shell +- `models.json` is valid JSON (use `cat ~/.gsd/agent/models.json | python3 -m json.tool`) +- The server is running (for local providers) + +For additional help, see [Troubleshooting](./troubleshooting.md) or run `/gsd doctor` inside a session. diff --git a/docs/remote-questions.md b/docs/user-docs/remote-questions.md similarity index 100% rename from docs/remote-questions.md rename to docs/user-docs/remote-questions.md diff --git a/docs/skills.md b/docs/user-docs/skills.md similarity index 100% rename from docs/skills.md rename to docs/user-docs/skills.md diff --git a/docs/token-optimization.md b/docs/user-docs/token-optimization.md similarity index 79% rename from docs/token-optimization.md rename to docs/user-docs/token-optimization.md index 5c5ea3466..4a3a423af 100644 --- a/docs/token-optimization.md +++ b/docs/user-docs/token-optimization.md @@ -262,15 +262,59 @@ PREFERENCES.md ├─ resolveProfileDefaults() → model defaults + phase skip defaults ├─ resolveInlineLevel() → standard │ └─ prompt builders gate context inclusion by level - └─ classifyUnitComplexity() → routes to execution/execution_simple model - ├─ task plan analysis (steps, files, signals) - ├─ unit type defaults - ├─ budget pressure adjustment - └─ adaptive learning from routing-history.json + ├─ classifyUnitComplexity() → routes to execution/execution_simple model + │ ├─ task plan analysis (steps, files, signals) + │ ├─ unit type defaults + │ ├─ budget pressure adjustment + │ ├─ adaptive learning from routing-history.json + │ └─ capability scoring (when capability_routing: true) + │ └─ 7-dimension model profiles × task requirement vectors + └─ context_management + ├─ observation masking (before_provider_request hook) + ├─ tool result truncation (tool_result_max_chars) + └─ phase handoff anchors (injected into prompt builders) ``` The profile is resolved once and flows through the entire dispatch pipeline. Explicit preferences override profile defaults at every layer. +## Observation Masking + +*Introduced in v2.59.0* + +During auto-mode sessions, tool results accumulate in the conversation history and consume context window space. Observation masking replaces tool result content older than N user turns with a lightweight placeholder before each LLM call. This reduces token usage with zero LLM overhead — no summarization calls, no latency. + +Masking is enabled by default during auto-mode. Configure via preferences: + +```yaml +context_management: + observation_masking: true # default: true (set false to disable) + observation_mask_turns: 8 # keep results from last 8 user turns (range: 1-50) + tool_result_max_chars: 800 # truncate individual tool results beyond this length +``` + +### How It Works + +1. Before each provider request, the `before_provider_request` hook inspects the messages array +2. Tool results (`toolResult`, `bashExecution`) older than the configured turn threshold are replaced with `[result masked — within summarized history]` +3. Recent tool results (within the keep window) are preserved in full +4. All assistant and user messages are always preserved — only tool result content is masked + +This pairs with the existing compaction system: masking reduces context pressure between compactions, and compaction handles the full context reset when the window fills. + +### Tool Result Truncation + +Individual tool results that exceed `tool_result_max_chars` (default: 800) are truncated with a `…[truncated]` marker. This prevents a single large tool output from dominating the context window. + +## Phase Handoff Anchors + +*Introduced in v2.59.0* + +When auto-mode transitions between phases (research → planning → execution), structured JSON anchors are written to `.gsd/milestones//anchors/.json`. Downstream prompt builders inject these anchors so the next phase inherits intent, decisions, blockers, and next steps without re-inferring from artifact files. + +This reduces context drift — the 65% of enterprise agent failures caused by agents losing track of prior decisions across phase boundaries. + +Anchors are written automatically after successful completion of `research-milestone`, `research-slice`, `plan-milestone`, and `plan-slice` units. No configuration needed. + ## Prompt Compression *Introduced in v2.29.0* diff --git a/docs/troubleshooting.md b/docs/user-docs/troubleshooting.md similarity index 99% rename from docs/troubleshooting.md rename to docs/user-docs/troubleshooting.md index aef19f982..875bba7fc 100644 --- a/docs/troubleshooting.md +++ b/docs/user-docs/troubleshooting.md @@ -97,6 +97,8 @@ models: **Headless mode:** `gsd headless auto` auto-restarts the entire process on crash (default 3 attempts with exponential backoff). Combined with provider error auto-resume, this enables true overnight unattended execution. +For common provider setup issues (role errors, streaming errors, model ID mismatches), see the [Provider Setup Guide — Common Pitfalls](./providers.md#common-pitfalls). + ### Budget ceiling reached **Symptoms:** Auto mode pauses with "Budget ceiling reached." diff --git a/docs/visualizer.md b/docs/user-docs/visualizer.md similarity index 100% rename from docs/visualizer.md rename to docs/user-docs/visualizer.md diff --git a/docs/web-interface.md b/docs/user-docs/web-interface.md similarity index 100% rename from docs/web-interface.md rename to docs/user-docs/web-interface.md diff --git a/docs/working-in-teams.md b/docs/user-docs/working-in-teams.md similarity index 100% rename from docs/working-in-teams.md rename to docs/user-docs/working-in-teams.md diff --git a/gitbook/README.md b/gitbook/README.md new file mode 100644 index 000000000..cb84bae87 --- /dev/null +++ b/gitbook/README.md @@ -0,0 +1,65 @@ +# What is GSD? + +GSD is an AI-powered development agent that turns project ideas into working software. Describe what you want to build, and GSD researches, plans, codes, tests, and commits — with clean git history and full cost tracking. + +## How It Works + +GSD breaks your project into manageable pieces and works through them systematically: + +``` +You describe your project + ↓ +GSD creates a milestone with slices (features) + ↓ +Each slice is decomposed into tasks + ↓ +Tasks are executed one at a time in fresh AI sessions + ↓ +Code is committed, verified, and the next task begins +``` + +You can stay hands-on with **step mode** (reviewing each step) or let GSD run autonomously with **auto mode** while you grab coffee. + +## Key Features + +- **Autonomous execution** — `/gsd auto` runs research, planning, coding, testing, and committing without intervention +- **20+ LLM providers** — Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, local models, and more +- **Git isolation** — Each milestone works in its own worktree branch, merged cleanly when done +- **Cost tracking** — Real-time token usage, budget ceilings, and automatic model downgrading +- **Crash recovery** — Sessions resume automatically after interruptions +- **Skills system** — Domain-specific instruction sets for frameworks, languages, and tools +- **Parallel milestones** — Run multiple milestones simultaneously in isolated worktrees +- **Remote questions** — Get Discord, Slack, or Telegram notifications when GSD needs input +- **Web interface** — Browser-based dashboard with real-time progress +- **VS Code extension** — Chat participant, sidebar dashboard, and full command palette +- **Headless mode** — Run in CI pipelines, cron jobs, and scripted automation + +## Quick Start + +```bash +# Install +npm install -g gsd-pi + +# Launch +gsd + +# Start autonomous mode +/gsd auto +``` + +See [Installation](getting-started/installation.md) for detailed setup instructions. + +## Two Ways to Work + +| Mode | Command | Best For | +|------|---------|----------| +| **Step** | `/gsd` | Staying in the loop, reviewing each step | +| **Auto** | `/gsd auto` | Walking away, overnight builds, batch work | + +The recommended workflow: run auto mode in one terminal, steer from another. See [Step Mode](core-concepts/step-mode.md) and [Auto Mode](core-concepts/auto-mode.md). + +## Requirements + +- **Node.js** 22.0.0 or later (24 LTS recommended) +- **Git** installed and configured +- An API key for at least one LLM provider (or use browser sign-in for Anthropic/GitHub Copilot) diff --git a/gitbook/SUMMARY.md b/gitbook/SUMMARY.md new file mode 100644 index 000000000..962364bbe --- /dev/null +++ b/gitbook/SUMMARY.md @@ -0,0 +1,49 @@ +# Table of contents + +* [What is GSD?](README.md) + +## Getting Started + +* [Installation](getting-started/installation.md) +* [Your First Project](getting-started/first-project.md) +* [Choosing a Model](getting-started/choosing-a-model.md) + +## Core Concepts + +* [How GSD Organizes Work](core-concepts/project-structure.md) +* [Step Mode](core-concepts/step-mode.md) +* [Auto Mode](core-concepts/auto-mode.md) + +## Configuration + +* [Preferences](configuration/preferences.md) +* [Provider Setup](configuration/providers.md) +* [Custom Models](configuration/custom-models.md) +* [Git & Worktrees](configuration/git-settings.md) +* [Notifications](configuration/notifications.md) +* [MCP Servers](configuration/mcp-servers.md) + +## Features + +* [Cost Management](features/cost-management.md) +* [Token Optimization](features/token-optimization.md) +* [Dynamic Model Routing](features/dynamic-model-routing.md) +* [Skills](features/skills.md) +* [Captures & Triage](features/captures.md) +* [Workflow Visualizer](features/visualizer.md) +* [Workflow Templates](features/workflow-templates.md) +* [Web Interface](features/web-interface.md) +* [Remote Questions](features/remote-questions.md) +* [Working in Teams](features/teams.md) +* [Parallel Orchestration](features/parallel.md) +* [Headless & CI Mode](features/headless.md) +* [GitHub Sync](features/github-sync.md) + +## Reference + +* [Commands](reference/commands.md) +* [Keyboard Shortcuts](reference/keyboard-shortcuts.md) +* [CLI Flags](reference/cli-flags.md) +* [Environment Variables](reference/environment-variables.md) +* [Troubleshooting](reference/troubleshooting.md) +* [Migration from v1](reference/migration.md) diff --git a/gitbook/configuration/custom-models.md b/gitbook/configuration/custom-models.md new file mode 100644 index 000000000..8f02512ff --- /dev/null +++ b/gitbook/configuration/custom-models.md @@ -0,0 +1,131 @@ +# Custom Models + +Define custom models and providers in `~/.gsd/agent/models.json`. This lets you add models not in the default registry — self-hosted endpoints, fine-tuned models, proxies, or new provider releases. + +## File Location + +GSD looks for models.json at: +1. `~/.gsd/agent/models.json` (primary) +2. `~/.pi/agent/models.json` (fallback) + +The file reloads each time you open `/model` — no restart needed. + +## Basic Structure + +```json +{ + "providers": { + "my-provider": { + "baseUrl": "https://my-endpoint.example.com/v1", + "apiKey": "MY_PROVIDER_API_KEY", + "api": "openai-completions", + "models": [ + { + "id": "model-id-here", + "name": "Friendly Model Name", + "reasoning": false, + "input": ["text"], + "contextWindow": 128000, + "maxTokens": 16384, + "cost": { "input": 0.15, "output": 0.60, "cacheRead": 0.015, "cacheWrite": 0.19 } + } + ] + } + } +} +``` + +## API Key Resolution + +The `apiKey` field can be: + +- **An environment variable name**: `"OPENROUTER_API_KEY"` — GSD resolves it automatically +- **A literal value**: `"sk-abc123..."` — used directly +- **A dummy value**: `"not-needed"` — for local servers that don't require auth + +## Compatibility Flags + +Local and non-standard servers often need compatibility adjustments: + +```json +{ + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false, + "supportsUsageInStreaming": false, + "thinkingFormat": "qwen" + } +} +``` + +| Flag | Default | Purpose | +|------|---------|---------| +| `supportsDeveloperRole` | `true` | Set `false` if the server doesn't support the `developer` message role | +| `supportsReasoningEffort` | `true` | Set `false` if the server doesn't support reasoning effort parameters | +| `supportsUsageInStreaming` | `true` | Set `false` if streaming responses don't include token usage | +| `thinkingFormat` | — | Set `"qwen"` for Qwen thinking mode, `"qwen-chat-template"` for chat template variant | + +## Custom Headers + +For proxies that need extra headers: + +```json +{ + "providers": { + "litellm-proxy": { + "baseUrl": "https://litellm.example.com/v1", + "apiKey": "MY_API_KEY", + "api": "openai-completions", + "headers": { + "x-custom-header": "value" + }, + "models": [...] + } + } +} +``` + +## Model Overrides + +Override specific model settings without redefining the entire model: + +```json +{ + "providers": { + "openrouter": { + "modelOverrides": { + "anthropic/claude-sonnet-4": { + "compat": { + "openRouterRouting": { + "only": ["amazon-bedrock"] + } + } + } + } + } + } +} +``` + +## Cost Tracking + +For accurate cost tracking with custom models, add the `cost` field (per million tokens): + +```json +"cost": { + "input": 0.15, + "output": 0.60, + "cacheRead": 0.015, + "cacheWrite": 0.19 +} +``` + +Without this, cost shows $0.00 — which is the expected default for custom models. + +## Community Extensions + +For providers not built into GSD, community extensions add full provider support: + +| Extension | Provider | Install | +|-----------|----------|---------| +| `pi-dashscope` | Alibaba DashScope (Qwen3, GLM-5, etc.) | `gsd install npm:pi-dashscope` | diff --git a/gitbook/configuration/git-settings.md b/gitbook/configuration/git-settings.md new file mode 100644 index 000000000..cf4c0d524 --- /dev/null +++ b/gitbook/configuration/git-settings.md @@ -0,0 +1,148 @@ +# Git & Worktrees + +GSD uses git for milestone isolation and sequential commits. The strategy is fully automated — you don't need to manage branches manually. + +## Isolation Modes + +GSD supports three isolation modes, configured via `git.isolation` in preferences: + +| Mode | Working Directory | Branch | Best For | +|------|-------------------|--------|----------| +| `worktree` (default) | `.gsd/worktrees//` | `milestone/` | Most projects — full isolation | +| `branch` | Project root | `milestone/` | Submodule-heavy repos | +| `none` | Project root | Current branch | Hot-reload workflows | + +### Worktree Mode (Default) + +Each milestone gets its own git worktree and branch. All execution happens inside the worktree. On completion, everything is squash-merged to main as one clean commit. The worktree and branch are then cleaned up. + +Changes in a milestone can't interfere with your main working copy. + +### Branch Mode + +Work happens in the project root on a `milestone/` branch. No worktree directory is created. Useful when worktrees cause problems with submodules or hardcoded paths. + +### None Mode + +Work happens directly on your current branch. No worktree, no milestone branch. GSD still commits with conventional commit messages. Use this when file isolation breaks dev tooling (file watchers, hot-reload, etc.). + +## Branching Model + +``` +main ──────────────────────────────────────────── + │ ↑ + └── milestone/M001 (worktree) ─────────────┘ + commit: feat: core types + commit: feat: markdown parser + commit: feat: file writer + → squash-merged to main +``` + +## Workflow Modes + +Set `mode` for sensible defaults instead of configuring each setting individually: + +```yaml +mode: solo # personal projects +mode: team # shared repos +``` + +| Setting | `solo` | `team` | +|---------|--------|--------| +| `git.auto_push` | `true` | `false` | +| `git.push_branches` | `false` | `true` | +| `git.pre_merge_check` | `false` | `true` | +| `unique_milestone_ids` | `false` | `true` | + +Mode defaults are the lowest priority — any explicit preference overrides them. + +## Git Preferences + +```yaml +git: + auto_push: false # push after commits + push_branches: false # push milestone branch to remote + remote: origin # git remote name + snapshots: true # WIP snapshot commits during long tasks + pre_merge_check: auto # validation before merge + commit_type: feat # override conventional commit prefix + main_branch: main # primary branch name + merge_strategy: squash # "squash" or "merge" + isolation: worktree # "worktree", "branch", or "none" + commit_docs: true # commit .gsd/ artifacts to git + manage_gitignore: true # let GSD manage .gitignore + auto_pr: false # create PR on milestone completion + pr_target_branch: develop # PR target branch +``` + +## Automatic Pull Requests + +For teams using Gitflow or branch-based workflows: + +```yaml +git: + auto_push: true + auto_pr: true + pr_target_branch: develop +``` + +When a milestone completes, GSD pushes the branch and creates a PR targeting your specified branch. Requires `gh` CLI installed and authenticated. + +## Post-Worktree Hook + +Run a script after worktree creation (copy `.env` files, symlink assets, etc.): + +```yaml +git: + worktree_post_create: .gsd/hooks/post-worktree-create +``` + +Example hook: + +```bash +#!/bin/bash +cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env" +ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets" +``` + +## Keeping `.gsd/` Local + +For teams where only some members use GSD: + +```yaml +git: + commit_docs: false +``` + +This adds `.gsd/` to `.gitignore` entirely. You get structured planning without affecting teammates who don't use GSD. + +## Commit Format + +Commits use conventional commit format with GSD metadata: + +``` +feat: core type definitions + +GSD-Task: M001/S01/T01 +``` + +## Manual Worktree Management + +Use `/worktree` (or `/wt`) for manual worktree operations: + +``` +/worktree create +/worktree switch +/worktree merge +/worktree remove +``` + +## Self-Healing + +GSD automatically recovers from common git issues: + +- **Detached HEAD** — reattaches to the correct branch +- **Stale lock files** — removes `index.lock` from crashed processes +- **Orphaned worktrees** — detects and cleans up abandoned worktrees + +Run `/gsd doctor` to check git health manually. diff --git a/gitbook/configuration/mcp-servers.md b/gitbook/configuration/mcp-servers.md new file mode 100644 index 000000000..6079fa3a7 --- /dev/null +++ b/gitbook/configuration/mcp-servers.md @@ -0,0 +1,65 @@ +# MCP Servers + +GSD can connect to external MCP (Model Context Protocol) servers for local tools, internal APIs, self-hosted services, or integrations not built in as native extensions. + +## Configuration Files + +GSD reads MCP config from these project-local paths: + +- `.mcp.json` — repo-shared config (safe to commit) +- `.gsd/mcp.json` — local-only config (not shared) + +If both exist, server names are merged and the first definition found wins. + +## Supported Transports + +| Transport | Config Shape | Use When | +|-----------|-------------|----------| +| `stdio` | `command` + optional `args`, `env`, `cwd` | Launching a local MCP server | +| `http` | `url` | Connecting to an already-running server | + +## Examples + +### stdio Server + +```json +{ + "mcpServers": { + "my-server": { + "type": "stdio", + "command": "/absolute/path/to/python3", + "args": ["/absolute/path/to/server.py"], + "env": { + "API_URL": "http://localhost:8000" + } + } + } +} +``` + +### HTTP Server + +```json +{ + "mcpServers": { + "my-http-server": { + "url": "http://localhost:8080/mcp" + } + } +} +``` + +## Verifying a Server + +After adding config, verify from a GSD session: + +1. `mcp_servers` — confirms GSD sees the config +2. `mcp_discover(server="my-server")` — confirms the server starts and responds +3. `mcp_call(server="my-server", tool="", args={...})` — confirms a real tool call works + +## Tips + +- Use **absolute paths** for executables and scripts +- Set required **environment variables** directly in the MCP config's `env` block +- Use `.mcp.json` for team-shared servers; `.gsd/mcp.json` for machine-local ones +- If a server depends on local paths or personal secrets, keep it in `.gsd/mcp.json` diff --git a/gitbook/configuration/notifications.md b/gitbook/configuration/notifications.md new file mode 100644 index 000000000..54acd0d67 --- /dev/null +++ b/gitbook/configuration/notifications.md @@ -0,0 +1,38 @@ +# Notifications + +GSD sends desktop notifications during auto mode to keep you informed without watching the terminal. + +## Configuration + +```yaml +notifications: + enabled: true + on_complete: true # notify on unit completion + on_error: true # notify on errors + on_budget: true # notify on budget thresholds + on_milestone: true # notify when milestone finishes + on_attention: true # notify when manual attention needed +``` + +## macOS Setup + +GSD uses `terminal-notifier` when available, falling back to `osascript`. + +**Recommended:** Install `terminal-notifier` for reliable delivery: + +```bash +brew install terminal-notifier +``` + +**Why?** The `osascript` fallback attributes notifications to your terminal app (Ghostty, iTerm2, etc.), which may not have notification permissions. `terminal-notifier` registers as its own app and prompts for permission on first use. + +### Notifications Not Appearing? + +1. Check **System Settings → Notifications** for your terminal app +2. Install `terminal-notifier` (recommended) +3. Test with: + ```bash + terminal-notifier -title "GSD" -message "working!" -sound Glass + ``` + +If your terminal app doesn't appear in Notification settings, it may need to send at least one notification first to register. See [Troubleshooting](../reference/troubleshooting.md) for more details. diff --git a/gitbook/configuration/preferences.md b/gitbook/configuration/preferences.md new file mode 100644 index 000000000..3a997150a --- /dev/null +++ b/gitbook/configuration/preferences.md @@ -0,0 +1,238 @@ +# Preferences + +GSD preferences live in YAML frontmatter markdown files. You can configure them globally or per-project. + +## Managing Preferences + +``` +/gsd prefs # open the global preferences wizard +/gsd prefs project # open the project preferences wizard +/gsd prefs status # show current values and where they come from +``` + +## Preference Files + +| Scope | Path | Applies To | +|-------|------|-----------| +| Global | `~/.gsd/PREFERENCES.md` | All projects | +| Project | `.gsd/PREFERENCES.md` | Current project only | + +**How they merge:** +- **Scalar fields** (`budget_ceiling`, `token_profile`): project wins if defined +- **Array fields** (`always_use_skills`, etc.): concatenated (global first, then project) +- **Object fields** (`models`, `git`, `auto_supervisor`): shallow-merged, project overrides per-key + +## Quick Example + +```yaml +--- +version: 1 + +# Model selection +models: + research: claude-sonnet-4-6 + planning: claude-opus-4-6 + execution: claude-sonnet-4-6 + completion: claude-sonnet-4-6 + +# Token optimization +token_profile: balanced + +# Budget +budget_ceiling: 25.00 +budget_enforcement: pause + +# Supervision +auto_supervisor: + soft_timeout_minutes: 15 + hard_timeout_minutes: 25 + +# Git +git: + auto_push: true + merge_strategy: squash + isolation: worktree + +# Verification +verification_commands: + - npm run lint + - npm run test + +# Notifications +notifications: + on_milestone: true + on_attention: true +--- +``` + +## All Settings + +### `models` + +Per-phase model selection. See [Choosing a Model](../getting-started/choosing-a-model.md). + +```yaml +models: + research: claude-sonnet-4-6 + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + execution: claude-sonnet-4-6 + execution_simple: claude-haiku-4-5 + completion: claude-sonnet-4-6 + subagent: claude-sonnet-4-6 +``` + +### `token_profile` + +Coordinates model selection, phase skipping, and context compression. Values: `budget`, `balanced` (default), `quality`. See [Token Optimization](../features/token-optimization.md). + +### `budget_ceiling` + +Maximum USD to spend during auto mode: + +```yaml +budget_ceiling: 50.00 +``` + +### `budget_enforcement` + +What happens when the ceiling is reached: + +| Value | Behavior | +|-------|----------| +| `warn` | Log a warning, continue | +| `pause` | Pause auto mode (default) | +| `halt` | Stop auto mode entirely | + +### `auto_supervisor` + +Timeout thresholds for auto mode: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 # warn AI to wrap up + idle_timeout_minutes: 10 # detect stalls + hard_timeout_minutes: 30 # pause auto mode +``` + +### `verification_commands` + +Shell commands that run after every task execution: + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true # auto-retry on failure (default) +verification_max_retries: 2 # max attempts (default: 2) +``` + +### `phases` + +Fine-grained control over which phases run: + +```yaml +phases: + skip_research: false + skip_reassess: false + skip_slice_research: true + reassess_after_slice: true + require_slice_discussion: false +``` + +### `skill_discovery` + +| Value | Behavior | +|-------|----------| +| `auto` | Skills found and applied automatically | +| `suggest` | Skills identified but not auto-applied (default) | +| `off` | Skill discovery disabled | + +### `dynamic_routing` + +Automatic model selection by task complexity. See [Dynamic Model Routing](../features/dynamic-model-routing.md). + +```yaml +dynamic_routing: + enabled: true + escalate_on_failure: true + budget_pressure: true +``` + +### `git` + +Git behavior. See [Git & Worktrees](git-settings.md). + +```yaml +git: + auto_push: false + merge_strategy: squash + isolation: worktree + commit_docs: true + auto_pr: false +``` + +### `notifications` + +See [Notifications](notifications.md). + +```yaml +notifications: + enabled: true + on_complete: true + on_error: true + on_milestone: true + on_attention: true +``` + +### `remote_questions` + +Route questions to Slack, Discord, or Telegram. See [Remote Questions](../features/remote-questions.md). + +```yaml +remote_questions: + channel: discord + channel_id: "1234567890123456789" + timeout_minutes: 5 +``` + +### `parallel` + +Run multiple milestones simultaneously. See [Parallel Orchestration](../features/parallel.md). + +```yaml +parallel: + enabled: false + max_workers: 2 + budget_ceiling: 50.00 +``` + +### `custom_instructions` + +Durable instructions appended to every session: + +```yaml +custom_instructions: + - "Always use TypeScript strict mode" + - "Prefer functional patterns over classes" +``` + +For project-specific patterns, use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically. + +### `context_pause_threshold` + +Context window usage percentage at which auto mode pauses: + +```yaml +context_pause_threshold: 80 # pause at 80% +``` + +### `show_token_cost` + +Show per-prompt and cumulative session token cost in the footer: + +```yaml +show_token_cost: true +``` diff --git a/gitbook/configuration/providers.md b/gitbook/configuration/providers.md new file mode 100644 index 000000000..4cb709142 --- /dev/null +++ b/gitbook/configuration/providers.md @@ -0,0 +1,277 @@ +# Provider Setup + +Step-by-step setup instructions for every LLM provider GSD supports. If you ran the onboarding wizard (`gsd config`) and picked a provider, you may already be configured — check with `/model` inside a session. + +## Quick Reference + +| Provider | Auth Method | Environment Variable | +|----------|-------------|---------------------| +| Anthropic | OAuth or API key | `ANTHROPIC_API_KEY` | +| OpenAI | API key | `OPENAI_API_KEY` | +| Google Gemini | API key | `GEMINI_API_KEY` | +| OpenRouter | API key | `OPENROUTER_API_KEY` | +| Groq | API key | `GROQ_API_KEY` | +| xAI (Grok) | API key | `XAI_API_KEY` | +| Mistral | API key | `MISTRAL_API_KEY` | +| GitHub Copilot | OAuth | `GH_TOKEN` | +| Amazon Bedrock | IAM credentials | `AWS_PROFILE` or `AWS_ACCESS_KEY_ID` | +| Vertex AI | ADC | `GOOGLE_APPLICATION_CREDENTIALS` | +| Azure OpenAI | API key | `AZURE_OPENAI_API_KEY` | +| Ollama | None (local) | — | +| LM Studio | None (local) | — | +| vLLM / SGLang | None (local) | — | + +## Built-in Providers + +### Anthropic (Claude) + +**Recommended.** Anthropic models have the deepest integration: built-in web search, extended thinking, and prompt caching. + +**Option A — Browser sign-in (recommended):** + +```bash +gsd config +# Choose "Sign in with your browser" → "Anthropic (Claude)" +``` + +Or inside a session: `/login` + +**Option B — API key:** + +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +### OpenAI + +```bash +export OPENAI_API_KEY="sk-..." +``` + +Or run `gsd config` and choose "Paste an API key" then "OpenAI". + +### Google Gemini + +```bash +export GEMINI_API_KEY="..." +``` + +### OpenRouter + +OpenRouter aggregates 200+ models from multiple providers behind a single API key. + +1. Get a key at [openrouter.ai/keys](https://openrouter.ai/keys) +2. Set it: + ```bash + export OPENROUTER_API_KEY="sk-or-..." + ``` +3. In GSD, type `/model` to select an OpenRouter model (prefixed with `openrouter/`) + +To add models not in the built-in list, add them to `~/.gsd/agent/models.json`. See [Custom Models](custom-models.md). + +### Groq + +```bash +export GROQ_API_KEY="gsk_..." +``` + +### xAI (Grok) + +```bash +export XAI_API_KEY="xai-..." +``` + +### Mistral + +```bash +export MISTRAL_API_KEY="..." +``` + +### GitHub Copilot + +Uses OAuth — sign in through the browser: + +```bash +gsd config +# Choose "Sign in with your browser" → "GitHub Copilot" +``` + +Requires an active GitHub Copilot subscription. + +### Amazon Bedrock + +Bedrock uses AWS IAM credentials: + +```bash +# Named profile +export AWS_PROFILE="my-profile" + +# Or IAM keys +export AWS_ACCESS_KEY_ID="AKIA..." +export AWS_SECRET_ACCESS_KEY="..." +export AWS_REGION="us-east-1" + +# Or bearer token +export AWS_BEARER_TOKEN_BEDROCK="..." +``` + +ECS task roles and IRSA (Kubernetes) are also detected automatically. + +### Anthropic on Vertex AI + +```bash +gcloud auth application-default login +export ANTHROPIC_VERTEX_PROJECT_ID="my-project-id" +``` + +### Azure OpenAI + +```bash +export AZURE_OPENAI_API_KEY="..." +``` + +## Local Providers + +Local providers run on your machine. They require a `models.json` configuration file at `~/.gsd/agent/models.json` because GSD needs to know the endpoint URL and available models. + +The file reloads each time you open `/model` — no restart needed. + +### Ollama + +1. Install and start Ollama: + ```bash + brew install ollama + ollama serve + ``` + +2. Pull a model: + ```bash + ollama pull llama3.1:8b + ``` + +3. Create `~/.gsd/agent/models.json`: + ```json + { + "providers": { + "ollama": { + "baseUrl": "http://localhost:11434/v1", + "api": "openai-completions", + "apiKey": "ollama", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { "id": "llama3.1:8b" } + ] + } + } + } + ``` + +4. In GSD, type `/model` and select your Ollama model. + +### LM Studio + +1. Install [LM Studio](https://lmstudio.ai) +2. Go to "Local Server" tab, load a model, click "Start Server" (default port 1234) +3. Create `~/.gsd/agent/models.json`: + ```json + { + "providers": { + "lm-studio": { + "baseUrl": "http://localhost:1234/v1", + "api": "openai-completions", + "apiKey": "lm-studio", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { "id": "your-model-name" } + ] + } + } + } + ``` + +### vLLM + +```json +{ + "providers": { + "vllm": { + "baseUrl": "http://localhost:8000/v1", + "api": "openai-completions", + "apiKey": "vllm", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false, + "supportsUsageInStreaming": false + }, + "models": [ + { "id": "meta-llama/Llama-3.1-8B-Instruct" } + ] + } + } +} +``` + +### SGLang + +```json +{ + "providers": { + "sglang": { + "baseUrl": "http://localhost:30000/v1", + "api": "openai-completions", + "apiKey": "sglang", + "compat": { + "supportsDeveloperRole": false, + "supportsReasoningEffort": false + }, + "models": [ + { "id": "meta-llama/Llama-3.1-8B-Instruct" } + ] + } + } +} +``` + +## Custom OpenAI-Compatible Endpoints + +Any server that implements the OpenAI Chat Completions API can work with GSD — proxies (LiteLLM, Portkey, Helicone), self-hosted inference, new providers. + +**Quickest path:** + +```bash +gsd config +# Choose "Paste an API key" → "Custom (OpenAI-compatible)" +# Enter: base URL, API key, model ID +``` + +This writes `~/.gsd/agent/models.json` for you. See [Custom Models](custom-models.md) for manual setup. + +## Verifying Your Setup + +1. Launch GSD: `gsd` +2. Check available models: `/model` +3. Select your model from the picker +4. Send a test message to confirm it responds + +If the model doesn't appear, check: +- The environment variable is set in the current shell +- `models.json` is valid JSON +- The server is running (for local providers) + +## Common Issues + +| Problem | Cause | Fix | +|---------|-------|-----| +| "Authentication failed" with valid key | Key not visible to GSD | Export in the same terminal, or save via `gsd config` | +| OpenRouter models not in `/model` | No API key set | Set `OPENROUTER_API_KEY` and restart | +| Ollama returns empty responses | Server not running or model not pulled | Run `ollama serve` and `ollama pull ` | +| LM Studio model ID mismatch | ID doesn't match server | Check LM Studio's server tab for the exact identifier | +| `developer` role error | Local server doesn't support it | Set `compat.supportsDeveloperRole: false` | +| `stream_options` error | Server doesn't support streaming usage | Set `compat.supportsUsageInStreaming: false` | +| Cost shows $0.00 | Default for custom models | Add `cost` field to model definition | diff --git a/gitbook/core-concepts/auto-mode.md b/gitbook/core-concepts/auto-mode.md new file mode 100644 index 000000000..b611f85ff --- /dev/null +++ b/gitbook/core-concepts/auto-mode.md @@ -0,0 +1,183 @@ +# Auto Mode + +Auto mode is GSD's autonomous execution engine. Run `/gsd auto`, walk away, come back to built software with clean git history. + +## Starting Auto Mode + +``` +/gsd auto +``` + +GSD reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh AI session with all relevant context, and lets the AI execute. When it finishes, GSD reads disk state again and dispatches the next unit. This continues until the milestone is complete. + +## The Execution Loop + +Each slice flows through phases automatically: + +``` +Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice + ↓ (all done) + Validate Milestone +``` + +- **Plan** — scouts the codebase, researches docs, decomposes the slice into tasks +- **Execute** — runs each task in a fresh context window +- **Complete** — writes summary, UAT script, marks roadmap, commits +- **Reassess** — checks if the roadmap still makes sense after what was learned +- **Validate** — after all slices, verifies success criteria were actually met + +## Controlling Auto Mode + +### Pause + +Press **Escape**. The conversation is preserved. You can interact with the agent, inspect state, or resume. + +### Resume + +``` +/gsd auto +``` + +Auto mode reads disk state and picks up where it left off. + +### Stop + +``` +/gsd stop +``` + +Stops auto mode gracefully. Can be run from a different terminal. + +### Steer + +``` +/gsd steer +``` + +Modify plan documents during execution without stopping. Changes are picked up at the next phase boundary. + +### Capture Thoughts + +``` +/gsd capture "add rate limiting to API endpoints" +``` + +Fire-and-forget thought capture. Captures are triaged automatically between tasks without pausing execution. See [Captures & Triage](../features/captures.md). + +## Fresh Session Per Unit + +Every task gets a clean AI context window. No accumulated garbage, no quality degradation from context bloat. The dispatch prompt includes everything needed — task plans, prior summaries, decisions, dependency context — so the AI starts oriented. + +## Git Isolation + +GSD isolates milestone work using one of three modes: + +| Mode | How It Works | Best For | +|------|-------------|----------| +| `worktree` (default) | Each milestone gets its own directory and branch | Most projects | +| `branch` | Work happens in the project root on a milestone branch | Submodule-heavy repos | +| `none` | Work happens directly on your current branch | Hot-reload workflows | + +In worktree mode, all commits are squash-merged to main as one clean commit when the milestone completes. See [Git & Worktrees](../configuration/git-settings.md). + +## Crash Recovery + +If a session dies, the next `/gsd auto` reads the surviving session file, synthesizes a recovery briefing from every tool call that made it to disk, and resumes with full context. + +In headless mode (`gsd headless auto`), crashes trigger automatic restart with exponential backoff (5s → 10s → 30s, up to 3 attempts). Combined with crash recovery, this enables true overnight "fire and forget" execution. + +## Provider Error Recovery + +GSD handles provider errors automatically: + +| Error Type | Examples | What Happens | +|-----------|----------|-------------| +| Rate limit | 429, "too many requests" | Auto-resumes after cooldown (60s or retry-after header) | +| Server error | 500, 502, 503, "overloaded" | Auto-resumes after 30s | +| Permanent | "unauthorized", "invalid key" | Pauses — requires manual resume | + +No manual intervention needed for transient errors. + +## Timeout Supervision + +Three timeout tiers prevent runaway sessions: + +| Timeout | Default | What Happens | +|---------|---------|-------------| +| Soft | 20 min | Warns the AI to wrap up | +| Idle | 10 min | Detects stalls, intervenes | +| Hard | 30 min | Pauses auto mode | + +Configure in preferences: + +```yaml +auto_supervisor: + soft_timeout_minutes: 20 + idle_timeout_minutes: 10 + hard_timeout_minutes: 30 +``` + +## Verification Gates + +Configure shell commands that run automatically after every task: + +```yaml +verification_commands: + - npm run lint + - npm run test +verification_auto_fix: true # auto-retry on failure +verification_max_retries: 2 # max retry attempts +``` + +If verification fails, the AI sees the output and attempts to fix the issues before advancing. This ensures quality gates are enforced mechanically. + +## Slice Discussion Gate + +For projects requiring human review before each slice: + +```yaml +require_slice_discussion: true +``` + +Auto mode pauses before each slice, showing the plan for your approval before building. + +## Stuck Detection + +GSD uses sliding-window analysis to detect stuck loops — not just "same unit dispatched twice" but also cycles like A→B→A→B. On detection, GSD retries once with a diagnostic prompt. If it fails again, auto mode stops with details so you can intervene. + +## Cost Tracking + +Every unit's token usage and cost is captured, broken down by phase, slice, and model. The dashboard shows running totals and projections. Budget ceilings can pause auto mode before overspending. See [Cost Management](../features/cost-management.md). + +## Dashboard + +`Ctrl+Alt+G` or `/gsd status` shows real-time progress: + +- Current milestone, slice, and task +- Auto mode elapsed time and phase +- Per-unit cost and token breakdown +- Cost projections +- Completed and in-progress units +- Pending capture count +- Parallel worker status (when running parallel milestones) + +## HTML Reports + +After a milestone completes, GSD generates a self-contained HTML report in `.gsd/reports/` with project summary, progress tree, dependency graph, cost metrics, timeline, and changelog. Generate manually with: + +``` +/gsd export --html +/gsd export --html --all # all milestones +``` + +## Diagnostic Tools + +If auto mode has issues, GSD provides two diagnostic tools: + +- **`/gsd doctor`** — validates `.gsd/` integrity, checks referential consistency, fixes structural issues +- **`/gsd forensics`** — full post-mortem debugger with anomaly detection, unit traces, metrics analysis, and AI-guided investigation + +``` +/gsd doctor +/gsd forensics [optional problem description] +``` diff --git a/gitbook/core-concepts/project-structure.md b/gitbook/core-concepts/project-structure.md new file mode 100644 index 000000000..6aa6e9078 --- /dev/null +++ b/gitbook/core-concepts/project-structure.md @@ -0,0 +1,104 @@ +# How GSD Organizes Work + +GSD uses a three-level hierarchy to break projects into manageable pieces that an AI can execute reliably. + +## The Hierarchy + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable vertical feature (1-7 tasks) + Task → one context-window-sized unit of work +``` + +### Milestones + +A milestone is a shippable version of your project — an MVP, a major release, or a feature set that delivers standalone value. Milestones typically contain 4-10 slices. + +Examples: +- "MVP with user auth, dashboard, and settings" +- "v2.0 with real-time collaboration and API v2" +- "Security hardening milestone" + +### Slices + +A slice is one demoable, vertical capability within a milestone. It cuts across layers (database, backend, frontend) to deliver something you could show to a user. Slices contain 1-7 tasks. + +Examples: +- "User authentication with JWT" +- "Dashboard layout with charts" +- "API rate limiting" + +### Tasks + +A task is the smallest unit of work — something that fits in one AI context window. If a task can't be completed in a single AI session, it's broken into smaller tasks. + +Examples: +- "Create the User model and migration" +- "Implement JWT middleware" +- "Build the login form component" + +## The `.gsd/` Directory + +All project state lives on disk in a `.gsd/` directory at your project root: + +``` +.gsd/ + PROJECT.md — living description of what the project is + REQUIREMENTS.md — requirement contract (active/validated/deferred) + DECISIONS.md — append-only architectural decisions log + KNOWLEDGE.md — cross-session rules, patterns, and lessons + RUNTIME.md — runtime context: API endpoints, env vars, services + STATE.md — quick-glance status of current work + PREFERENCES.md — project-level preferences (optional) + milestones/ + M001/ + M001-ROADMAP.md — slice plan with risk levels and dependencies + M001-CONTEXT.md — scope and goals from discussion phase + slices/ + S01/ + S01-PLAN.md — task decomposition for this slice + S01-SUMMARY.md — what was built and what changed + S01-UAT.md — human test script + tasks/ + T01-PLAN.md — detailed plan for this task + T01-SUMMARY.md — what the task accomplished +``` + +### Key Files + +| File | Purpose | +|------|---------| +| `PROJECT.md` | High-level project description, updated as the project evolves | +| `REQUIREMENTS.md` | Formal requirement contract — tracks what's active, validated, and deferred | +| `DECISIONS.md` | Append-only log of architectural decisions with rationale | +| `KNOWLEDGE.md` | Rules, patterns, and lessons learned across sessions — GSD reads this at the start of every task | +| `RUNTIME.md` | Runtime context like API URLs, ports, and environment variables | +| `STATE.md` | Current status at a glance — auto-generated, don't edit manually | + +## How Work Flows + +Each slice flows through phases: + +``` +Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice +``` + +1. **Plan** — GSD scouts the codebase, researches relevant docs, and decomposes the slice into tasks with clear requirements +2. **Execute** — Each task runs in a fresh AI session with focused context +3. **Complete** — GSD writes summaries, generates a UAT script, and commits +4. **Reassess** — The roadmap is checked against reality — slices may be reordered, added, or removed +5. **Next Slice** — The loop continues until all slices are done + +After all slices complete, a **milestone validation** gate checks that success criteria were actually met before sealing the milestone. + +## Adding Knowledge + +GSD maintains a knowledge base that persists across sessions. Add rules, patterns, or lessons: + +``` +/gsd knowledge rule "Always use parameterized queries for database access" +/gsd knowledge pattern "Service classes go in src/services/" +/gsd knowledge lesson "The OAuth flow requires the redirect URL to match exactly" +``` + +This knowledge is injected into every task prompt automatically. diff --git a/gitbook/core-concepts/step-mode.md b/gitbook/core-concepts/step-mode.md new file mode 100644 index 000000000..750c56728 --- /dev/null +++ b/gitbook/core-concepts/step-mode.md @@ -0,0 +1,54 @@ +# Step Mode + +Step mode is GSD's interactive, one-step-at-a-time workflow. You stay in the loop, reviewing output between each step. + +## Starting Step Mode + +``` +/gsd +``` + +GSD reads the state of your `.gsd/` directory and presents a wizard showing what's completed and what's next. It then executes one unit of work and pauses. + +## How It Works + +Step mode adapts to your project's current state: + +| State | What Happens | +|-------|-------------| +| No `.gsd/` directory | Starts a discussion flow to capture your project vision | +| Milestone exists, no roadmap | Opens a discussion or research phase for the milestone | +| Roadmap exists, slices pending | Plans the next slice or executes the next task | +| Mid-task | Resumes where you left off | + +After each unit completes, you see results and decide what to do next. This is ideal for: + +- New projects where you want to shape the architecture +- Critical work where you want to review each step +- Learning how GSD works before trusting auto mode + +## Steering During Step Mode + +Between steps, you can: + +- **Discuss** — `/gsd discuss` to talk through architecture decisions +- **Skip** — `/gsd skip` to prevent a unit from being dispatched +- **Undo** — `/gsd undo` to revert the last completed unit +- **Switch to auto** — `/gsd auto` to let GSD continue autonomously + +## When to Use Step Mode + +- **First milestone** — Review GSD's work before trusting it to run solo +- **Architectural decisions** — When you want to guide the approach +- **Unfamiliar codebases** — When you want to ensure GSD understands the project +- **High-stakes changes** — When mistakes would be costly + +## Transitioning to Auto Mode + +Once you're comfortable with GSD's approach, switch to auto mode: + +``` +/gsd auto +``` + +You can always press **Escape** to pause auto mode and return to step-by-step control. diff --git a/gitbook/features/captures.md b/gitbook/features/captures.md new file mode 100644 index 000000000..54a2a27e1 --- /dev/null +++ b/gitbook/features/captures.md @@ -0,0 +1,54 @@ +# Captures & Triage + +Captures let you fire-and-forget thoughts during auto-mode execution. Instead of pausing auto mode to steer, capture ideas, bugs, or scope changes and let GSD triage them at natural seams between tasks. + +## Quick Start + +While auto mode is running (or any time): + +``` +/gsd capture "add rate limiting to the API endpoints" +/gsd capture "the auth flow should support OAuth, not just JWT" +``` + +Captures are appended to `.gsd/CAPTURES.md` and triaged automatically between tasks. + +## How It Works + +``` +Capture → Triage → Confirm → Resolve → Resume +``` + +1. **Capture** — your thought is saved with a timestamp +2. **Triage** — between tasks, GSD classifies each capture +3. **Confirm** — you see the proposed resolution and approve or adjust +4. **Resolve** — the resolution is applied +5. **Resume** — auto mode continues + +## Classification Types + +Each capture is classified into one of five types: + +| Type | Meaning | What Happens | +|------|---------|-------------| +| `quick-task` | Small, self-contained fix | Executed immediately | +| `inject` | New task needed in current slice | Task added to active slice | +| `defer` | Important but not urgent | Deferred to roadmap reassessment | +| `replan` | Changes the current approach | Triggers slice replan | +| `note` | Informational, no action needed | Acknowledged, no changes | + +Plan-modifying resolutions (inject, replan) require your confirmation. + +## Manual Triage + +Trigger triage manually at any time: + +``` +/gsd triage +``` + +Useful when you've accumulated several captures and want to process them before the next natural seam. + +## Dashboard Integration + +The progress widget shows a pending capture count badge when captures are waiting for triage. diff --git a/gitbook/features/cost-management.md b/gitbook/features/cost-management.md new file mode 100644 index 000000000..62204c586 --- /dev/null +++ b/gitbook/features/cost-management.md @@ -0,0 +1,74 @@ +# Cost Management + +GSD tracks token usage and cost for every unit of work during auto mode. This data powers the dashboard, budget enforcement, and cost projections. + +## Viewing Costs + +**Dashboard:** Press `Ctrl+Alt+G` or type `/gsd status` for real-time cost breakdown. + +**Visualizer:** `/gsd visualize` → Metrics tab for detailed charts. + +**Aggregations:** +- By phase (research, planning, execution, completion, reassessment) +- By slice +- By model +- Project totals + +## Budget Ceiling + +Set a maximum spend: + +```yaml +budget_ceiling: 50.00 +``` + +### Enforcement Modes + +```yaml +budget_enforcement: pause # default when ceiling is set +``` + +| Mode | What Happens | +|------|-------------| +| `warn` | Log a warning, keep going | +| `pause` | Pause auto mode, wait for you | +| `halt` | Stop auto mode entirely | + +## Cost Projections + +Once at least two slices have completed, GSD projects the remaining cost: + +``` +Projected remaining: $12.40 ($6.20/slice avg × 2 remaining) +``` + +## Budget Pressure + +When approaching the budget ceiling, GSD automatically uses cheaper models: + +| Budget Used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard tasks downgrade to lighter models | +| 75-90% | More aggressive downgrading | +| > 90% | Nearly everything downgrades; only complex tasks stay at standard | + +This spreads your budget across remaining work instead of exhausting it early. + +## Token Profiles & Cost + +| Profile | Typical Savings | How | +|---------|----------------|-----| +| `budget` | 40-60% | Cheaper models, phase skipping, minimal context | +| `balanced` | 10-20% | Default models, standard context | +| `quality` | 0% (baseline) | All phases, full context | + +## Tips + +- Start with `balanced` profile and a generous `budget_ceiling` to establish baseline costs +- Check `/gsd status` after a few slices to see per-slice cost averages +- Switch to `budget` for well-understood, repetitive work +- Use `quality` only when architectural decisions are being made +- Use per-phase model selection to save: Opus for planning, Sonnet for execution +- Enable `dynamic_routing` for automatic model downgrading on simple tasks +- Use `/gsd visualize` → Metrics tab to see where your budget is going diff --git a/gitbook/features/dynamic-model-routing.md b/gitbook/features/dynamic-model-routing.md new file mode 100644 index 000000000..a9903f715 --- /dev/null +++ b/gitbook/features/dynamic-model-routing.md @@ -0,0 +1,88 @@ +# Dynamic Model Routing + +Dynamic model routing automatically selects cheaper models for simple work and reserves expensive models for complex tasks. This reduces cost by 20-50% without sacrificing quality where it matters. + +## Enabling + +```yaml +dynamic_routing: + enabled: true +``` + +## How It Works + +Each unit passes through two stages: + +1. **Complexity classification** — classifies work as light, standard, or heavy +2. **Capability scoring** — within the tier, ranks models by how well they match the task + +**Key rule:** Your configured model is always the ceiling — routing never upgrades beyond what you've set. + +| Tier | Typical Work | Model Level | +|------|-------------|-------------| +| Light | Slice completion, UAT, hooks | Haiku-class | +| Standard | Research, planning, execution | Sonnet-class | +| Heavy | Replanning, roadmap reassessment | Opus-class | + +## Configuration + +```yaml +dynamic_routing: + enabled: true + tier_models: # optional: explicit model per tier + light: claude-haiku-4-5 + standard: claude-sonnet-4-6 + heavy: claude-opus-4-6 + escalate_on_failure: true # bump tier on failure (default) + budget_pressure: true # auto-downgrade near budget ceiling (default) + cross_provider: true # consider models from other providers (default) + capability_routing: true # score models by task fit (default) +``` + +### Escalate on Failure + +When a task fails at a given tier, the router escalates to the next tier on retry: Light → Standard → Heavy. This prevents cheap models from burning retries on work that needs more reasoning. + +### Budget Pressure + +When approaching the budget ceiling, the router progressively downgrades: + +| Budget Used | Effect | +|------------|--------| +| < 50% | No adjustment | +| 50-75% | Standard → Light | +| 75-90% | More aggressive | +| > 90% | Nearly everything → Light | + +### Cross-Provider + +When enabled, the router may select models from providers other than your primary, using the built-in cost table to find the cheapest model at each tier. + +### Capability Routing + +Models are scored across 7 dimensions: coding, debugging, research, reasoning, speed, long context handling, and instruction following. Different task types weight these dimensions differently — a research task prioritizes research and reasoning, while an execution task prioritizes coding and instruction following. + +Set `capability_routing: false` to revert to simple cheapest-in-tier selection. + +## Interaction with Token Profiles + +Dynamic routing and token profiles work together: + +- **Token profiles** control phase skipping and context compression +- **Dynamic routing** controls per-unit model selection + +The `budget` profile + dynamic routing provides maximum cost savings. + +## Adaptive Learning + +GSD tracks routing outcomes in `.gsd/routing-history.json`. If a tier's failure rate exceeds 20% for a given task type, future classifications are bumped up. + +Use `/gsd rate` to submit feedback: + +``` +/gsd rate over # too powerful — use cheaper next time +/gsd rate ok # just right +/gsd rate under # too weak — use stronger next time +``` + +Feedback is weighted 2x compared to automatic outcomes. diff --git a/gitbook/features/github-sync.md b/gitbook/features/github-sync.md new file mode 100644 index 000000000..aa89c8602 --- /dev/null +++ b/gitbook/features/github-sync.md @@ -0,0 +1,44 @@ +# GitHub Sync + +GSD can auto-sync milestones, slices, and tasks to GitHub Issues, PRs, and Milestones. + +## Setup + +1. Install and authenticate the `gh` CLI: + ```bash + gh auth login + ``` + +2. Enable in preferences: + ```yaml + github: + enabled: true + repo: "owner/repo" # auto-detected from git remote if omitted + labels: [gsd, auto-generated] # labels for created items + ``` + +## Commands + +| Command | Description | +|---------|-------------| +| `/github-sync bootstrap` | Initial setup — creates GitHub Milestones, Issues, and draft PRs from current `.gsd/` state | +| `/github-sync status` | Show sync mapping counts (milestones, slices, tasks) | + +## How It Works + +- Milestones → GitHub Milestones +- Slices → GitHub Issues (linked to milestone) +- Tasks → GitHub Issue checklists +- Completed slices → Draft PRs + +Sync mapping is persisted in `.gsd/.github-sync.json`. The sync is rate-limit aware — it skips when the GitHub API rate limit is low. + +## Configuration + +```yaml +github: + enabled: true + repo: "owner/repo" + labels: [gsd, auto-generated] + project: "Project ID" # optional: GitHub Project board +``` diff --git a/gitbook/features/headless.md b/gitbook/features/headless.md new file mode 100644 index 000000000..5cc1e9351 --- /dev/null +++ b/gitbook/features/headless.md @@ -0,0 +1,86 @@ +# Headless & CI Mode + +`gsd headless` runs GSD commands without a terminal UI — designed for CI pipelines, cron jobs, and scripted automation. + +## Basic Usage + +```bash +# Run auto mode +gsd headless + +# Run a single unit +gsd headless next + +# With timeout for CI +gsd headless --timeout 600000 auto + +# Force a specific phase +gsd headless dispatch plan + +# Stream all events as JSONL +gsd headless --json auto +``` + +## Creating Milestones Headlessly + +```bash +# From a context file +gsd headless new-milestone --context brief.md --auto + +# From inline text +gsd headless new-milestone --context-text "Build a REST API with auth" + +# Pipe from stdin +echo "Build a CLI tool" | gsd headless new-milestone --context - +``` + +## CLI Flags + +| Flag | Default | Description | +|------|---------|-------------| +| `--timeout N` | 300000 (5 min) | Overall timeout in milliseconds | +| `--max-restarts N` | 3 | Auto-restart on crash (0 to disable) | +| `--json` | — | Stream events as JSONL to stdout | +| `--model ID` | — | Override model for this session | +| `--context ` | — | Context file for `new-milestone` (use `-` for stdin) | +| `--context-text ` | — | Inline context for `new-milestone` | +| `--auto` | — | Chain into auto mode after milestone creation | + +## Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Complete | +| `1` | Error or timeout | +| `2` | Blocked | + +## Instant State Query + +`gsd headless query` returns a JSON snapshot of project state — no AI session, instant response (~50ms): + +```bash +gsd headless query | jq '.state.phase' +# "executing" + +gsd headless query | jq '.next' +# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"} + +gsd headless query | jq '.cost.total' +# 4.25 +``` + +Any `/gsd` subcommand works as a positional argument: `gsd headless status`, `gsd headless doctor`, etc. + +## MCP Server Mode + +`gsd --mode mcp` runs GSD as a Model Context Protocol server over stdin/stdout, exposing all GSD tools to external AI clients: + +```bash +gsd --mode mcp +``` + +Compatible with Claude Desktop, VS Code Copilot, and any MCP host. + +## Auto-Restart + +In headless mode, crashes trigger automatic restart with exponential backoff (5s → 10s → 30s cap, default 3 attempts). SIGINT/SIGTERM bypasses restart. Combined with crash recovery, this enables true overnight unattended execution. diff --git a/gitbook/features/parallel.md b/gitbook/features/parallel.md new file mode 100644 index 000000000..a94615308 --- /dev/null +++ b/gitbook/features/parallel.md @@ -0,0 +1,97 @@ +# Parallel Orchestration + +Run multiple milestones simultaneously in isolated git worktrees. Each milestone gets its own worker process, branch, and context window. + +{% hint style="info" %} +Parallel mode is off by default. Enable it in preferences to use `/gsd parallel` commands. +{% endhint %} + +## Quick Start + +1. Enable parallel mode: + ```yaml + parallel: + enabled: true + max_workers: 2 + ``` + +2. Start parallel execution: + ``` + /gsd parallel start + ``` + GSD scans milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers. + +3. Monitor: + ``` + /gsd parallel status + ``` + +4. Stop: + ``` + /gsd parallel stop + ``` + +## How It Works + +Each worker is a separate GSD process with complete isolation: + +| Resource | Isolation | +|----------|----------| +| Filesystem | Own git worktree | +| Git branch | `milestone/` | +| Context window | Separate process | +| Metrics | Own `metrics.json` | +| Crash recovery | Own `auto.lock` | + +Workers communicate with the coordinator through file-based IPC — heartbeat files and signal files in `.gsd/parallel/`. + +## Eligibility + +Before starting, GSD checks which milestones can run concurrently: + +1. **Not complete** — finished milestones are skipped +2. **Dependencies satisfied** — all `dependsOn` entries must be complete +3. **File overlap** — milestones touching the same files get a warning (but are still eligible since they run in separate worktrees) + +## Configuration + +```yaml +parallel: + enabled: false # master toggle (default: false) + max_workers: 2 # concurrent workers (1-4) + budget_ceiling: 50.00 # aggregate cost limit + merge_strategy: "per-milestone" # when to merge back + auto_merge: "confirm" # "auto", "confirm", or "manual" +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `/gsd parallel start` | Analyze and start workers | +| `/gsd parallel status` | Show all workers with progress and cost | +| `/gsd parallel stop [MID]` | Stop all or a specific worker | +| `/gsd parallel pause [MID]` | Pause all or a specific worker | +| `/gsd parallel resume [MID]` | Resume paused workers | +| `/gsd parallel merge [MID]` | Merge completed milestones to main | + +## Merge Reconciliation + +When milestones complete, their changes merge back to main: + +- `.gsd/` state files are auto-resolved +- Code conflicts halt the merge — resolve manually and retry with `/gsd parallel merge ` + +## Budget Management + +When `budget_ceiling` is set, aggregate cost across all workers is tracked. When the ceiling is reached, workers are signaled to stop. + +## Troubleshooting + +| Problem | Fix | +|---------|-----| +| "Parallel mode is not enabled" | Set `parallel.enabled: true` | +| "No eligible milestones" | All milestones are complete or blocked; check `/gsd queue` | +| Worker crashed | Run `/gsd doctor --fix`, then `/gsd parallel start` | +| Merge conflicts | Resolve in `.gsd/worktrees//`, then `/gsd parallel merge ` | +| Workers seem stuck | Check if budget ceiling was reached via `/gsd parallel status` | diff --git a/gitbook/features/remote-questions.md b/gitbook/features/remote-questions.md new file mode 100644 index 000000000..2c16ef8db --- /dev/null +++ b/gitbook/features/remote-questions.md @@ -0,0 +1,90 @@ +# Remote Questions + +Remote questions let GSD ask for your input via Slack, Discord, or Telegram when running in headless auto mode. When GSD needs a decision, it posts the question to your configured channel and polls for a response. + +## Setup + +### Discord + +``` +/gsd remote discord +``` + +The wizard prompts for your bot token, validates it, lets you pick a server and channel, sends a test message, and saves the config. + +**Bot requirements:** +- A bot application with a token from the [Discord Developer Portal](https://discord.com/developers/applications) +- Bot invited to the server with: Send Messages, Read Message History, Add Reactions, View Channel +- `DISCORD_BOT_TOKEN` environment variable set + +### Slack + +``` +/gsd remote slack +``` + +**Bot requirements:** +- A Slack app with a bot token (`xoxb-...`) from [Slack API](https://api.slack.com/apps) +- Bot invited to the target channel +- Scopes: `chat:write`, `reactions:read`, `reactions:write`, `channels:read`, `groups:read`, `channels:history`, `groups:history` + +### Telegram + +``` +/gsd remote telegram +``` + +**Bot requirements:** +- A bot token from [@BotFather](https://t.me/BotFather) +- Bot added to the target group chat +- `TELEGRAM_BOT_TOKEN` environment variable set + +## Configuration + +```yaml +remote_questions: + channel: discord # or slack or telegram + channel_id: "1234567890123456789" + timeout_minutes: 5 # 1-30, default 5 + poll_interval_seconds: 5 # 2-30, default 5 +``` + +## How It Works + +1. GSD encounters a decision point during auto mode +2. The question is posted to your channel as a rich message +3. GSD polls for a response at the configured interval +4. You respond by: + - **Reacting** with a number emoji (1️⃣, 2️⃣, etc.) for single-question prompts + - **Replying** with a number, comma-separated numbers, or free text +5. GSD picks up the response and continues +6. A ✅ reaction confirms receipt + +### Response Formats + +**Single question:** React with a number emoji, reply with a number, or reply with free text. + +**Multiple questions:** Reply with semicolons (`1;2;custom text`) or newlines (one answer per line). + +### Timeouts + +If no response arrives within `timeout_minutes`, GSD continues with a timeout result — typically making a conservative default choice. + +## Commands + +| Command | Description | +|---------|-------------| +| `/gsd remote` | Show menu and current status | +| `/gsd remote slack` | Set up Slack | +| `/gsd remote discord` | Set up Discord | +| `/gsd remote telegram` | Set up Telegram | +| `/gsd remote status` | Show current config | +| `/gsd remote disconnect` | Remove configuration | + +## Troubleshooting + +| Problem | Fix | +|---------|-----| +| "Remote auth failed" | Verify bot token is correct and not expired | +| "Could not send to channel" | Check bot has Send Messages permission; invite bot to channel | +| No response detected | Make sure you're replying to the prompt message, not posting a new one | diff --git a/gitbook/features/skills.md b/gitbook/features/skills.md new file mode 100644 index 000000000..4a9fd46b7 --- /dev/null +++ b/gitbook/features/skills.md @@ -0,0 +1,120 @@ +# Skills + +Skills are specialized instruction sets that GSD loads when the task matches. They provide domain-specific guidance — coding patterns, framework idioms, testing strategies, and tool usage. + +Skills follow the open [Agent Skills standard](https://agentskills.io/) and work across multiple AI agents, not just GSD. + +## Skill Directories + +| Location | Scope | Description | +|----------|-------|------------| +| `~/.agents/skills/` | Global | Shared across all projects | +| `.agents/skills/` (project root) | Project | Project-specific, committable to git | + +Global skills take precedence when names collide. + +## Installing Skills + +Skills are installed via the [skills.sh CLI](https://skills.sh): + +```bash +# Interactive — choose skills and target agents +npx skills add dpearson2699/swift-ios-skills + +# Install specific skills +npx skills add dpearson2699/swift-ios-skills --skill swift-concurrency --skill swiftui-patterns -y + +# Install all from a repo +npx skills add dpearson2699/swift-ios-skills --all + +# Check for updates +npx skills check + +# Update installed skills +npx skills update +``` + +## Onboarding Catalog + +During `gsd init`, GSD detects your project's tech stack and recommends relevant skill packs: + +- **Swift** — SwiftUI, Swift Core, concurrency, Charts, Testing +- **iOS** — App Intents, Widgets, StoreKit, MapKit, Core ML, Vision, accessibility +- **Web** — React, React Native, frontend design, accessibility +- **Languages** — Rust, Python, Go patterns and best practices +- **General** — Document handling (PDF, DOCX, XLSX) + +## Skill Discovery + +The `skill_discovery` preference controls how GSD finds skills during auto mode: + +| Mode | Behavior | +|------|----------| +| `auto` | Skills found and applied automatically | +| `suggest` | Skills identified but require confirmation (default) | +| `off` | No skill discovery | + +## Skill Preferences + +Control which skills are used: + +```yaml +always_use_skills: + - debug-like-expert +prefer_skills: + - frontend-design +avoid_skills: + - security-docker +skill_rules: + - when: task involves authentication + use: [clerk] + - when: frontend styling work + prefer: [frontend-design] +``` + +## Creating Custom Skills + +Create your own skill by adding a directory with a `SKILL.md` file: + +``` +~/.agents/skills/my-skill/ + SKILL.md — instructions for the AI + references/ — optional reference files +``` + +The `SKILL.md` contains instructions the AI follows when the skill is active. + +### Project-Local Skills + +Place skills in your project root for project-specific guidance: + +``` +.agents/skills/my-project-skill/ + SKILL.md +``` + +Project-local skills can be committed to git so team members share the same skill set. + +## Skill Health Dashboard + +Track skill performance: + +``` +/gsd skill-health # overview table +/gsd skill-health rust-core # detailed view for one skill +/gsd skill-health --stale 30 # skills unused for 30+ days +/gsd skill-health --declining # skills with falling success rates +``` + +The dashboard flags: +- Success rate below 70% over the last 10 uses +- Token usage rising 20%+ compared to previous window +- Skills unused beyond the configured threshold + +### Staleness Detection + +```yaml +skill_staleness_days: 60 # flag skills unused for 60+ days (0 to disable) +``` + +Stale skills are excluded from automatic matching but remain available for explicit use. diff --git a/gitbook/features/teams.md b/gitbook/features/teams.md new file mode 100644 index 000000000..44dac0c57 --- /dev/null +++ b/gitbook/features/teams.md @@ -0,0 +1,91 @@ +# Working in Teams + +GSD supports multi-user workflows where several developers work on the same repository concurrently. + +## Quick Setup + +The simplest way: set team mode in your project preferences. + +```yaml +# .gsd/PREFERENCES.md (committed to git) +--- +version: 1 +mode: team +--- +``` + +This enables unique milestone IDs, push branches, pre-merge checks, and other team-appropriate defaults in one setting. + +## What Team Mode Does + +| Setting | Effect | +|---------|--------| +| `unique_milestone_ids` | IDs like `M001-eh88as` instead of `M001` — no collisions | +| `git.push_branches` | Milestone branches are pushed to remote | +| `git.pre_merge_check` | Validation runs before merging | + +You can override individual settings on top of `mode: team`. + +## Configure `.gitignore` + +Share planning artifacts while keeping runtime files local: + +```bash +# Runtime files (per-developer, gitignore these) +.gsd/auto.lock +.gsd/completed-units.json +.gsd/STATE.md +.gsd/metrics.json +.gsd/activity/ +.gsd/runtime/ +.gsd/worktrees/ +.gsd/milestones/**/continue.md +.gsd/milestones/**/*-CONTINUE.md +``` + +**What gets shared** (committed to git): +- `.gsd/PREFERENCES.md` — project preferences +- `.gsd/PROJECT.md` — living project description +- `.gsd/REQUIREMENTS.md` — requirement contract +- `.gsd/DECISIONS.md` — architectural decisions +- `.gsd/milestones/` — roadmaps, plans, summaries, research + +**What stays local** (gitignored): +- Lock files, metrics, state, activity logs, worktrees + +## Commit the Config + +```bash +git add .gsd/PREFERENCES.md +git commit -m "chore: enable GSD team workflow" +``` + +## Keeping `.gsd/` Local + +For teams where only some members use GSD: + +```yaml +git: + commit_docs: false +``` + +This gitignores `.gsd/` entirely. You get structured planning without affecting teammates. + +## Parallel Development + +Multiple developers can run auto mode simultaneously on different milestones. Each developer: + +- Gets their own worktree (`.gsd/worktrees//`) +- Works on a unique `milestone/` branch +- Squash-merges to main independently + +Milestone dependencies can be declared: + +```yaml +# In M00X-CONTEXT.md frontmatter +--- +depends_on: [M001-eh88as] +--- +``` + +GSD enforces that dependent milestones complete before starting downstream work. diff --git a/gitbook/features/token-optimization.md b/gitbook/features/token-optimization.md new file mode 100644 index 000000000..c89493618 --- /dev/null +++ b/gitbook/features/token-optimization.md @@ -0,0 +1,108 @@ +# Token Optimization + +GSD's token optimization system can reduce token usage by 40-60% without sacrificing output quality. It has three pillars: **token profiles**, **context compression**, and **complexity-based task routing**. + +## Token Profiles + +A token profile coordinates model selection, phase skipping, and context compression with a single setting: + +```yaml +token_profile: balanced +``` + +### `budget` — Maximum Savings (40-60%) + +| Setting | Value | +|---------|-------| +| Planning model | Sonnet | +| Execution model | Sonnet | +| Simple task model | Haiku | +| Milestone research | Skipped | +| Slice research | Skipped | +| Roadmap reassessment | Skipped | +| Context level | Minimal | + +Best for: prototyping, small projects, well-understood codebases. + +### `balanced` — Smart Defaults (default) + +| Setting | Value | +|---------|-------| +| All models | User's default | +| Milestone research | Runs | +| Slice research | Skipped | +| Roadmap reassessment | Runs | +| Context level | Standard | + +Best for: most projects, day-to-day development. + +### `quality` — Full Context + +| Setting | Value | +|---------|-------| +| All models | User's configured defaults | +| All phases | Run | +| Context level | Full | + +Best for: complex architectures, greenfield projects, critical work. + +## Context Compression + +Each profile controls how much context is pre-loaded into AI prompts: + +| Profile | What's Included | +|---------|----------------| +| `budget` | Task plan and essential prior summaries only | +| `balanced` | Task plan, summaries, slice plan, roadmap excerpt | +| `quality` | Everything — all plans, summaries, decisions, requirements | + +## Complexity-Based Task Routing + +GSD classifies each task by complexity and routes it to an appropriate model: + +| Complexity | Indicators | Model Level | +|-----------|------------|-------------| +| Simple | ≤3 steps, ≤3 files, short description | Haiku-class | +| Standard | 4-7 steps, 4-7 files | Sonnet-class | +| Complex | ≥8 steps, ≥8 files, complexity keywords | Opus-class | + +**Complexity keywords** that prevent simple classification: `refactor`, `migrate`, `integrate`, `architect`, `security`, `performance`, `concurrent`, `distributed`, and others. + +{% hint style="info" %} +Dynamic routing requires `models` configured in your preferences and `dynamic_routing.enabled: true`. See [Dynamic Model Routing](dynamic-model-routing.md). +{% endhint %} + +## Overriding Profile Defaults + +The `token_profile` sets defaults, but explicit preferences always win: + +```yaml +token_profile: budget +phases: + skip_research: false # override: keep research +models: + planning: claude-opus-4-6 # override: use Opus for planning +``` + +## Adaptive Learning + +GSD tracks success and failure of tier assignments over time. If a model tier's failure rate exceeds 20% for a given task type, future tasks of that type are bumped to a higher tier. + +Submit manual feedback with: + +``` +/gsd rate over # model was overpowered — use cheaper next time +/gsd rate ok # model was appropriate +/gsd rate under # model was too weak — use stronger next time +``` + +## Observation Masking + +During auto mode, old tool results are replaced with lightweight placeholders before each AI call. This reduces token usage between compactions with zero overhead. + +```yaml +context_management: + observation_masking: true # default: true + observation_mask_turns: 8 # keep results from last 8 turns + tool_result_max_chars: 800 # truncate large tool outputs +``` diff --git a/gitbook/features/visualizer.md b/gitbook/features/visualizer.md new file mode 100644 index 000000000..4155ec144 --- /dev/null +++ b/gitbook/features/visualizer.md @@ -0,0 +1,82 @@ +# Workflow Visualizer + +The workflow visualizer is a full-screen terminal overlay showing project progress, dependencies, cost metrics, and execution timeline. + +## Opening + +``` +/gsd visualize +``` + +Or configure automatic display after milestone completion: + +```yaml +auto_visualize: true +``` + +## Tabs + +Switch tabs with `Tab`, `1`-`4`, or arrow keys. + +### 1. Progress + +A tree view of milestones, slices, and tasks with completion status: + +``` +M001: User Management 3/6 tasks + ✅ S01: Auth module 3/3 tasks + ✅ T01: Core types + ✅ T02: JWT middleware + ✅ T03: Login flow + ⏳ S02: User dashboard 1/2 tasks + ✅ T01: Layout component + ⬜ T02: Profile page +``` + +### 2. Dependencies + +An ASCII dependency graph showing slice relationships: + +``` +S01 ──→ S02 ──→ S04 + └───→ S03 ──↗ +``` + +### 3. Metrics + +Bar charts showing cost and token usage: + +- By phase (research, planning, execution, completion) +- By slice (with running totals) +- By model (which models consumed the most budget) + +### 4. Timeline + +Chronological execution history: unit type, timestamps, duration, model, and token counts. + +## Controls + +| Key | Action | +|-----|--------| +| `Tab` | Next tab | +| `Shift+Tab` | Previous tab | +| `1`-`4` | Jump to tab | +| `↑`/`↓` | Scroll | +| `Escape` / `q` | Close | + +The visualizer auto-refreshes every 2 seconds, staying current alongside running auto mode. + +## HTML Reports + +For shareable reports outside the terminal: + +``` +/gsd export --html # current milestone +/gsd export --html --all # all milestones +``` + +Generates self-contained HTML files in `.gsd/reports/` with progress tree, dependency graph, cost charts, timeline, and changelog. All CSS and JS are inlined — no external dependencies. Printable to PDF from any browser. + +```yaml +auto_report: true # auto-generate after milestone completion (default) +``` diff --git a/gitbook/features/web-interface.md b/gitbook/features/web-interface.md new file mode 100644 index 000000000..6870ffc41 --- /dev/null +++ b/gitbook/features/web-interface.md @@ -0,0 +1,37 @@ +# Web Interface + +GSD includes a browser-based interface for project management and real-time progress monitoring. + +## Quick Start + +```bash +gsd --web +``` + +This starts a local web server and opens the dashboard in your default browser. + +## CLI Flags + +```bash +gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com" +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--host` | `localhost` | Bind address | +| `--port` | `3000` | Port | +| `--allowed-origins` | (none) | Comma-separated CORS origins | + +## Features + +- **Project management** — view milestones, slices, and tasks in a visual dashboard +- **Real-time progress** — live updates as auto mode executes +- **Multi-project support** — manage multiple projects from one browser tab via `?project=` URL parameter +- **Change project root** — switch directories from the web UI without restarting +- **Onboarding flow** — API key setup and provider configuration in the browser +- **Model selection** — switch models and providers from the web UI + +## Platform Notes + +- **macOS/Linux** — Full support +- **Windows** — Web build is skipped due to Next.js compatibility issues; CLI remains fully functional diff --git a/gitbook/features/workflow-templates.md b/gitbook/features/workflow-templates.md new file mode 100644 index 000000000..45246a33b --- /dev/null +++ b/gitbook/features/workflow-templates.md @@ -0,0 +1,45 @@ +# Workflow Templates + +Workflow templates are pre-built patterns for common development tasks. Instead of setting up a full milestone for a quick bugfix or spike, use a template to get started immediately. + +## Using Templates + +``` +/gsd start # pick from available templates +/gsd start resume # resume an in-progress workflow +``` + +## Available Templates + +| Template | Purpose | +|----------|---------| +| `bugfix` | Fix a specific bug with diagnosis and verification | +| `spike` | Time-boxed investigation or prototype | +| `feature` | Standard feature development | +| `hotfix` | Urgent production fix | +| `refactor` | Code restructuring and cleanup | +| `security-audit` | Security review and remediation | +| `dep-upgrade` | Dependency update and migration | +| `full-project` | Complete project from scratch | + +## Listing and Inspecting + +``` +/gsd templates # list all available templates +/gsd templates info # show details for a template +``` + +## Custom Workflows + +Create your own workflow definitions: + +``` +/gsd workflow new # create a new workflow YAML +/gsd workflow run # start a workflow run +/gsd workflow list # list active runs +/gsd workflow validate # validate definition +/gsd workflow pause # pause running workflow +/gsd workflow resume # resume paused workflow +``` + +Custom workflows are defined in YAML and can specify phases, dependencies, and configuration for each step. diff --git a/gitbook/getting-started/choosing-a-model.md b/gitbook/getting-started/choosing-a-model.md new file mode 100644 index 000000000..64b2e3aad --- /dev/null +++ b/gitbook/getting-started/choosing-a-model.md @@ -0,0 +1,94 @@ +# Choosing a Model + +GSD auto-selects a default model after you log in to a provider. You can switch models at any time. + +## Switch Models + +Inside a GSD session, type: + +``` +/model +``` + +This opens an interactive picker showing all available models from your configured providers. + +## Per-Phase Models + +Different phases of work have different requirements. You can assign specific models to each phase in your preferences: + +```yaml +models: + research: claude-sonnet-4-6 # scouting and research + planning: claude-opus-4-6 # architectural decisions + execution: claude-sonnet-4-6 # writing code + execution_simple: claude-haiku-4-5 # simple tasks (docs, config) + completion: claude-sonnet-4-6 # summaries and wrap-up + subagent: claude-sonnet-4-6 # delegated sub-tasks +``` + +Omit a key to use whatever model is currently active for that phase. + +## Model Fallbacks + +If a model is unavailable (provider down, rate limited, credits exhausted), GSD can automatically fall back to another: + +```yaml +models: + planning: + model: claude-opus-4-6 + fallbacks: + - openrouter/z-ai/glm-5 + - openrouter/moonshotai/kimi-k2.5 +``` + +Fallbacks are tried in order until one works. + +## Token Profiles + +Token profiles coordinate model selection, phase skipping, and context compression with a single setting: + +| Profile | Cost Savings | Best For | +|---------|-------------|----------| +| `budget` | 40-60% | Prototyping, small projects, well-understood codebases | +| `balanced` | 10-20% | Most projects, day-to-day development (default) | +| `quality` | 0% (baseline) | Complex architectures, greenfield projects, critical work | + +```yaml +token_profile: balanced +``` + +See [Token Optimization](../features/token-optimization.md) for details. + +## Dynamic Model Routing + +When enabled, GSD automatically picks cheaper models for simple tasks and reserves expensive ones for complex work: + +```yaml +dynamic_routing: + enabled: true +``` + +A documentation fix gets Haiku. An architectural refactor gets Opus. Your configured model is always the ceiling — routing never upgrades beyond what you've set. + +See [Dynamic Model Routing](../features/dynamic-model-routing.md) for the full guide. + +## Supported Providers + +GSD supports 20+ providers out of the box. See [Provider Setup](../configuration/providers.md) for setup instructions: + +| Provider | Auth Method | +|----------|-------------| +| Anthropic (Claude) | OAuth or API key | +| OpenAI | API key | +| Google Gemini | API key | +| OpenRouter | API key | +| Groq | API key | +| xAI (Grok) | API key | +| Mistral | API key | +| GitHub Copilot | OAuth | +| Amazon Bedrock | IAM credentials | +| Vertex AI | ADC | +| Azure OpenAI | API key | +| Ollama | Local (no auth) | +| LM Studio | Local (no auth) | +| vLLM / SGLang | Local (no auth) | diff --git a/gitbook/getting-started/first-project.md b/gitbook/getting-started/first-project.md new file mode 100644 index 000000000..dd0551035 --- /dev/null +++ b/gitbook/getting-started/first-project.md @@ -0,0 +1,128 @@ +# Your First Project + +## Launch GSD + +Open a terminal in any project directory (or an empty one) and run: + +```bash +gsd +``` + +GSD shows a welcome screen with your version, active model, and available tool keys. + +## Start a Discussion + +Type `/gsd` to enter step mode. GSD reads the state of your project directory and determines the next logical action: + +- **No `.gsd/` directory** — starts a discussion flow to capture your project vision +- **Milestone exists, no roadmap** — discuss or research the milestone +- **Roadmap exists, slices pending** — plan the next slice or execute a task +- **Mid-task** — resume where you left off + +For a new project, GSD will ask you to describe what you want to build. Talk through your vision — GSD captures requirements, architectural decisions, and scope. + +## The Project Hierarchy + +After discussion, GSD organizes your work into: + +``` +Milestone → a shippable version (4-10 slices) + Slice → one demoable feature (1-7 tasks) + Task → one context-window-sized unit of work +``` + +The key rule: **a task must fit in one AI context window.** If it can't, it becomes two tasks. + +## Run Auto Mode + +Once you have a milestone and roadmap, let GSD take the wheel: + +``` +/gsd auto +``` + +GSD autonomously: +1. **Plans** each slice — scouts the codebase, researches docs, decomposes into tasks +2. **Executes** each task — writes code in a fresh AI session +3. **Completes** the slice — writes summaries, commits with meaningful messages +4. **Reassesses** the roadmap — checks if the plan still makes sense +5. **Repeats** until the milestone is done + +## The Two-Terminal Workflow + +The recommended approach: auto mode in one terminal, steering from another. + +**Terminal 1 — let it build:** + +```bash +gsd +/gsd auto +``` + +**Terminal 2 — steer while it works:** + +```bash +gsd +/gsd discuss # talk through architecture decisions +/gsd status # check progress +/gsd queue # queue the next milestone +/gsd capture "add rate limiting to the API" # fire-and-forget thought +``` + +Both terminals read and write the same `.gsd/` files. Decisions in terminal 2 are picked up at the next phase boundary automatically. + +## Check Progress + +Press `Ctrl+Alt+G` or type `/gsd status` to see the dashboard: + +- Current milestone, slice, and task +- Elapsed time and phase +- Per-unit cost and token breakdown +- Completed and in-progress work + +## Resume a Session + +```bash +gsd --continue # or gsd -c +``` + +Resumes the most recent session for the current directory. + +To browse and pick from all saved sessions: + +```bash +gsd sessions +``` + +Shows each session's date, message count, and preview so you can choose which to resume. + +## What's on Disk + +All state lives in `.gsd/` inside your project: + +``` +.gsd/ + PROJECT.md — what the project is + REQUIREMENTS.md — requirement contract + DECISIONS.md — architectural decisions + KNOWLEDGE.md — cross-session rules and patterns + STATE.md — quick-glance status + milestones/ + M001/ + M001-ROADMAP.md — slice plan with dependencies + M001-CONTEXT.md — scope and goals + slices/ + S01/ + S01-PLAN.md — task decomposition + S01-SUMMARY.md — what happened + S01-UAT.md — test script + tasks/ + T01-PLAN.md + T01-SUMMARY.md +``` + +## Next Steps + +- [Auto Mode](../core-concepts/auto-mode.md) — deep dive into autonomous execution +- [Preferences](../configuration/preferences.md) — model selection, timeouts, budgets +- [Commands](../reference/commands.md) — all commands and shortcuts diff --git a/gitbook/getting-started/installation.md b/gitbook/getting-started/installation.md new file mode 100644 index 000000000..e1e72fe80 --- /dev/null +++ b/gitbook/getting-started/installation.md @@ -0,0 +1,84 @@ +# Installation + +## Install GSD + +```bash +npm install -g gsd-pi +``` + +Requires **Node.js 22.0.0 or later** (24 LTS recommended) and **Git**. + +{% hint style="info" %} +**`command not found: gsd`?** Your shell may not have npm's global bin directory in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin` to your PATH. See [Troubleshooting](../reference/troubleshooting.md) for details. +{% endhint %} + +GSD checks for updates once every 24 hours. When a new version is available, you'll see a prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`. + +## Set Up Your LLM Provider + +Launch GSD for the first time: + +```bash +gsd +``` + +The setup wizard walks you through: + +1. **LLM Provider** — choose from 20+ providers (Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Azure, and more). OAuth flows handle Claude Max and Copilot subscriptions automatically; otherwise paste an API key. +2. **Tool API Keys** (optional) — Brave Search, Context7, Jina, Slack, Discord. Press Enter to skip any. + +Re-run the wizard anytime with: + +```bash +gsd config +``` + +For detailed provider setup, see [Provider Setup](../configuration/providers.md). + +## Set Up API Keys for Tools + +If you use a non-Anthropic model, you may need a search API key for web search. Run `/gsd config` inside any GSD session to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects. + +| Tool | Purpose | Get a Key | +|------|---------|-----------| +| Tavily Search | Web search for non-Anthropic models | [tavily.com](https://tavily.com/app/api-keys) | +| Brave Search | Web search for non-Anthropic models | [brave.com](https://brave.com/search/api) | +| Context7 Docs | Library documentation lookup | [context7.com](https://context7.com/dashboard) | + +Anthropic models have built-in web search and don't need these keys. + +## VS Code Extension + +GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. + +The extension provides: + +- **`@gsd` chat participant** — talk to the agent in VS Code Chat +- **Sidebar dashboard** — connection status, model info, token usage, quick actions +- **Full command palette** — start/stop agent, switch models, export sessions + +The CLI (`gsd-pi`) must be installed first — the extension connects to it via RPC. + +## Web Interface + +GSD also has a browser-based interface: + +```bash +gsd --web +``` + +This starts a local web server with a visual dashboard, real-time progress, and multi-project support. See [Web Interface](../features/web-interface.md) for details. + +## Alternative Binary Name + +If the `gsd` command conflicts with another tool (e.g., the oh-my-zsh git plugin aliases `gsd` to `git svn dcommit`), use the alternative: + +```bash +gsd-cli +``` + +Both `gsd` and `gsd-cli` point to the same binary. To remove the conflict permanently, add this to your `~/.zshrc`: + +```bash +unalias gsd 2>/dev/null +``` diff --git a/gitbook/reference/cli-flags.md b/gitbook/reference/cli-flags.md new file mode 100644 index 000000000..a1de87f37 --- /dev/null +++ b/gitbook/reference/cli-flags.md @@ -0,0 +1,61 @@ +# CLI Flags + +## Starting GSD + +| Flag | Description | +|------|-------------| +| `gsd` | Start a new interactive session | +| `gsd --continue` (`-c`) | Resume the most recent session | +| `gsd --model ` | Override the default model for this session | +| `gsd --web [path]` | Start browser-based web interface | +| `gsd --worktree` (`-w`) [name] | Start in a git worktree | +| `gsd --no-session` | Disable session persistence | +| `gsd --extension ` | Load an additional extension (repeatable) | +| `gsd --append-system-prompt ` | Append text to the system prompt | +| `gsd --tools ` | Comma-separated tools to enable | +| `gsd --version` (`-v`) | Print version and exit | +| `gsd --help` (`-h`) | Print help and exit | +| `gsd --debug` | Enable diagnostic logging | + +## Non-Interactive Modes + +| Flag | Description | +|------|-------------| +| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) | +| `gsd --mode ` | Output mode for non-interactive use | + +## Session Management + +| Command | Description | +|---------|-------------| +| `gsd sessions` | Interactive session picker — list and resume saved sessions | +| `gsd --list-models [search]` | List available models and exit | + +## Configuration + +| Command | Description | +|---------|-------------| +| `gsd config` | Set up global API keys | +| `gsd update` | Update to the latest version | + +## Headless Mode + +| Flag | Description | +|------|-------------| +| `gsd headless` | Run without TUI | +| `gsd headless --timeout N` | Timeout in ms (default: 300000) | +| `gsd headless --max-restarts N` | Auto-restart on crash (default: 3) | +| `gsd headless --json` | Stream events as JSONL | +| `gsd headless --model ID` | Override model | +| `gsd headless --context ` | Context file for `new-milestone` | +| `gsd headless --context-text ` | Inline context for `new-milestone` | +| `gsd headless --auto` | Chain into auto mode after milestone creation | +| `gsd headless query` | Instant JSON state snapshot (~50ms) | + +## Web Interface + +| Flag | Default | Description | +|------|---------|-------------| +| `--host` | `localhost` | Bind address | +| `--port` | `3000` | Port | +| `--allowed-origins` | (none) | CORS origins | diff --git a/gitbook/reference/commands.md b/gitbook/reference/commands.md new file mode 100644 index 000000000..e042723da --- /dev/null +++ b/gitbook/reference/commands.md @@ -0,0 +1,128 @@ +# Commands + +## Session Commands + +| Command | Description | +|---------|-------------| +| `/gsd` | Step mode — execute one unit at a time | +| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat | +| `/gsd quick` | Quick task with GSD guarantees but no full planning | +| `/gsd stop` | Stop auto mode gracefully | +| `/gsd pause` | Pause auto mode (preserves state) | +| `/gsd steer` | Modify plan documents during execution | +| `/gsd discuss` | Discuss architecture and decisions | +| `/gsd status` | Progress dashboard | +| `/gsd widget` | Cycle dashboard widget: full / small / min / off | +| `/gsd queue` | Queue and reorder future milestones | +| `/gsd capture` | Fire-and-forget thought capture | +| `/gsd triage` | Manually trigger capture triage | +| `/gsd dispatch` | Dispatch a specific phase directly | +| `/gsd history` | View execution history (supports `--cost`, `--phase`, `--model` filters) | +| `/gsd forensics` | Full debugger for auto-mode failures | +| `/gsd cleanup` | Clean up state files and stale worktrees | +| `/gsd visualize` | Open workflow visualizer | +| `/gsd export --html` | Generate HTML report for current milestone | +| `/gsd export --html --all` | Generate reports for all milestones | +| `/gsd update` | Update GSD to the latest version | +| `/gsd knowledge` | Add persistent project knowledge | +| `/gsd fast` | Toggle service tier for supported models | +| `/gsd rate` | Rate last unit's model tier (over/ok/under) | +| `/gsd changelog` | Show release notes | +| `/gsd logs` | Browse activity and debug logs | +| `/gsd remote` | Control remote auto-mode | +| `/gsd help` | Show all available commands | + +## Configuration & Diagnostics + +| Command | Description | +|---------|-------------| +| `/gsd prefs` | Preferences wizard | +| `/gsd mode` | Switch workflow mode (solo/team) | +| `/gsd config` | Re-run provider setup wizard | +| `/gsd keys` | API key manager | +| `/gsd doctor` | Runtime health checks with auto-fix | +| `/gsd inspect` | Show database diagnostics | +| `/gsd init` | Project init wizard | +| `/gsd setup` | Global setup status | +| `/gsd skill-health` | Skill lifecycle dashboard | +| `/gsd hooks` | Show configured hooks | +| `/gsd migrate` | Migrate v1 `.planning` to `.gsd` format | + +## Milestone Management + +| Command | Description | +|---------|-------------| +| `/gsd new-milestone` | Create a new milestone | +| `/gsd skip` | Prevent a unit from auto-mode dispatch | +| `/gsd undo` | Revert last completed unit | +| `/gsd undo-task` | Reset a specific task's completion state | +| `/gsd reset-slice` | Reset a slice and all its tasks | +| `/gsd park` | Park a milestone (skip without deleting) | +| `/gsd unpark` | Reactivate a parked milestone | + +## Parallel Orchestration + +| Command | Description | +|---------|-------------| +| `/gsd parallel start` | Analyze and start parallel workers | +| `/gsd parallel status` | Show worker state and progress | +| `/gsd parallel stop [MID]` | Stop workers | +| `/gsd parallel pause [MID]` | Pause workers | +| `/gsd parallel resume [MID]` | Resume workers | +| `/gsd parallel merge [MID]` | Merge completed milestones | + +## Workflow Templates + +| Command | Description | +|---------|-------------| +| `/gsd start` | Start a workflow template | +| `/gsd start resume` | Resume an in-progress workflow | +| `/gsd templates` | List available templates | +| `/gsd templates info ` | Show template details | + +## Custom Workflows + +| Command | Description | +|---------|-------------| +| `/gsd workflow new` | Create a workflow definition | +| `/gsd workflow run ` | Start a workflow run | +| `/gsd workflow list` | List workflow runs | +| `/gsd workflow validate ` | Validate a workflow YAML | +| `/gsd workflow pause` | Pause workflow auto-mode | +| `/gsd workflow resume` | Resume paused workflow | + +## Extensions + +| Command | Description | +|---------|-------------| +| `/gsd extensions list` | List all extensions | +| `/gsd extensions enable ` | Enable an extension | +| `/gsd extensions disable ` | Disable an extension | +| `/gsd extensions info ` | Show extension details | + +## GitHub Sync + +| Command | Description | +|---------|-------------| +| `/github-sync bootstrap` | Initial GitHub sync setup | +| `/github-sync status` | Show sync mapping counts | + +## Session Management + +| Command | Description | +|---------|-------------| +| `/clear` | Start a new session | +| `/exit` | Graceful shutdown | +| `/model` | Switch the active model | +| `/login` | Log in to an LLM provider | +| `/thinking` | Toggle thinking level | +| `/voice` | Toggle speech-to-text | +| `/worktree` (`/wt`) | Git worktree management | + +## In-Session Update + +``` +/gsd update +``` + +Checks npm for a newer version and installs it without leaving the session. diff --git a/gitbook/reference/environment-variables.md b/gitbook/reference/environment-variables.md new file mode 100644 index 000000000..c23af72df --- /dev/null +++ b/gitbook/reference/environment-variables.md @@ -0,0 +1,56 @@ +# Environment Variables + +## GSD Configuration + +| Variable | Default | Description | +|----------|---------|-------------| +| `GSD_HOME` | `~/.gsd` | Global GSD directory. All paths derive from this unless individually overridden. | +| `GSD_PROJECT_ID` | (auto-hash) | Override automatic project identity hash. Useful for CI/CD or sharing state across repo clones. | +| `GSD_STATE_DIR` | `$GSD_HOME` | Per-project state root. Controls where `projects//` directories are created. | +| `GSD_CODING_AGENT_DIR` | `$GSD_HOME/agent` | Agent directory for extensions, auth, and managed resources. | +| `GSD_FETCH_ALLOWED_URLS` | (none) | Comma-separated hostnames exempt from internal URL blocking. | +| `GSD_ALLOWED_COMMAND_PREFIXES` | (built-in) | Comma-separated command prefixes allowed for value resolution. | +| `GSD_WEB_PROJECT_CWD` | — | Default project path for `gsd --web` when `?project=` is not specified. | + +## LLM Provider Keys + +| Variable | Provider | +|----------|----------| +| `ANTHROPIC_API_KEY` | Anthropic (Claude) | +| `OPENAI_API_KEY` | OpenAI | +| `GEMINI_API_KEY` | Google Gemini | +| `OPENROUTER_API_KEY` | OpenRouter | +| `GROQ_API_KEY` | Groq | +| `XAI_API_KEY` | xAI (Grok) | +| `MISTRAL_API_KEY` | Mistral | +| `GH_TOKEN` | GitHub Copilot | +| `AWS_PROFILE` | Amazon Bedrock (named profile) | +| `AWS_ACCESS_KEY_ID` | Amazon Bedrock (IAM keys) | +| `AWS_SECRET_ACCESS_KEY` | Amazon Bedrock (IAM keys) | +| `AWS_REGION` | Amazon Bedrock (region) | +| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock (bearer token) | +| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI | +| `GOOGLE_APPLICATION_CREDENTIALS` | Vertex AI (ADC) | +| `AZURE_OPENAI_API_KEY` | Azure OpenAI | + +## Tool API Keys + +| Variable | Purpose | +|----------|---------| +| `TAVILY_API_KEY` | Tavily web search | +| `BRAVE_API_KEY` | Brave web search | +| `CONTEXT7_API_KEY` | Context7 documentation lookup | +| `DISCORD_BOT_TOKEN` | Discord remote questions | +| `TELEGRAM_BOT_TOKEN` | Telegram remote questions | + +## URL Blocking + +The `fetch_page` tool blocks requests to private/internal networks by default (SSRF protection). To allow specific internal hosts: + +```bash +export GSD_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50" +``` + +Or set `fetchAllowedUrls` in `~/.gsd/agent/settings.json`. + +Blocked by default: private IP ranges, cloud metadata endpoints, localhost, non-HTTP protocols, IPv6 private ranges. diff --git a/gitbook/reference/keyboard-shortcuts.md b/gitbook/reference/keyboard-shortcuts.md new file mode 100644 index 000000000..8b2013729 --- /dev/null +++ b/gitbook/reference/keyboard-shortcuts.md @@ -0,0 +1,33 @@ +# Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| `Ctrl+Alt+G` | Toggle dashboard overlay | +| `Ctrl+Alt+V` | Toggle voice transcription | +| `Ctrl+Alt+B` | Show background shell processes | +| `Ctrl+V` / `Alt+V` | Paste image from clipboard (screenshot → vision input) | +| `Escape` | Pause auto mode (preserves conversation) | + +## Terminal Compatibility + +In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts. + +{% hint style="tip" %} +If `Ctrl+V` is intercepted by your terminal (e.g. Warp), use `Alt+V` instead for clipboard image paste. +{% endhint %} + +## iTerm2 Note + +If `Ctrl+Alt` shortcuts trigger the wrong action (e.g., `Ctrl+Alt+G` opens external editor instead of the dashboard), go to **Profiles → Keys → General** and set **Left Option Key** to **Esc+**. This makes Alt/Option work correctly with Ctrl combinations. + +## cmux Integration + +If you use cmux (terminal multiplexer), GSD can integrate with it: + +| Command | Description | +|---------|-------------| +| `/gsd cmux status` | Show cmux detection and capabilities | +| `/gsd cmux on` / `off` | Enable/disable integration | +| `/gsd cmux notifications on/off` | Toggle desktop notifications | +| `/gsd cmux sidebar on/off` | Toggle sidebar metadata | +| `/gsd cmux splits on/off` | Toggle visual subagent splits | diff --git a/gitbook/reference/migration.md b/gitbook/reference/migration.md new file mode 100644 index 000000000..54d548dc8 --- /dev/null +++ b/gitbook/reference/migration.md @@ -0,0 +1,48 @@ +# Migration from v1 + +If you have projects with `.planning` directories from the original Get Shit Done (v1), you can migrate them to GSD-2's `.gsd` format. + +## Running the Migration + +```bash +# From within the project directory +/gsd migrate + +# Or specify a path +/gsd migrate ~/projects/my-old-project +``` + +## What Gets Migrated + +The migration tool: + +- Parses your old `PROJECT.md`, `ROADMAP.md`, `REQUIREMENTS.md`, phase directories, plans, summaries, and research +- Maps phases → slices, plans → tasks, milestones → milestones +- Preserves completion state (`[x]` phases stay done, summaries carry over) +- Consolidates research files into the new structure +- Shows a preview before writing anything +- Optionally runs an AI-driven review for quality assurance + +## Supported Formats + +The migration handles various v1 format variations: + +- Milestone-sectioned roadmaps with `
` blocks +- Bold phase entries +- Bullet-format requirements +- Decimal phase numbering +- Duplicate phase numbers across milestones + +## Requirements + +Migration works best with a `ROADMAP.md` file for milestone structure. Without one, milestones are inferred from the `phases/` directory. + +## Post-Migration + +After migrating, verify the output: + +``` +/gsd doctor +``` + +This checks `.gsd/` integrity and flags any structural issues. diff --git a/gitbook/reference/troubleshooting.md b/gitbook/reference/troubleshooting.md new file mode 100644 index 000000000..8102ede58 --- /dev/null +++ b/gitbook/reference/troubleshooting.md @@ -0,0 +1,151 @@ +# Troubleshooting + +## `/gsd doctor` + +The built-in diagnostic tool validates `.gsd/` integrity: + +``` +/gsd doctor +``` + +It checks file structure, roadmap ↔ slice ↔ task consistency, completion state, git health, stale locks, and orphaned records. + +## Common Issues + +### Auto mode loops on the same unit + +The same unit dispatches repeatedly. + +**Fix:** Run `/gsd doctor` to repair state, then `/gsd auto`. If it persists, check that the expected artifact file exists on disk. + +### Auto mode stops with "Loop detected" + +A unit failed to produce its expected artifact twice. + +**Fix:** Check the task plan for clarity. Refine it manually, then `/gsd auto`. + +### `command not found: gsd` after install + +npm's global bin directory isn't in `$PATH`. + +**Fix:** +```bash +npm prefix -g +# Add the bin dir to PATH: +echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc +source ~/.zshrc +``` + +**Common causes:** +- **Homebrew Node** — `/opt/homebrew/bin` missing from PATH +- **Version manager (nvm, fnm, mise)** — global bin is version-specific +- **oh-my-zsh** — `gitfast` plugin aliases `gsd` to `git svn dcommit`; check with `alias gsd` + +### Provider errors during auto mode + +| Error Type | Auto-Resume? | Delay | +|-----------|-------------|-------| +| Rate limit (429) | Yes | 60s or retry-after header | +| Server error (500, 502, 503) | Yes | 30s | +| Auth/billing ("unauthorized") | No | Manual resume required | + +For permanent errors, configure fallback models: + +```yaml +models: + execution: + model: claude-sonnet-4-6 + fallbacks: + - openrouter/minimax/minimax-m2.5 +``` + +### Budget ceiling reached + +Auto mode pauses with "Budget ceiling reached." + +**Fix:** Increase `budget_ceiling` in preferences, or switch to `budget` token profile, then `/gsd auto`. + +### Stale lock file + +Auto mode won't start, says another session is running. + +**Fix:** GSD auto-detects stale locks (dead PID = auto cleanup). If automatic recovery fails: + +```bash +rm -f .gsd/auto.lock +rm -rf "$(dirname .gsd)/.gsd.lock" +``` + +### Git merge conflicts + +Worktree merge fails on `.gsd/` files. + +**Fix:** `.gsd/` conflicts are auto-resolved. Code conflicts get an AI fix attempt; if that fails, resolve manually. + +### Notifications not appearing on macOS + +**Fix:** Install `terminal-notifier`: + +```bash +brew install terminal-notifier +``` + +See [Notifications](../configuration/notifications.md) for details. + +## MCP Issues + +### No servers configured + +**Fix:** Add server to `.mcp.json` or `.gsd/mcp.json`, verify JSON is valid, run `mcp_servers(refresh=true)`. + +### Server discovery times out + +**Fix:** Run the configured command outside GSD to confirm it starts. Check that backend services are reachable. + +### Server connection closed immediately + +**Fix:** Verify `command` and `args` paths are correct and absolute. Run the command manually to catch errors. + +## Recovery Procedures + +### Reset auto mode state + +```bash +rm .gsd/auto.lock +rm .gsd/completed-units.json +``` + +Then `/gsd auto` to restart from current state. + +### Reset routing history + +```bash +rm .gsd/routing-history.json +``` + +### Full state rebuild + +``` +/gsd doctor +``` + +Rebuilds `STATE.md` from plan and roadmap files and fixes inconsistencies. + +## Getting Help + +- **GitHub Issues:** [github.com/gsd-build/GSD-2/issues](https://github.com/gsd-build/GSD-2/issues) +- **Dashboard:** `Ctrl+Alt+G` or `/gsd status` +- **Forensics:** `/gsd forensics` for post-mortem analysis +- **Session logs:** `.gsd/activity/` contains JSONL session dumps + +## Platform-Specific Issues + +### iTerm2 + +`Ctrl+Alt` shortcuts trigger wrong actions → Set **Profiles → Keys → General → Left Option Key** to **Esc+**. + +### Windows + +- LSP ENOENT on MSYS2/Git Bash → Fixed in v2.29+, upgrade +- EBUSY errors during builds → Close browser extension, or change output directory +- Transient EBUSY/EPERM on `.gsd/` files → Retry; close file-locking tools if persistent diff --git a/native/README.md b/native/README.md index bf818e9d5..4f6829681 100644 --- a/native/README.md +++ b/native/README.md @@ -6,8 +6,11 @@ Rust N-API addon providing high-performance native modules for GSD. ``` JS (packages/native) -> N-API -> Rust crates - ├── engine/ (N-API bindings, cdylib) - └── grep/ (ripgrep internals, pure Rust lib) + +native/crates/ +├── engine/ (N-API bindings, cdylib — 20+ modules) +├── grep/ (ripgrep internals, pure Rust lib) +└── ast/ (ast-grep structural search) ``` Inspired by [Oh My Pi's pi-natives](https://github.com/can1357/oh-my-pi), adapted for GSD's Node.js runtime. @@ -15,7 +18,7 @@ Inspired by [Oh My Pi's pi-natives](https://github.com/can1357/oh-my-pi), adapte ## Prerequisites - **Rust** (stable, 1.70+): https://rustup.rs -- **Node.js** (20.6+) +- **Node.js** (22.0.0+) ## Build @@ -41,6 +44,34 @@ npm run test:native ## Modules +### ast + +Structural code search via ast-grep. Provides pattern-based code matching that understands language syntax, enabling searches like "find all functions that return a Promise" rather than raw regex. + +### clipboard + +Native clipboard access for reading and writing system clipboard contents. + +### diff + +Fuzzy text matching and unified diff generation. Provides efficient comparison of text content with configurable matching thresholds. + +### fd + +Fuzzy file path discovery. Locates files by partial name matching across the project tree. + +### fs_cache + +Filesystem caching layer. Caches file metadata and contents to reduce redundant I/O during repeated operations. + +### git + +Libgit2-backed git read operations. Provides fast, direct access to repository status, diffs, blame, and log without shelling out to the `git` CLI. + +### glob / glob_util + +Gitignore-aware file discovery. Walks directory trees while respecting `.gitignore` rules, returning matching paths for a given glob pattern. + ### grep Ripgrep-backed regex search using the `grep-regex`, `grep-searcher`, and `grep-matcher` crates. @@ -72,6 +103,54 @@ const contentResult = searchContent(Buffer.from(fileContent), { }); ``` +### gsd_parser + +GSD file parsing and frontmatter extraction. Reads `.gsd` files and extracts structured metadata from YAML frontmatter blocks. + +### highlight + +Syntect-based syntax highlighting. Tokenizes source code and produces highlighted output for terminal or HTML rendering. + +### html + +HTML-to-Markdown conversion. Transforms HTML content into clean Markdown, useful for importing web content into GSD notes and documents. + +### image + +Image decoding, encoding, and resizing. Supports common formats (PNG, JPEG, WebP) and provides efficient thumbnail generation. + +### json_parse + +JSON parsing utilities. Provides streaming and fault-tolerant JSON parsing for large or partially valid payloads. + +### ps + +Cross-platform process tree management. Lists, inspects, and terminates process trees by PID, used for managing spawned subprocesses. + +### stream_process + +Streaming process I/O. Spawns child processes with non-blocking, streamed access to stdout and stderr for real-time output handling. + +### task + +Task-related native operations. Provides low-level primitives for task scheduling and execution within the native layer. + +### text + +ANSI-aware text measurement and wrapping. Correctly measures visible width of strings containing ANSI escape codes and wraps text to terminal column widths. + +### truncate + +Text truncation utilities. Truncates strings to a target length while preserving ANSI sequences and respecting grapheme boundaries. + +### ttsr + +Tool-triggered system rules. Evaluates and applies system-level rules that activate in response to specific tool invocations. + +### xxhash + +xxHash hashing. Provides fast, non-cryptographic hashing via the xxHash algorithm for content deduplication and cache keying. + ## Adding New Modules 1. Create a new crate in `native/crates/` (pure Rust library) diff --git a/native/npm/darwin-arm64/package.json b/native/npm/darwin-arm64/package.json index ac07f8a64..096c57f16 100644 --- a/native/npm/darwin-arm64/package.json +++ b/native/npm/darwin-arm64/package.json @@ -1,6 +1,6 @@ { "name": "@gsd-build/engine-darwin-arm64", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD native engine binary for macOS ARM64", "os": [ "darwin" diff --git a/native/npm/darwin-x64/package.json b/native/npm/darwin-x64/package.json index ef645779c..09464a640 100644 --- a/native/npm/darwin-x64/package.json +++ b/native/npm/darwin-x64/package.json @@ -1,6 +1,6 @@ { "name": "@gsd-build/engine-darwin-x64", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD native engine binary for macOS Intel", "os": [ "darwin" diff --git a/native/npm/linux-arm64-gnu/package.json b/native/npm/linux-arm64-gnu/package.json index dea68fe25..67c22f543 100644 --- a/native/npm/linux-arm64-gnu/package.json +++ b/native/npm/linux-arm64-gnu/package.json @@ -1,6 +1,6 @@ { "name": "@gsd-build/engine-linux-arm64-gnu", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD native engine binary for Linux ARM64 (glibc)", "os": [ "linux" diff --git a/native/npm/linux-x64-gnu/package.json b/native/npm/linux-x64-gnu/package.json index 043a52165..be462588b 100644 --- a/native/npm/linux-x64-gnu/package.json +++ b/native/npm/linux-x64-gnu/package.json @@ -1,6 +1,6 @@ { "name": "@gsd-build/engine-linux-x64-gnu", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD native engine binary for Linux x64 (glibc)", "os": [ "linux" diff --git a/native/npm/win32-x64-msvc/package.json b/native/npm/win32-x64-msvc/package.json index 4f56ea3c7..373a6b2c9 100644 --- a/native/npm/win32-x64-msvc/package.json +++ b/native/npm/win32-x64-msvc/package.json @@ -1,6 +1,6 @@ { "name": "@gsd-build/engine-win32-x64-msvc", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD native engine binary for Windows x64 (MSVC)", "os": [ "win32" diff --git a/package-lock.json b/package-lock.json index 741ca0b5b..cae86f699 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "gsd-pi", - "version": "2.56.0", + "version": "2.66.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "gsd-pi", - "version": "2.56.0", + "version": "2.66.1", "hasInstallScript": true, "license": "MIT", "workspaces": [ @@ -846,13 +846,13 @@ } }, "node_modules/@aws-sdk/xml-builder": { - "version": "3.972.10", - "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.10.tgz", - "integrity": "sha512-OnejAIVD+CxzyAUrVic7lG+3QRltyja9LoNqCE/1YVs8ichoTbJlVSaZ9iSMcnHLyzrSNtvaOGjSDRP+d/ouFA==", + "version": "3.972.17", + "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.17.tgz", + "integrity": "sha512-Ra7hjqAZf1OXRRMueB13qex7mFJRDK/pgCvdSFemXBT8KCGnQDPoKzHY1SjN+TjJVmnpSF14W5tJ1vDamFu+Gg==", "license": "Apache-2.0", "dependencies": { - "@smithy/types": "^4.13.0", - "fast-xml-parser": "5.4.1", + "@smithy/types": "^4.14.0", + "fast-xml-parser": "5.5.8", "tslib": "^2.6.2" }, "engines": { @@ -1245,9 +1245,9 @@ } }, "node_modules/@discordjs/builders": { - "version": "1.14.0", - "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-1.14.0.tgz", - "integrity": "sha512-7pVKxVWkeLUtrTo9nTYkjRcJk0Hlms6lYervXAD7E7+K5lil9ms2JrEB1TalMiHvQMh7h1HJZ4fCJa0/vHpl4w==", + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/@discordjs/builders/-/builders-1.14.1.tgz", + "integrity": "sha512-gSKkhXLqs96TCzk66VZuHHl8z2bQMJFGwrXC0f33ngK+FLNau4hU1PYny3DNJfNdSH+gVMzE85/d5FQ2BpcNwQ==", "license": "Apache-2.0", "dependencies": { "@discordjs/formatters": "^0.6.2", @@ -2002,9 +2002,9 @@ "link": true }, "node_modules/@hono/node-server": { - "version": "1.19.11", - "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.11.tgz", - "integrity": "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g==", + "version": "1.19.13", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.13.tgz", + "integrity": "sha512-TsQLe4i2gvoTtrHje625ngThGBySOgSK3Xo2XRYOdqGN1teR8+I7vchQC46uLJi8OF62YTYA3AhSpumtkhsaKQ==", "license": "MIT", "engines": { "node": ">=18.14.1" @@ -3694,9 +3694,9 @@ } }, "node_modules/@smithy/types": { - "version": "4.13.1", - "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.13.1.tgz", - "integrity": "sha512-787F3yzE2UiJIQ+wYW1CVg2odHjmaWLGksnKQHUrK/lYZSEcy1msuLVvxaR/sI2/aDe9U+TBuLsXnr3vod1g0g==", + "version": "4.14.0", + "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.14.0.tgz", + "integrity": "sha512-OWgntFLW88kx2qvf/c/67Vno1yuXm/f9M7QFAtVkkO29IJXGBIg0ycEaBTH0kvCtwmvZxRujrgP5a86RvsXJAQ==", "license": "Apache-2.0", "dependencies": { "tslib": "^2.6.2" @@ -4616,9 +4616,9 @@ } }, "node_modules/basic-ftp": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.0.tgz", - "integrity": "sha512-VoMINM2rqJwJgfdHq6RiUudKt2BV+FY5ZFezP/ypmwayk68+NzzAQy4XXLlqsGD4MCzq3DrmNFD/uUmBJuGoXw==", + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.1.tgz", + "integrity": "sha512-0yaL8JdxTknKDILitVpfYfV2Ob6yb3udX/hK97M7I3jOeznBNxQPtVvTUtnhUkyHlxFWyr5Lvknmgzoc7jf+1Q==", "license": "MIT", "engines": { "node": ">=10.0.0" @@ -4679,9 +4679,9 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "5.0.4", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz", - "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==", + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", + "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", "license": "MIT", "dependencies": { "balanced-match": "^4.0.2" @@ -5216,24 +5216,24 @@ ] }, "node_modules/discord.js": { - "version": "14.25.1", - "resolved": "https://registry.npmjs.org/discord.js/-/discord.js-14.25.1.tgz", - "integrity": "sha512-2l0gsPOLPs5t6GFZfQZKnL1OJNYFcuC/ETWsW4VtKVD/tg4ICa9x+jb9bkPffkMdRpRpuUaO/fKkHCBeiCKh8g==", + "version": "14.26.2", + "resolved": "https://registry.npmjs.org/discord.js/-/discord.js-14.26.2.tgz", + "integrity": "sha512-feShi+gULJ6R2MAA4/KkCFnkJcuVrROJrKk4czplzq8gE1oqhqgOy9K0Scu44B8oGeWKe04egquzf+ia6VtXAw==", "license": "Apache-2.0", "dependencies": { - "@discordjs/builders": "^1.13.0", + "@discordjs/builders": "^1.14.1", "@discordjs/collection": "1.5.3", "@discordjs/formatters": "^0.6.2", - "@discordjs/rest": "^2.6.0", + "@discordjs/rest": "^2.6.1", "@discordjs/util": "^1.2.0", "@discordjs/ws": "^1.2.3", "@sapphire/snowflake": "3.5.3", - "discord-api-types": "^0.38.33", + "discord-api-types": "^0.38.40", "fast-deep-equal": "3.1.3", "lodash.snakecase": "4.1.1", - "magic-bytes.js": "^1.10.0", + "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", - "undici": "6.21.3" + "undici": "6.24.1" }, "engines": { "node": ">=18" @@ -5243,9 +5243,9 @@ } }, "node_modules/discord.js/node_modules/undici": { - "version": "6.21.3", - "resolved": "https://registry.npmjs.org/undici/-/undici-6.21.3.tgz", - "integrity": "sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==", + "version": "6.24.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.1.tgz", + "integrity": "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA==", "license": "MIT", "engines": { "node": ">=18.17" @@ -5281,9 +5281,9 @@ "license": "MIT" }, "node_modules/electron": { - "version": "41.0.3", - "resolved": "https://registry.npmjs.org/electron/-/electron-41.0.3.tgz", - "integrity": "sha512-IDjx8liW1q+r7+MOip5W1Eo1eMwJzVObmYrd9yz2dPCkS7XlgLq3qPVMR80TpiROFp73iY30kTzMdpA6fEVs3A==", + "version": "41.2.0", + "resolved": "https://registry.npmjs.org/electron/-/electron-41.2.0.tgz", + "integrity": "sha512-0OKLiymqfV0WK68RBXqAm3Myad2TpI5wwxLCBEUcH5Nugo3YfSk7p1Js/AL9266qTz5xZioUnxt9hG8FFwax0g==", "dev": true, "hasInstallScript": true, "license": "MIT", @@ -5703,9 +5703,9 @@ "license": "BSD-3-Clause" }, "node_modules/fast-xml-builder": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.2.tgz", - "integrity": "sha512-NJAmiuVaJEjVa7TjLZKlYd7RqmzOC91EtPFXHvlTcqBVo50Qh7XV5IwvXi1c7NRz2Q/majGX9YLcwJtWgHjtkA==", + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.4.tgz", + "integrity": "sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg==", "funding": [ { "type": "github", @@ -5718,9 +5718,9 @@ } }, "node_modules/fast-xml-parser": { - "version": "5.4.1", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.4.1.tgz", - "integrity": "sha512-BQ30U1mKkvXQXXkAGcuyUA/GA26oEB7NzOtsxCDtyu62sjGw5QraKFhx2Em3WQNjPw9PG6MQ9yuIIgkSDfGu5A==", + "version": "5.5.8", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.5.8.tgz", + "integrity": "sha512-Z7Fh2nVQSb2d+poDViM063ix2ZGt9jmY1nWhPfHBOK2Hgnb/OW3P4Et3P/81SEej0J7QbWtJqxO05h8QYfK7LQ==", "funding": [ { "type": "github", @@ -5729,8 +5729,9 @@ ], "license": "MIT", "dependencies": { - "fast-xml-builder": "^1.0.0", - "strnum": "^2.1.2" + "fast-xml-builder": "^1.1.4", + "path-expression-matcher": "^1.2.0", + "strnum": "^2.2.0" }, "bin": { "fxparser": "src/cli/cli.js" @@ -5788,9 +5789,9 @@ } }, "node_modules/file-type": { - "version": "21.3.1", - "resolved": "https://registry.npmjs.org/file-type/-/file-type-21.3.1.tgz", - "integrity": "sha512-SrzXX46I/zsRDjTb82eucsGg0ODq2NpGDp4HcsFKApPy8P8vACjpJRDoGGMfEzhFC0ry61ajd7f72J3603anBA==", + "version": "21.3.4", + "resolved": "https://registry.npmjs.org/file-type/-/file-type-21.3.4.tgz", + "integrity": "sha512-Ievi/yy8DS3ygGvT47PjSfdFoX+2isQueoYP1cntFW1JLYAuS4GD7NUPGg4zv2iZfV52uDyk5w5Z0TdpRS6Q1g==", "license": "MIT", "dependencies": { "@tokenizer/inflate": "^0.4.1", @@ -6262,9 +6263,9 @@ } }, "node_modules/hono": { - "version": "4.12.8", - "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.8.tgz", - "integrity": "sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A==", + "version": "4.12.12", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.12.tgz", + "integrity": "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==", "license": "MIT", "engines": { "node": ">=16.9.0" @@ -6923,9 +6924,9 @@ } }, "node_modules/lodash": { - "version": "4.17.23", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz", - "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==", + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz", + "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==", "license": "MIT" }, "node_modules/lodash.snakecase": { @@ -7389,9 +7390,9 @@ } }, "node_modules/path-expression-matcher": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.1.3.tgz", - "integrity": "sha512-qdVgY8KXmVdJZRSS1JdEPOKPdTiEK/pi0RkcT2sw1RhXxohdujUlJFPuS1TSkevZ9vzd3ZlL7ULl1MHGTApKzQ==", + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.4.0.tgz", + "integrity": "sha512-s4DQMxIdhj3jLFWd9LxHOplj4p9yQ4ffMGowFf3cpEgrrJjEhN0V5nxw4Ye1EViAGDoL4/1AeO6qHpqYPOzE4Q==", "funding": [ { "type": "github", @@ -7429,9 +7430,9 @@ } }, "node_modules/path-to-regexp": { - "version": "8.3.0", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz", - "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==", + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", "license": "MIT", "funding": { "type": "opencollective", @@ -7451,9 +7452,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz", + "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "license": "MIT", "engines": { "node": ">=12" @@ -8301,9 +8302,9 @@ } }, "node_modules/strnum": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.2.0.tgz", - "integrity": "sha512-Y7Bj8XyJxnPAORMZj/xltsfo55uOiyHcU2tnAVzHUnSJR/KsEX+9RoDeXEnsXtl/CX4fAcrt64gZ13aGaWPeBg==", + "version": "2.2.3", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.2.3.tgz", + "integrity": "sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg==", "funding": [ { "type": "github", @@ -8603,9 +8604,9 @@ } }, "node_modules/vite": { - "version": "7.3.1", - "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz", - "integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==", + "version": "7.3.2", + "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.2.tgz", + "integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==", "dev": true, "license": "MIT", "peer": true, @@ -9299,9 +9300,9 @@ "license": "ISC" }, "node_modules/yaml": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz", - "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==", + "version": "2.8.3", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", + "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", "license": "ISC", "bin": { "yaml": "bin.mjs" @@ -9534,7 +9535,7 @@ }, "packages/pi-coding-agent": { "name": "@gsd/pi-coding-agent", - "version": "2.56.0", + "version": "2.66.1", "dependencies": { "@mariozechner/jiti": "^2.6.2", "@silvia-odwyer/photon-node": "^0.3.4", diff --git a/package.json b/package.json index c7f83dad5..71c908b81 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gsd-pi", - "version": "2.58.0", + "version": "2.71.0", "description": "GSD — Get Shit Done coding agent", "license": "MIT", "repository": { @@ -46,30 +46,32 @@ "build:pi-agent-core": "npm run build -w @gsd/pi-agent-core", "build:pi-coding-agent": "npm run build -w @gsd/pi-coding-agent", "build:native-pkg": "npm run build -w @gsd/native", + "build:rpc-client": "npm run build -w @gsd-build/rpc-client", "build:pi": "npm run build:native-pkg && npm run build:pi-tui && npm run build:pi-ai && npm run build:pi-agent-core && npm run build:pi-coding-agent", - "build": "npm run build:pi && tsc && npm run copy-resources && npm run copy-themes && npm run copy-export-html && node scripts/build-web-if-stale.cjs", + "build:mcp-server": "npm run build -w @gsd-build/mcp-server", + "build": "npm run build:pi && npm run build:rpc-client && npm run build:mcp-server && tsc && npm run copy-resources && npm run copy-themes && npm run copy-export-html && node scripts/build-web-if-stale.cjs", "stage:web-host": "node scripts/stage-web-standalone.cjs", "build:web-host": "npm --prefix web run build && npm run stage:web-host", "copy-resources": "node scripts/copy-resources.cjs", "copy-themes": "node scripts/copy-themes.cjs", "copy-export-html": "node scripts/copy-export-html.cjs", "test:compile": "node scripts/compile-tests.mjs", - "test:unit": "npm run test:compile && node --import ./scripts/dist-test-resolve.mjs --experimental-test-isolation=process --test-reporter=./scripts/test-reporter-compact.mjs --test 'dist-test/src/tests/*.test.js' 'dist-test/src/resources/extensions/gsd/tests/*.test.js' 'dist-test/src/resources/extensions/gsd/tests/*.test.mjs' 'dist-test/src/resources/extensions/shared/tests/*.test.js' 'dist-test/src/resources/extensions/claude-code-cli/tests/*.test.js' 'dist-test/src/resources/extensions/github-sync/tests/*.test.js' 'dist-test/src/resources/extensions/universal-config/tests/*.test.js' 'dist-test/src/resources/extensions/voice/tests/*.test.js'", - "test:packages": "node --test packages/pi-coding-agent/dist/core/*.test.js", - "test:marketplace": "GSD_TEST_CLONE_MARKETPLACES=1 node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/resources/extensions/gsd/tests/claude-import-tui.test.ts src/resources/extensions/gsd/tests/plugin-importer-live.test.ts src/tests/marketplace-discovery.test.ts", - "test:coverage": "c8 --reporter=text --reporter=lcov --exclude='src/resources/extensions/gsd/tests/**' --exclude='src/tests/**' --exclude='scripts/**' --exclude='native/**' --exclude='node_modules/**' --check-coverage --statements=40 --lines=40 --branches=20 --functions=20 node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --experimental-test-isolation=process --test src/resources/extensions/gsd/tests/*.test.ts src/resources/extensions/gsd/tests/*.test.mjs src/tests/*.test.ts src/resources/extensions/shared/tests/*.test.ts", - "test:integration": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test 'src/tests/integration/*.test.ts' 'src/resources/extensions/gsd/tests/integration/*.test.ts' 'src/resources/extensions/async-jobs/*.test.ts' 'src/resources/extensions/browser-tools/tests/*.test.mjs'", + "test:unit": "npm run test:compile && node --import ./scripts/dist-test-resolve.mjs --experimental-test-isolation=process --test-reporter=./scripts/test-reporter-compact.mjs --test \"dist-test/src/tests/*.test.js\" \"dist-test/src/resources/extensions/gsd/tests/*.test.js\" \"dist-test/src/resources/extensions/gsd/tests/*.test.mjs\" \"dist-test/src/resources/extensions/shared/tests/*.test.js\" \"dist-test/src/resources/extensions/claude-code-cli/tests/*.test.js\" \"dist-test/src/resources/extensions/github-sync/tests/*.test.js\" \"dist-test/src/resources/extensions/universal-config/tests/*.test.js\" \"dist-test/src/resources/extensions/voice/tests/*.test.js\" \"dist-test/src/resources/extensions/mcp-client/tests/*.test.js\"", + "test:packages": "node --test packages/pi-coding-agent/dist/core/*.test.js packages/pi-coding-agent/dist/core/tools/spawn-shell-windows.test.js", + "test:marketplace": "node scripts/with-env.mjs GSD_TEST_CLONE_MARKETPLACES=1 -- node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/resources/extensions/gsd/tests/claude-import-tui.test.ts src/resources/extensions/gsd/tests/plugin-importer-live.test.ts src/tests/marketplace-discovery.test.ts", + "test:coverage": "c8 --reporter=text --reporter=lcov --exclude=\"src/resources/extensions/gsd/tests/**\" --exclude=\"src/tests/**\" --exclude=\"scripts/**\" --exclude=\"native/**\" --exclude=\"node_modules/**\" --check-coverage --statements=40 --lines=40 --branches=20 --functions=20 node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --experimental-test-isolation=process --test src/resources/extensions/gsd/tests/*.test.ts src/resources/extensions/gsd/tests/*.test.mjs src/tests/*.test.ts src/resources/extensions/shared/tests/*.test.ts", + "test:integration": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test \"src/tests/integration/*.test.ts\" \"src/resources/extensions/gsd/tests/integration/*.test.ts\" \"src/resources/extensions/async-jobs/*.test.ts\" \"src/resources/extensions/browser-tools/tests/*.test.mjs\"", "pretest": "npm run typecheck:extensions", "test": "npm run test:unit && npm run test:integration", "test:smoke": "node --experimental-strip-types tests/smoke/run.ts", "test:fixtures": "node --experimental-strip-types tests/fixtures/run.ts", - "test:fixtures:record": "GSD_FIXTURE_MODE=record node --experimental-strip-types tests/fixtures/record.ts", - "test:live": "GSD_LIVE_TESTS=1 node --experimental-strip-types tests/live/run.ts", + "test:fixtures:record": "node scripts/with-env.mjs GSD_FIXTURE_MODE=record -- node --experimental-strip-types tests/fixtures/record.ts", + "test:live": "node scripts/with-env.mjs GSD_LIVE_TESTS=1 -- node --experimental-strip-types tests/live/run.ts", "test:browser-tools": "node --test src/resources/extensions/browser-tools/tests/browser-tools-unit.test.cjs src/resources/extensions/browser-tools/tests/browser-tools-integration.test.mjs", "test:native": "node --test packages/native/src/__tests__/grep.test.mjs", "test:secret-scan": "node --import ./src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/tests/secret-scan.test.ts", - "secret-scan": "bash scripts/secret-scan.sh", - "secret-scan:install-hook": "bash scripts/install-hooks.sh", + "secret-scan": "node scripts/secret-scan.mjs", + "secret-scan:install-hook": "node scripts/install-hooks.mjs", "build:native": "node native/scripts/build.js", "build:native:dev": "node native/scripts/build.js --dev", "dev": "node scripts/dev.js", @@ -90,7 +92,7 @@ "release:update-changelog": "node scripts/update-changelog.mjs", "docker:build-runtime": "docker build --target runtime -t ghcr.io/gsd-build/gsd-pi .", "docker:build-builder": "docker build --target builder -t ghcr.io/gsd-build/gsd-ci-builder .", - "prepublishOnly": "npm run sync-pkg-version && npm run sync-platform-versions && ([ \"$CI\" = 'true' ] || git diff --exit-code || (echo 'ERROR: version sync changed files — commit them before publishing' && exit 1)) && npm run build && npm run typecheck:extensions && npm run validate-pack", + "prepublishOnly": "npm run sync-pkg-version && npm run sync-platform-versions && node scripts/prepublish-check.mjs && npm run build && npm run typecheck:extensions && npm run validate-pack", "test:live-regression": "node --experimental-strip-types tests/live-regression/run.ts" }, "dependencies": { diff --git a/packages/daemon/src/orchestrator.ts b/packages/daemon/src/orchestrator.ts index 678874cec..fe2998d8f 100644 --- a/packages/daemon/src/orchestrator.ts +++ b/packages/daemon/src/orchestrator.ts @@ -12,9 +12,6 @@ */ import { z } from 'zod'; -import { readFileSync, writeFileSync, chmodSync } from 'node:fs'; -import { join } from 'node:path'; -import { homedir } from 'node:os'; import type Anthropic from '@anthropic-ai/sdk'; import type { MessageParam, @@ -30,90 +27,18 @@ import type { ProjectInfo, ManagedSession } from './types.js'; import type { Logger } from './logger.js'; // --------------------------------------------------------------------------- -// OAuth token resolution — reads GSD's auth.json, refreshes if expired +// API key resolution — requires ANTHROPIC_API_KEY env var +// Anthropic OAuth removed per TOS compliance (see docs/user-docs/claude-code-auth-compliance.md) // --------------------------------------------------------------------------- -interface OAuthCredentials { - type: 'oauth'; - refresh: string; - access: string; - expires: number; -} - -const TOKEN_URL = 'https://platform.claude.com/v1/oauth/token'; -const CLIENT_ID = atob('OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl'); - -/** - * Read the Anthropic OAuth access token from GSD's auth.json. - * If expired, refresh it and write the new credentials back. - * Falls back to ANTHROPIC_API_KEY env var if no OAuth credential exists. - */ -async function resolveAnthropicApiKey(logger?: Logger): Promise { - // Try env var first (explicit override) - if (process.env.ANTHROPIC_API_KEY) { - return process.env.ANTHROPIC_API_KEY; - } - - const authPath = join(homedir(), '.gsd', 'agent', 'auth.json'); - let authData: Record; - try { - authData = JSON.parse(readFileSync(authPath, 'utf-8')); - } catch { +function resolveAnthropicApiKey(): string { + const apiKey = process.env.ANTHROPIC_API_KEY; + if (!apiKey) { throw new Error( - 'No Anthropic auth found. Run `gsd login` to authenticate, or set ANTHROPIC_API_KEY.', + 'ANTHROPIC_API_KEY is required. Set it in your environment or run `gsd config`.', ); } - - const cred = authData.anthropic as OAuthCredentials | undefined; - if (!cred || cred.type !== 'oauth' || !cred.access) { - throw new Error( - 'No Anthropic OAuth credential in auth.json. Run `gsd login` to authenticate.', - ); - } - - // If token is still valid, use it - if (Date.now() < cred.expires) { - return cred.access; - } - - // Token expired — refresh it - logger?.info('orchestrator: refreshing Anthropic OAuth token'); - const response = await fetch(TOKEN_URL, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - grant_type: 'refresh_token', - client_id: CLIENT_ID, - refresh_token: cred.refresh, - }), - signal: AbortSignal.timeout(30_000), - }); - - if (!response.ok) { - const error = await response.text(); - throw new Error(`Anthropic token refresh failed: ${error}`); - } - - const data = (await response.json()) as { - access_token: string; - refresh_token: string; - expires_in: number; - }; - - const newCred: OAuthCredentials = { - type: 'oauth', - refresh: data.refresh_token, - access: data.access_token, - expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, - }; - - // Write back to auth.json - authData.anthropic = newCred; - writeFileSync(authPath, JSON.stringify(authData, null, 2), 'utf-8'); - chmodSync(authPath, 0o600); - logger?.info('orchestrator: Anthropic OAuth token refreshed'); - - return newCred.access; + return apiKey; } // --------------------------------------------------------------------------- @@ -254,11 +179,11 @@ export class Orchestrator { /** * Lazily initialise the Anthropic client. Dynamic import handles K007 module resolution. - * Resolves auth from GSD's OAuth credentials (auth.json), refreshing if needed. + * Requires ANTHROPIC_API_KEY environment variable. */ private async getClient(): Promise { if (this.client) return this.client; - const apiKey = await resolveAnthropicApiKey(this.deps.logger); + const apiKey = resolveAnthropicApiKey(); const { default: AnthropicSDK } = await import('@anthropic-ai/sdk'); this.client = new AnthropicSDK({ apiKey }); return this.client; diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md index fd4783ea9..642657dd7 100644 --- a/packages/mcp-server/README.md +++ b/packages/mcp-server/README.md @@ -4,6 +4,12 @@ MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other M Start GSD auto-mode sessions, poll progress, resolve blockers, and retrieve results — all through the [Model Context Protocol](https://modelcontextprotocol.io/). +This package now exposes two tool surfaces: + +- session/read tools for starting and inspecting GSD sessions +- MCP-native interactive tools for structured user input +- headless-safe workflow tools for planning, completion, validation, reassessment, metadata persistence, and journal reads + ## Installation ```bash @@ -69,6 +75,57 @@ Add to `.cursor/mcp.json`: ## Tools +### Workflow tools + +The workflow MCP surface includes: + +- `gsd_decision_save` +- `gsd_save_decision` +- `gsd_requirement_update` +- `gsd_update_requirement` +- `gsd_requirement_save` +- `gsd_save_requirement` +- `gsd_milestone_generate_id` +- `gsd_generate_milestone_id` +- `gsd_plan_milestone` +- `gsd_plan_slice` +- `gsd_plan_task` +- `gsd_task_plan` +- `gsd_replan_slice` +- `gsd_slice_replan` +- `gsd_task_complete` +- `gsd_complete_task` +- `gsd_slice_complete` +- `gsd_complete_slice` +- `gsd_skip_slice` +- `gsd_validate_milestone` +- `gsd_milestone_validate` +- `gsd_complete_milestone` +- `gsd_milestone_complete` +- `gsd_reassess_roadmap` +- `gsd_roadmap_reassess` +- `gsd_save_gate_result` +- `gsd_summary_save` +- `gsd_milestone_status` +- `gsd_journal_query` + +These tools use the same GSD workflow handlers as the native in-process tool path wherever a shared handler exists. + +### Interactive tools + +The packaged server now exposes `ask_user_questions` through MCP form elicitation. This keeps the existing GSD answer payload shape while allowing Claude Code CLI and other elicitation-capable clients to surface structured user choices. + +`secure_env_collect` is still not exposed by this package. That path needs MCP URL elicitation or an equivalent secure bridge because secrets should not flow through form elicitation. + +Current support boundary: + +- when running inside the GSD monorepo checkout, the MCP server auto-discovers the shared workflow executor module +- outside the monorepo, set `GSD_WORKFLOW_EXECUTORS_MODULE` to an importable `workflow-tool-executors` module path if you want the mutation tools enabled +- `ask_user_questions` requires an MCP client that supports form elicitation +- session/read tools do not depend on this bridge + +If the executor bridge cannot be loaded, workflow mutation calls will fail with a precise configuration error instead of silently degrading. + ### `gsd_execute` Start a GSD auto-mode session for a project directory. @@ -175,6 +232,9 @@ Resolve a pending blocker in a session by sending a response to the blocked UI r | Variable | Description | |----------|-------------| | `GSD_CLI_PATH` | Absolute path to the GSD CLI binary. If not set, the server resolves `gsd` via `which`. | +| `GSD_WORKFLOW_EXECUTORS_MODULE` | Optional absolute path or `file:` URL for the shared GSD workflow executor module used by workflow mutation tools. | + +The server also hydrates supported model-provider and tool credentials from `~/.gsd/agent/auth.json` on startup. Keys saved through `/gsd config` or `/gsd keys` become available to the MCP server process automatically, and any explicitly-set environment variable still wins. ## Architecture diff --git a/packages/mcp-server/src/cli.ts b/packages/mcp-server/src/cli.ts index eb4252d5a..e9b64d794 100644 --- a/packages/mcp-server/src/cli.ts +++ b/packages/mcp-server/src/cli.ts @@ -1,5 +1,3 @@ -#!/usr/bin/env node - /** * @gsd-build/mcp-server CLI — stdio transport entry point. * @@ -9,13 +7,17 @@ import { SessionManager } from './session-manager.js'; import { createMcpServer } from './server.js'; +import { loadStoredCredentialEnvKeys } from './tool-credentials.js'; const MCP_PKG = '@modelcontextprotocol/sdk'; async function main(): Promise { + loadStoredCredentialEnvKeys(); + const sessionManager = new SessionManager(); - // Create the configured MCP server with all 6 tools + // Create the configured MCP server with session, interactive, read-only, + // and workflow tools. const { server } = await createMcpServer(sessionManager); // Dynamic import for StdioServerTransport (same TS subpath workaround) diff --git a/packages/mcp-server/src/env-writer.test.ts b/packages/mcp-server/src/env-writer.test.ts new file mode 100644 index 000000000..5932d1cfb --- /dev/null +++ b/packages/mcp-server/src/env-writer.test.ts @@ -0,0 +1,280 @@ +// @gsd-build/mcp-server — Tests for env-writer utilities +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it, afterEach } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { + checkExistingEnvKeys, + detectDestination, + writeEnvKey, + applySecrets, + isSafeEnvVarKey, + isSupportedDeploymentEnvironment, + shellEscapeSingle, +} from './env-writer.js'; + +function makeTempDir(prefix: string): string { + return mkdtempSync(join(tmpdir(), `${prefix}-`)); +} + +// --------------------------------------------------------------------------- +// checkExistingEnvKeys +// --------------------------------------------------------------------------- + +describe('checkExistingEnvKeys', () => { + it('finds key in .env file', async () => { + const tmp = makeTempDir('env-check'); + try { + const envPath = join(tmp, '.env'); + writeFileSync(envPath, 'API_KEY=secret123\nOTHER=val\n'); + const result = await checkExistingEnvKeys(['API_KEY'], envPath); + assert.deepStrictEqual(result, ['API_KEY']); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('finds key in process.env', async () => { + const tmp = makeTempDir('env-check'); + const saved = process.env.GSD_MCP_TEST_KEY_1; + try { + process.env.GSD_MCP_TEST_KEY_1 = 'some-value'; + const envPath = join(tmp, '.env'); + const result = await checkExistingEnvKeys(['GSD_MCP_TEST_KEY_1'], envPath); + assert.deepStrictEqual(result, ['GSD_MCP_TEST_KEY_1']); + } finally { + delete process.env.GSD_MCP_TEST_KEY_1; + if (saved !== undefined) process.env.GSD_MCP_TEST_KEY_1 = saved; + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('returns empty for missing keys', async () => { + const tmp = makeTempDir('env-check'); + try { + const envPath = join(tmp, '.env'); + writeFileSync(envPath, 'OTHER=val\n'); + delete process.env.DEFINITELY_NOT_SET_MCP_XYZ; + const result = await checkExistingEnvKeys(['DEFINITELY_NOT_SET_MCP_XYZ'], envPath); + assert.deepStrictEqual(result, []); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('handles missing .env file gracefully', async () => { + const tmp = makeTempDir('env-check'); + try { + const envPath = join(tmp, 'nonexistent.env'); + delete process.env.DEFINITELY_NOT_SET_MCP_XYZ; + const result = await checkExistingEnvKeys(['DEFINITELY_NOT_SET_MCP_XYZ'], envPath); + assert.deepStrictEqual(result, []); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// --------------------------------------------------------------------------- +// detectDestination +// --------------------------------------------------------------------------- + +describe('detectDestination', () => { + it('returns vercel when vercel.json exists', () => { + const tmp = makeTempDir('dest'); + try { + writeFileSync(join(tmp, 'vercel.json'), '{}'); + assert.equal(detectDestination(tmp), 'vercel'); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('returns convex when convex/ dir exists', () => { + const tmp = makeTempDir('dest'); + try { + mkdirSync(join(tmp, 'convex')); + assert.equal(detectDestination(tmp), 'convex'); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('returns dotenv when neither exists', () => { + const tmp = makeTempDir('dest'); + try { + assert.equal(detectDestination(tmp), 'dotenv'); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('vercel takes priority over convex', () => { + const tmp = makeTempDir('dest'); + try { + writeFileSync(join(tmp, 'vercel.json'), '{}'); + mkdirSync(join(tmp, 'convex')); + assert.equal(detectDestination(tmp), 'vercel'); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// --------------------------------------------------------------------------- +// writeEnvKey +// --------------------------------------------------------------------------- + +describe('writeEnvKey', () => { + it('creates .env file with new key', async () => { + const tmp = makeTempDir('write'); + try { + const envPath = join(tmp, '.env'); + await writeEnvKey(envPath, 'NEW_KEY', 'new-value'); + const content = readFileSync(envPath, 'utf8'); + assert.ok(content.includes('NEW_KEY=new-value')); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('updates existing key in-place', async () => { + const tmp = makeTempDir('write'); + try { + const envPath = join(tmp, '.env'); + writeFileSync(envPath, 'EXISTING=old\nOTHER=keep\n'); + await writeEnvKey(envPath, 'EXISTING', 'new'); + const content = readFileSync(envPath, 'utf8'); + assert.ok(content.includes('EXISTING=new')); + assert.ok(content.includes('OTHER=keep')); + assert.ok(!content.includes('old')); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('escapes newlines in values', async () => { + const tmp = makeTempDir('write'); + try { + const envPath = join(tmp, '.env'); + await writeEnvKey(envPath, 'MULTI', 'line1\nline2'); + const content = readFileSync(envPath, 'utf8'); + assert.ok(content.includes('MULTI=line1\\nline2')); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('rejects non-string values', async () => { + const tmp = makeTempDir('write'); + try { + const envPath = join(tmp, '.env'); + await assert.rejects( + () => writeEnvKey(envPath, 'KEY', undefined as unknown as string), + /expects a string value/, + ); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// --------------------------------------------------------------------------- +// applySecrets (dotenv) +// --------------------------------------------------------------------------- + +describe('applySecrets', () => { + const savedKeys: Record = {}; + + afterEach(() => { + for (const [k, v] of Object.entries(savedKeys)) { + if (v === undefined) delete process.env[k]; + else process.env[k] = v; + } + }); + + it('writes keys to .env and hydrates process.env', async () => { + const tmp = makeTempDir('apply'); + const envPath = join(tmp, '.env'); + savedKeys.GSD_APPLY_TEST_A = process.env.GSD_APPLY_TEST_A; + try { + const { applied, errors } = await applySecrets( + [{ key: 'GSD_APPLY_TEST_A', value: 'val-a' }], + 'dotenv', + { envFilePath: envPath }, + ); + assert.deepStrictEqual(applied, ['GSD_APPLY_TEST_A']); + assert.deepStrictEqual(errors, []); + assert.equal(process.env.GSD_APPLY_TEST_A, 'val-a'); + const content = readFileSync(envPath, 'utf8'); + assert.ok(content.includes('GSD_APPLY_TEST_A=val-a')); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('returns errors for invalid vercel environment', async () => { + const tmp = makeTempDir('apply'); + try { + const { applied, errors } = await applySecrets( + [{ key: 'KEY', value: 'val' }], + 'vercel', + { + envFilePath: join(tmp, '.env'), + environment: 'staging' as 'development', + execFn: async () => ({ code: 0, stderr: '' }), + }, + ); + assert.deepStrictEqual(applied, []); + assert.ok(errors[0]?.includes('unsupported')); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// --------------------------------------------------------------------------- +// Validation helpers +// --------------------------------------------------------------------------- + +describe('isSafeEnvVarKey', () => { + it('accepts valid keys', () => { + assert.ok(isSafeEnvVarKey('API_KEY')); + assert.ok(isSafeEnvVarKey('_PRIVATE')); + assert.ok(isSafeEnvVarKey('key123')); + }); + + it('rejects invalid keys', () => { + assert.ok(!isSafeEnvVarKey('123BAD')); + assert.ok(!isSafeEnvVarKey('has-dash')); + assert.ok(!isSafeEnvVarKey('has space')); + assert.ok(!isSafeEnvVarKey('')); + }); +}); + +describe('isSupportedDeploymentEnvironment', () => { + it('accepts valid environments', () => { + assert.ok(isSupportedDeploymentEnvironment('development')); + assert.ok(isSupportedDeploymentEnvironment('preview')); + assert.ok(isSupportedDeploymentEnvironment('production')); + }); + + it('rejects invalid environments', () => { + assert.ok(!isSupportedDeploymentEnvironment('staging')); + assert.ok(!isSupportedDeploymentEnvironment('test')); + }); +}); + +describe('shellEscapeSingle', () => { + it('wraps in single quotes', () => { + assert.equal(shellEscapeSingle('hello'), "'hello'"); + }); + + it('escapes embedded single quotes', () => { + assert.equal(shellEscapeSingle("it's"), "'it'\\''s'"); + }); +}); diff --git a/packages/mcp-server/src/env-writer.ts b/packages/mcp-server/src/env-writer.ts new file mode 100644 index 000000000..219496539 --- /dev/null +++ b/packages/mcp-server/src/env-writer.ts @@ -0,0 +1,183 @@ +// @gsd-build/mcp-server — Environment variable write utilities +// Copyright (c) 2026 Jeremy McSpadden +// +// Shared helpers for writing env vars to .env files, detecting project +// destinations, and checking existing keys. Used by secure_env_collect +// MCP tool. No TUI dependencies — pure filesystem + process.env operations. + +import { readFile, writeFile } from "node:fs/promises"; +import { existsSync, statSync } from "node:fs"; +import { resolve } from "node:path"; + +// --------------------------------------------------------------------------- +// checkExistingEnvKeys +// --------------------------------------------------------------------------- + +/** + * Check which keys already exist in a .env file or process.env. + * Returns the subset of `keys` that are already set. + */ +export async function checkExistingEnvKeys(keys: string[], envFilePath: string): Promise { + let fileContent = ""; + try { + fileContent = await readFile(envFilePath, "utf8"); + } catch { + // ENOENT or other read error — proceed with empty content + } + + const existing: string[] = []; + for (const key of keys) { + const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const regex = new RegExp(`^${escaped}\\s*=`, "m"); + if (regex.test(fileContent) || key in process.env) { + existing.push(key); + } + } + return existing; +} + +// --------------------------------------------------------------------------- +// detectDestination +// --------------------------------------------------------------------------- + +/** + * Detect the write destination based on project files in basePath. + * Priority: vercel.json → convex/ dir → fallback "dotenv". + */ +export function detectDestination(basePath: string): "dotenv" | "vercel" | "convex" { + if (existsSync(resolve(basePath, "vercel.json"))) { + return "vercel"; + } + const convexPath = resolve(basePath, "convex"); + try { + if (existsSync(convexPath) && statSync(convexPath).isDirectory()) { + return "convex"; + } + } catch { + // stat error — treat as not found + } + return "dotenv"; +} + +// --------------------------------------------------------------------------- +// writeEnvKey +// --------------------------------------------------------------------------- + +/** + * Write a single key=value pair to a .env file. + * Updates existing keys in-place, appends new ones at the end. + */ +export async function writeEnvKey(filePath: string, key: string, value: string): Promise { + if (typeof value !== "string") { + throw new TypeError(`writeEnvKey expects a string value for key "${key}", got ${typeof value}`); + } + let content = ""; + try { + content = await readFile(filePath, "utf8"); + } catch { + content = ""; + } + const escaped = value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, ""); + const line = `${key}=${escaped}`; + const regex = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*=.*$`, "m"); + if (regex.test(content)) { + content = content.replace(regex, line); + } else { + if (content.length > 0 && !content.endsWith("\n")) content += "\n"; + content += `${line}\n`; + } + await writeFile(filePath, content, "utf8"); +} + +// --------------------------------------------------------------------------- +// Validation helpers +// --------------------------------------------------------------------------- + +export function isSafeEnvVarKey(key: string): boolean { + return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key); +} + +export function isSupportedDeploymentEnvironment(env: string): boolean { + return env === "development" || env === "preview" || env === "production"; +} + +// --------------------------------------------------------------------------- +// Shell helpers (for vercel/convex CLI) +// --------------------------------------------------------------------------- + +export function shellEscapeSingle(value: string): string { + return `'${value.replace(/'/g, `'\\''`)}'`; +} + +// --------------------------------------------------------------------------- +// applySecrets +// --------------------------------------------------------------------------- + +interface ApplyResult { + applied: string[]; + errors: string[]; +} + +/** + * Apply collected secrets to the target destination. + * Dotenv writes are handled directly; vercel/convex shell out via execFn. + */ +export async function applySecrets( + provided: Array<{ key: string; value: string }>, + destination: "dotenv" | "vercel" | "convex", + opts: { + envFilePath: string; + environment?: string; + execFn?: (cmd: string, args: string[]) => Promise<{ code: number; stderr: string }>; + }, +): Promise { + const applied: string[] = []; + const errors: string[] = []; + + if (destination === "dotenv") { + for (const { key, value } of provided) { + try { + await writeEnvKey(opts.envFilePath, key, value); + applied.push(key); + // Hydrate process.env so the current session sees the new value + process.env[key] = value; + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + errors.push(`${key}: ${msg}`); + } + } + } + + if ((destination === "vercel" || destination === "convex") && opts.execFn) { + const env = opts.environment ?? "development"; + if (!isSupportedDeploymentEnvironment(env)) { + errors.push(`environment: unsupported target environment "${env}"`); + return { applied, errors }; + } + for (const { key, value } of provided) { + if (!isSafeEnvVarKey(key)) { + errors.push(`${key}: invalid environment variable name`); + continue; + } + const cmd = destination === "vercel" + ? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}` + : ""; + try { + const result = destination === "vercel" + ? await opts.execFn("sh", ["-c", cmd]) + : await opts.execFn("npx", ["convex", "env", "set", key, value]); + if (result.code !== 0) { + errors.push(`${key}: ${result.stderr.slice(0, 200)}`); + } else { + applied.push(key); + process.env[key] = value; + } + } catch (err: unknown) { + const msg = err instanceof Error ? err.message : String(err); + errors.push(`${key}: ${msg}`); + } + } + } + + return { applied, errors }; +} diff --git a/packages/mcp-server/src/import-candidates.test.ts b/packages/mcp-server/src/import-candidates.test.ts new file mode 100644 index 000000000..5b0171f3f --- /dev/null +++ b/packages/mcp-server/src/import-candidates.test.ts @@ -0,0 +1,48 @@ +// GSD-2 — Regression tests for importLocalModule candidate resolution (#3954) +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +import { _buildImportCandidates } from "./workflow-tools.js"; + +describe("_buildImportCandidates", () => { + it("includes dist/ fallback for src/ paths", () => { + const candidates = _buildImportCandidates("../../../src/resources/extensions/gsd/db-writer.js"); + assert.ok( + candidates.some((c) => c.includes("/dist/resources/extensions/gsd/db-writer.js")), + "should include dist/ swapped candidate", + ); + }); + + it("includes src/ fallback for dist/ paths", () => { + const candidates = _buildImportCandidates("../../../dist/resources/extensions/gsd/db-writer.js"); + assert.ok( + candidates.some((c) => c.includes("/src/resources/extensions/gsd/db-writer.js")), + "should include src/ swapped candidate", + ); + }); + + it("includes .ts variants for .js paths", () => { + const candidates = _buildImportCandidates("../../../src/resources/extensions/gsd/db-writer.js"); + assert.ok( + candidates.some((c) => c.endsWith("db-writer.ts") && c.includes("/src/")), + "should include .ts variant for original src/ path", + ); + assert.ok( + candidates.some((c) => c.endsWith("db-writer.ts") && c.includes("/dist/")), + "should include .ts variant for swapped dist/ path", + ); + }); + + it("returns original path first", () => { + const input = "../../../src/resources/extensions/gsd/db-writer.js"; + const candidates = _buildImportCandidates(input); + assert.equal(candidates[0], input, "first candidate should be the original path"); + }); + + it("handles paths without src/ or dist/ gracefully", () => { + const candidates = _buildImportCandidates("./local-module.js"); + assert.equal(candidates.length, 2, "should have original + .ts variant only"); + assert.equal(candidates[0], "./local-module.js"); + assert.equal(candidates[1], "./local-module.ts"); + }); +}); diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.ts index 7963926fc..c1b837305 100644 --- a/packages/mcp-server/src/index.ts +++ b/packages/mcp-server/src/index.ts @@ -1,5 +1,5 @@ /** - * @gsd-build/mcp-server — MCP server for GSD orchestration. + * @gsd-build/mcp-server — MCP server for GSD orchestration and project state. */ export { SessionManager } from './session-manager.js'; @@ -12,3 +12,17 @@ export type { CostAccumulator, } from './types.js'; export { MAX_EVENTS, INIT_TIMEOUT_MS } from './types.js'; + +// Read-only state readers (usable without a running session) +export { readProgress } from './readers/state.js'; +export type { ProgressResult } from './readers/state.js'; +export { readRoadmap } from './readers/roadmap.js'; +export type { RoadmapResult, MilestoneInfo, SliceInfo, TaskInfo } from './readers/roadmap.js'; +export { readHistory } from './readers/metrics.js'; +export type { HistoryResult, MetricsUnit } from './readers/metrics.js'; +export { readCaptures } from './readers/captures.js'; +export type { CapturesResult, CaptureEntry } from './readers/captures.js'; +export { readKnowledge } from './readers/knowledge.js'; +export type { KnowledgeResult, KnowledgeEntry } from './readers/knowledge.js'; +export { runDoctorLite } from './readers/doctor-lite.js'; +export type { DoctorResult, DoctorIssue } from './readers/doctor-lite.js'; diff --git a/packages/mcp-server/src/mcp-server.test.ts b/packages/mcp-server/src/mcp-server.test.ts index 6d7ce156e..c3ba68065 100644 --- a/packages/mcp-server/src/mcp-server.test.ts +++ b/packages/mcp-server/src/mcp-server.test.ts @@ -16,7 +16,11 @@ import { resolve } from 'node:path'; import { EventEmitter } from 'node:events'; import { SessionManager } from './session-manager.js'; -import { createMcpServer } from './server.js'; +import { + buildAskUserQuestionsElicitRequest, + createMcpServer, + formatAskUserQuestionsElicitResult, +} from './server.js'; import { MAX_EVENTS } from './types.js'; import type { ManagedSession, CostAccumulator, PendingBlocker } from './types.js'; @@ -574,6 +578,8 @@ describe('createMcpServer tool registration', () => { it('creates server successfully with all required methods', async () => { const { server } = await createMcpServer(sm); assert.ok(server); + assert.ok(server.server); + assert.equal(typeof server.server.elicitInput, 'function'); assert.ok(typeof server.connect === 'function'); assert.ok(typeof server.close === 'function'); }); @@ -625,4 +631,82 @@ describe('createMcpServer tool registration', () => { const session = sm.getSession(sessionId)!; assert.equal(session.status, 'cancelled'); }); + + it('buildAskUserQuestionsElicitRequest adds None of the above note field for single-select questions', () => { + const request = buildAskUserQuestionsElicitRequest([ + { + id: 'depth_verification_M001', + header: 'Depth Check', + question: 'Did I capture the depth right?', + options: [ + { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' }, + { label: 'Not quite', description: 'I need to clarify the depth further.' }, + ], + }, + { + id: 'focus_areas', + header: 'Focus', + question: 'Which areas matter most?', + allowMultiple: true, + options: [ + { label: 'Frontend', description: 'Prioritize the UI.' }, + { label: 'Backend', description: 'Prioritize server logic.' }, + ], + }, + ]); + + assert.equal(request.mode, 'form'); + assert.deepEqual(request.requestedSchema.required, ['depth_verification_M001', 'focus_areas']); + assert.ok(request.requestedSchema.properties['depth_verification_M001']); + assert.ok(request.requestedSchema.properties['depth_verification_M001__note']); + assert.ok(!request.requestedSchema.properties['focus_areas__note']); + }); + + it('formatAskUserQuestionsElicitResult preserves the existing answers JSON shape', () => { + const result = formatAskUserQuestionsElicitResult( + [ + { + id: 'depth_verification_M001', + header: 'Depth Check', + question: 'Did I capture the depth right?', + options: [ + { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' }, + { label: 'Not quite', description: 'I need to clarify the depth further.' }, + ], + }, + { + id: 'focus_areas', + header: 'Focus', + question: 'Which areas matter most?', + allowMultiple: true, + options: [ + { label: 'Frontend', description: 'Prioritize the UI.' }, + { label: 'Backend', description: 'Prioritize server logic.' }, + ], + }, + ], + { + action: 'accept', + content: { + depth_verification_M001: 'None of the above', + depth_verification_M001__note: 'Need more implementation detail.', + focus_areas: ['Frontend', 'Backend'], + }, + }, + ); + + assert.equal( + result, + JSON.stringify({ + answers: { + depth_verification_M001: { + answers: ['None of the above', 'user_note: Need more implementation detail.'], + }, + focus_areas: { + answers: ['Frontend', 'Backend'], + }, + }, + }), + ); + }); }); diff --git a/packages/mcp-server/src/readers/captures.ts b/packages/mcp-server/src/readers/captures.ts new file mode 100644 index 000000000..9cbd71570 --- /dev/null +++ b/packages/mcp-server/src/readers/captures.ts @@ -0,0 +1,119 @@ +// GSD MCP Server — captures reader +// Copyright (c) 2026 Jeremy McSpadden + +import { readFileSync, existsSync } from 'node:fs'; +import { resolveGsdRoot, resolveRootFile } from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export type CaptureStatus = 'pending' | 'triaged' | 'resolved'; +export type CaptureClassification = + | 'quick-task' | 'inject' | 'defer' | 'replan' | 'note' | 'stop' | 'backtrack'; + +export interface CaptureEntry { + id: string; + text: string; + timestamp: string; + status: CaptureStatus; + classification: CaptureClassification | null; + resolution: string | null; + rationale: string | null; + resolvedAt: string | null; + milestone: string | null; + executed: string | null; +} + +export interface CapturesResult { + captures: CaptureEntry[]; + counts: { + total: number; + pending: number; + resolved: number; + actionable: number; + }; +} + +// --------------------------------------------------------------------------- +// Parser +// --------------------------------------------------------------------------- + +function parseCapturesMarkdown(content: string): CaptureEntry[] { + const entries: CaptureEntry[] = []; + + // Split on H3 headers: ### CAP-xxxxxxxx + const sections = content.split(/(?=^### CAP-)/m); + + for (const section of sections) { + const idMatch = section.match(/^### (CAP-[\da-f]+)/); + if (!idMatch) continue; + + const id = idMatch[1]; + const field = (label: string): string | null => { + const re = new RegExp(`\\*\\*${label}:\\*\\*\\s*(.+)`, 'i'); + const m = section.match(re); + return m ? m[1].trim() : null; + }; + + const status = (field('Status') ?? 'pending').toLowerCase() as CaptureStatus; + const classification = field('Classification') as CaptureClassification | null; + + entries.push({ + id, + text: field('Text') ?? '', + timestamp: field('Captured') ?? '', + status, + classification, + resolution: field('Resolution'), + rationale: field('Rationale'), + resolvedAt: field('Resolved'), + milestone: field('Milestone'), + executed: field('Executed'), + }); + } + + return entries; +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +const ACTIONABLE_CLASSIFICATIONS = new Set(['quick-task', 'inject', 'replan']); + +export function readCaptures( + projectDir: string, + filter: 'all' | 'pending' | 'actionable' = 'all', +): CapturesResult { + const gsd = resolveGsdRoot(projectDir); + const capturesPath = resolveRootFile(gsd, 'CAPTURES.md'); + + if (!existsSync(capturesPath)) { + return { captures: [], counts: { total: 0, pending: 0, resolved: 0, actionable: 0 } }; + } + + const content = readFileSync(capturesPath, 'utf-8'); + let captures = parseCapturesMarkdown(content); + + // Compute counts before filtering + const counts = { + total: captures.length, + pending: captures.filter((c) => c.status === 'pending').length, + resolved: captures.filter((c) => c.status === 'resolved').length, + actionable: captures.filter( + (c) => c.classification !== null && ACTIONABLE_CLASSIFICATIONS.has(c.classification), + ).length, + }; + + // Apply filter + if (filter === 'pending') { + captures = captures.filter((c) => c.status === 'pending'); + } else if (filter === 'actionable') { + captures = captures.filter( + (c) => c.classification !== null && ACTIONABLE_CLASSIFICATIONS.has(c.classification), + ); + } + + return { captures, counts }; +} diff --git a/packages/mcp-server/src/readers/doctor-lite.ts b/packages/mcp-server/src/readers/doctor-lite.ts new file mode 100644 index 000000000..8b826090c --- /dev/null +++ b/packages/mcp-server/src/readers/doctor-lite.ts @@ -0,0 +1,225 @@ +// GSD MCP Server — lightweight structural health checks +// Copyright (c) 2026 Jeremy McSpadden + +import { existsSync, readFileSync } from 'node:fs'; +import { + resolveGsdRoot, + resolveRootFile, + findMilestoneIds, + resolveMilestoneFile, + resolveMilestoneDir, + findSliceIds, + resolveSliceFile, + findTaskFiles, +} from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export type Severity = 'info' | 'warning' | 'error'; + +export interface DoctorIssue { + severity: Severity; + code: string; + scope: 'project' | 'milestone' | 'slice' | 'task'; + unitId: string; + message: string; + file?: string; +} + +export interface DoctorResult { + ok: boolean; + issues: DoctorIssue[]; + counts: { error: number; warning: number; info: number }; +} + +// --------------------------------------------------------------------------- +// Check implementations +// --------------------------------------------------------------------------- + +function checkProjectLevel(gsdRoot: string, issues: DoctorIssue[]): void { + // PROJECT.md should exist + const projectPath = resolveRootFile(gsdRoot, 'PROJECT.md'); + if (!existsSync(projectPath)) { + issues.push({ + severity: 'warning', + code: 'missing_project_md', + scope: 'project', + unitId: '', + message: 'PROJECT.md is missing — project lacks a description', + file: projectPath, + }); + } + + // STATE.md should exist if milestones exist + const milestones = findMilestoneIds(gsdRoot); + if (milestones.length > 0) { + const statePath = resolveRootFile(gsdRoot, 'STATE.md'); + if (!existsSync(statePath)) { + issues.push({ + severity: 'warning', + code: 'missing_state_md', + scope: 'project', + unitId: '', + message: 'STATE.md is missing — run /gsd status to regenerate', + file: statePath, + }); + } + } +} + +function checkMilestoneLevel(gsdRoot: string, mid: string, issues: DoctorIssue[]): void { + const mDir = resolveMilestoneDir(gsdRoot, mid); + if (!mDir) { + issues.push({ + severity: 'error', + code: 'missing_milestone_dir', + scope: 'milestone', + unitId: mid, + message: `Milestone directory for ${mid} not found`, + }); + return; + } + + // CONTEXT.md should exist + const ctxPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT'); + if (!ctxPath || !existsSync(ctxPath)) { + // Check for draft + const draftPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT-DRAFT'); + if (!draftPath || !existsSync(draftPath)) { + issues.push({ + severity: 'warning', + code: 'missing_context', + scope: 'milestone', + unitId: mid, + message: `${mid} has no CONTEXT.md — milestone lacks defined scope`, + }); + } + } + + // ROADMAP.md should exist if slices exist + const sliceIds = findSliceIds(gsdRoot, mid); + if (sliceIds.length > 0) { + const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP'); + if (!roadmapPath || !existsSync(roadmapPath)) { + issues.push({ + severity: 'warning', + code: 'missing_roadmap', + scope: 'milestone', + unitId: mid, + message: `${mid} has ${sliceIds.length} slices but no ROADMAP.md`, + }); + } + } + + // Check if all slices done but no SUMMARY + if (sliceIds.length > 0) { + const allDone = sliceIds.every((sid) => { + const tasks = findTaskFiles(gsdRoot, mid, sid); + return tasks.length > 0 && tasks.every((t) => t.hasSummary); + }); + const summaryPath = resolveMilestoneFile(gsdRoot, mid, 'SUMMARY'); + if (allDone && (!summaryPath || !existsSync(summaryPath))) { + issues.push({ + severity: 'error', + code: 'all_slices_done_missing_summary', + scope: 'milestone', + unitId: mid, + message: `${mid} has all slices completed but no SUMMARY.md`, + }); + } + } +} + +function checkSliceLevel( + gsdRoot: string, mid: string, sid: string, issues: DoctorIssue[], +): void { + const unitId = `${mid}/${sid}`; + + // PLAN.md should exist + const planPath = resolveSliceFile(gsdRoot, mid, sid, 'PLAN'); + if (!planPath || !existsSync(planPath)) { + issues.push({ + severity: 'error', + code: 'missing_slice_plan', + scope: 'slice', + unitId, + message: `${unitId} has no PLAN.md`, + }); + } + + // Tasks should have plans + const tasks = findTaskFiles(gsdRoot, mid, sid); + for (const task of tasks) { + const taskUnitId = `${unitId}/${task.id}`; + if (!task.hasPlan) { + issues.push({ + severity: 'warning', + code: 'missing_task_plan', + scope: 'task', + unitId: taskUnitId, + message: `${taskUnitId} has a summary but no plan file`, + }); + } + } + + // Check for empty slice (directory exists but no tasks or plan) + if (tasks.length === 0 && (!planPath || !existsSync(planPath))) { + issues.push({ + severity: 'warning', + code: 'empty_slice', + scope: 'slice', + unitId, + message: `${unitId} has no plan and no tasks — may be abandoned`, + }); + } +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function runDoctorLite(projectDir: string, scope?: string): DoctorResult { + const gsdRoot = resolveGsdRoot(projectDir); + const issues: DoctorIssue[] = []; + + if (!existsSync(gsdRoot)) { + return { + ok: true, + issues: [{ + severity: 'info', + code: 'no_gsd_directory', + scope: 'project', + unitId: '', + message: 'No .gsd/ directory found — project not initialized', + }], + counts: { error: 0, warning: 0, info: 1 }, + }; + } + + // Project-level checks + checkProjectLevel(gsdRoot, issues); + + // Milestone + slice checks + const milestoneIds = scope + ? findMilestoneIds(gsdRoot).filter((id) => id === scope) + : findMilestoneIds(gsdRoot); + + for (const mid of milestoneIds) { + checkMilestoneLevel(gsdRoot, mid, issues); + + const sliceIds = findSliceIds(gsdRoot, mid); + for (const sid of sliceIds) { + checkSliceLevel(gsdRoot, mid, sid, issues); + } + } + + const counts = { + error: issues.filter((i) => i.severity === 'error').length, + warning: issues.filter((i) => i.severity === 'warning').length, + info: issues.filter((i) => i.severity === 'info').length, + }; + + return { ok: counts.error === 0, issues, counts }; +} diff --git a/packages/mcp-server/src/readers/index.ts b/packages/mcp-server/src/readers/index.ts new file mode 100644 index 000000000..d5b3368c7 --- /dev/null +++ b/packages/mcp-server/src/readers/index.ts @@ -0,0 +1,16 @@ +// GSD MCP Server — readers barrel export +// Copyright (c) 2026 Jeremy McSpadden + +export { resolveGsdRoot, resolveRootFile } from './paths.js'; +export { readProgress } from './state.js'; +export type { ProgressResult } from './state.js'; +export { readRoadmap } from './roadmap.js'; +export type { RoadmapResult, MilestoneInfo, SliceInfo, TaskInfo } from './roadmap.js'; +export { readHistory } from './metrics.js'; +export type { HistoryResult, MetricsUnit } from './metrics.js'; +export { readCaptures } from './captures.js'; +export type { CapturesResult, CaptureEntry } from './captures.js'; +export { readKnowledge } from './knowledge.js'; +export type { KnowledgeResult, KnowledgeEntry } from './knowledge.js'; +export { runDoctorLite } from './doctor-lite.js'; +export type { DoctorResult, DoctorIssue } from './doctor-lite.js'; diff --git a/packages/mcp-server/src/readers/knowledge.ts b/packages/mcp-server/src/readers/knowledge.ts new file mode 100644 index 000000000..134df44e0 --- /dev/null +++ b/packages/mcp-server/src/readers/knowledge.ts @@ -0,0 +1,111 @@ +// GSD MCP Server — knowledge base reader +// Copyright (c) 2026 Jeremy McSpadden + +import { readFileSync, existsSync } from 'node:fs'; +import { resolveGsdRoot, resolveRootFile } from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export type KnowledgeType = 'rule' | 'pattern' | 'lesson'; + +export interface KnowledgeEntry { + id: string; + type: KnowledgeType; + scope: string; + content: string; + addedAt: string; +} + +export interface KnowledgeResult { + entries: KnowledgeEntry[]; + counts: { rules: number; patterns: number; lessons: number }; +} + +// --------------------------------------------------------------------------- +// Parser +// --------------------------------------------------------------------------- + +function parseTableRows(section: string, type: KnowledgeType): KnowledgeEntry[] { + const entries: KnowledgeEntry[] = []; + const lines = section.split('\n'); + + for (const line of lines) { + if (!line.includes('|')) continue; + const cells = line.split('|').map((c) => c.trim()).filter(Boolean); + if (cells.length < 3) continue; + // Skip header/separator + if (cells[0].startsWith('#') || cells[0].startsWith('-')) continue; + + const id = cells[0]; + if (!/^[KPL]\d+$/i.test(id)) continue; + + if (type === 'rule' && cells.length >= 5) { + entries.push({ + id, type, scope: cells[1], content: cells[2], addedAt: cells[4] ?? '', + }); + } else if (type === 'pattern' && cells.length >= 4) { + entries.push({ + id, type, scope: cells[2] ?? '', content: cells[1], addedAt: cells[3] ?? '', + }); + } else if (type === 'lesson' && cells.length >= 5) { + entries.push({ + id, type, scope: cells[4] ?? '', + content: `${cells[1]} — Root cause: ${cells[2]} — Fix: ${cells[3]}`, + addedAt: '', + }); + } + } + + return entries; +} + +function parseKnowledgeMarkdown(content: string): KnowledgeEntry[] { + const entries: KnowledgeEntry[] = []; + + // Find ## Rules section + const rulesMatch = content.match(/## Rules\s*\n([\s\S]*?)(?=\n## |$)/i); + if (rulesMatch) { + entries.push(...parseTableRows(rulesMatch[1], 'rule')); + } + + // Find ## Patterns section + const patternsMatch = content.match(/## Patterns\s*\n([\s\S]*?)(?=\n## |$)/i); + if (patternsMatch) { + entries.push(...parseTableRows(patternsMatch[1], 'pattern')); + } + + // Find ## Lessons Learned section + const lessonsMatch = content.match(/## Lessons Learned\s*\n([\s\S]*?)(?=\n## |$)/i); + if (lessonsMatch) { + entries.push(...parseTableRows(lessonsMatch[1], 'lesson')); + } + + return entries; +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function readKnowledge(projectDir: string): KnowledgeResult { + const gsd = resolveGsdRoot(projectDir); + const knowledgePath = resolveRootFile(gsd, 'KNOWLEDGE.md'); + + if (!existsSync(knowledgePath)) { + return { entries: [], counts: { rules: 0, patterns: 0, lessons: 0 } }; + } + + const content = readFileSync(knowledgePath, 'utf-8'); + const entries = parseKnowledgeMarkdown(content); + + return { + entries, + counts: { + rules: entries.filter((e) => e.type === 'rule').length, + patterns: entries.filter((e) => e.type === 'pattern').length, + lessons: entries.filter((e) => e.type === 'lesson').length, + }, + }; +} diff --git a/packages/mcp-server/src/readers/metrics.ts b/packages/mcp-server/src/readers/metrics.ts new file mode 100644 index 000000000..0b6635ceb --- /dev/null +++ b/packages/mcp-server/src/readers/metrics.ts @@ -0,0 +1,118 @@ +// GSD MCP Server — metrics/history reader +// Copyright (c) 2026 Jeremy McSpadden + +import { readFileSync, existsSync } from 'node:fs'; +import { resolveGsdRoot, resolveRootFile } from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export interface MetricsUnit { + type: string; + id: string; + model: string; + startedAt: number; + finishedAt: number; + tokens: { + input: number; + output: number; + cacheRead: number; + cacheWrite: number; + total: number; + }; + cost: number; + toolCalls: number; + apiRequests: number; +} + +export interface HistoryResult { + entries: MetricsUnit[]; + totals: { + cost: number; + tokens: { input: number; output: number; total: number }; + units: number; + durationMs: number; + }; +} + +// --------------------------------------------------------------------------- +// Parser +// --------------------------------------------------------------------------- + +function parseMetricsJson(content: string): MetricsUnit[] { + try { + const data = JSON.parse(content); + if (!data.units || !Array.isArray(data.units)) return []; + + return data.units.map((u: Record) => ({ + type: String(u.type ?? 'unknown'), + id: String(u.id ?? ''), + model: String(u.model ?? 'unknown'), + startedAt: Number(u.startedAt ?? 0), + finishedAt: Number(u.finishedAt ?? 0), + tokens: { + input: Number((u.tokens as Record)?.input ?? 0), + output: Number((u.tokens as Record)?.output ?? 0), + cacheRead: Number((u.tokens as Record)?.cacheRead ?? 0), + cacheWrite: Number((u.tokens as Record)?.cacheWrite ?? 0), + total: Number((u.tokens as Record)?.total ?? 0), + }, + cost: Number(u.cost ?? 0), + toolCalls: Number(u.toolCalls ?? 0), + apiRequests: Number(u.apiRequests ?? 0), + })); + } catch { + return []; + } +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function readHistory(projectDir: string, limit?: number): HistoryResult { + const gsd = resolveGsdRoot(projectDir); + + // metrics.json (primary) + const metricsPath = resolveRootFile(gsd, 'metrics.json'); + let units: MetricsUnit[] = []; + + if (existsSync(metricsPath)) { + const content = readFileSync(metricsPath, 'utf-8'); + units = parseMetricsJson(content); + } + + // Sort by startedAt descending (most recent first) + units.sort((a, b) => b.startedAt - a.startedAt); + + // Apply limit + if (limit && limit > 0) { + units = units.slice(0, limit); + } + + // Compute totals from ALL units (not just limited set) + const allUnits = existsSync(metricsPath) + ? parseMetricsJson(readFileSync(metricsPath, 'utf-8')) + : []; + + const totals = { + cost: 0, + tokens: { input: 0, output: 0, total: 0 }, + units: allUnits.length, + durationMs: 0, + }; + + for (const u of allUnits) { + totals.cost += u.cost; + totals.tokens.input += u.tokens.input; + totals.tokens.output += u.tokens.output; + totals.tokens.total += u.tokens.total; + totals.durationMs += (u.finishedAt - u.startedAt); + } + + // Round cost to 4 decimal places + totals.cost = Math.round(totals.cost * 10000) / 10000; + + return { entries: units, totals }; +} diff --git a/packages/mcp-server/src/readers/paths.ts b/packages/mcp-server/src/readers/paths.ts new file mode 100644 index 000000000..ad0418a36 --- /dev/null +++ b/packages/mcp-server/src/readers/paths.ts @@ -0,0 +1,217 @@ +// GSD MCP Server — .gsd/ directory resolution +// Copyright (c) 2026 Jeremy McSpadden + +import { existsSync, statSync, readdirSync } from 'node:fs'; +import { join, resolve, dirname, basename } from 'node:path'; +import { execFileSync } from 'node:child_process'; + +/** + * Resolve the .gsd/ root directory for a project. + * + * Probes in order: + * 1. projectDir/.gsd (fast path) + * 2. git repo root/.gsd + * 3. Walk up from projectDir + * 4. Fallback: projectDir/.gsd (even if missing — for init) + */ +export function resolveGsdRoot(projectDir: string): string { + const resolved = resolve(projectDir); + + // Fast path: .gsd/ in the given directory + const direct = join(resolved, '.gsd'); + if (existsSync(direct) && statSync(direct).isDirectory()) { + return direct; + } + + // Try git repo root + try { + const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { + cwd: resolved, + encoding: 'utf-8', + stdio: ['pipe', 'pipe', 'pipe'], + }).trim(); + const gitGsd = join(gitRoot, '.gsd'); + if (existsSync(gitGsd) && statSync(gitGsd).isDirectory()) { + return gitGsd; + } + } catch { + // Not a git repo or git not available + } + + // Walk up from projectDir + let dir = resolved; + while (dir !== dirname(dir)) { + const candidate = join(dir, '.gsd'); + if (existsSync(candidate) && statSync(candidate).isDirectory()) { + return candidate; + } + dir = dirname(dir); + } + + // Fallback + return direct; +} + +/** Resolve path to a .gsd/ root file (STATE.md, KNOWLEDGE.md, etc.) */ +export function resolveRootFile(gsdRoot: string, name: string): string { + return join(gsdRoot, name); +} + +/** Resolve path to milestones directory */ +export function milestonesDir(gsdRoot: string): string { + return join(gsdRoot, 'milestones'); +} + +/** + * Find all milestone directory IDs (M001, M002, etc.). + * Handles both bare (M001/) and descriptor (M001-FLIGHT-SIM/) naming. + */ +export function findMilestoneIds(gsdRoot: string): string[] { + const dir = milestonesDir(gsdRoot); + if (!existsSync(dir)) return []; + + const entries = readdirSync(dir, { withFileTypes: true }); + const ids: string[] = []; + + for (const entry of entries) { + if (!entry.isDirectory()) continue; + const match = entry.name.match(/^(M\d+)/); + if (match) ids.push(match[1]); + } + + return ids.sort(); +} + +/** + * Resolve the actual directory name for a milestone ID. + * M001 might live in M001/ or M001-SOME-DESCRIPTOR/. + */ +export function resolveMilestoneDir(gsdRoot: string, milestoneId: string): string | null { + const dir = milestonesDir(gsdRoot); + if (!existsSync(dir)) return null; + + // Fast path: exact match + const exact = join(dir, milestoneId); + if (existsSync(exact) && statSync(exact).isDirectory()) return exact; + + // Prefix match + const entries = readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory() && entry.name.startsWith(milestoneId)) { + return join(dir, entry.name); + } + } + + return null; +} + +/** + * Resolve a milestone-level file (M001-ROADMAP.md, M001-CONTEXT.md, etc.). + * Handles various naming conventions. + */ +export function resolveMilestoneFile(gsdRoot: string, milestoneId: string, suffix: string): string | null { + const mDir = resolveMilestoneDir(gsdRoot, milestoneId); + if (!mDir) return null; + + const dirName = basename(mDir); + + // Try: M001-ROADMAP.md, then DIRNAME-ROADMAP.md + const candidates = [ + join(mDir, `${milestoneId}-${suffix}.md`), + join(mDir, `${dirName}-${suffix}.md`), + join(mDir, `${suffix}.md`), + ]; + + for (const c of candidates) { + if (existsSync(c)) return c; + } + return null; +} + +/** Find all slice IDs within a milestone (S01, S02, etc.) */ +export function findSliceIds(gsdRoot: string, milestoneId: string): string[] { + const mDir = resolveMilestoneDir(gsdRoot, milestoneId); + if (!mDir) return []; + + const slicesDir = join(mDir, 'slices'); + if (!existsSync(slicesDir)) return []; + + const entries = readdirSync(slicesDir, { withFileTypes: true }); + const ids: string[] = []; + + for (const entry of entries) { + if (!entry.isDirectory()) continue; + const match = entry.name.match(/^(S\d+)/); + if (match) ids.push(match[1]); + } + + return ids.sort(); +} + +/** Resolve the actual directory for a slice */ +export function resolveSliceDir(gsdRoot: string, milestoneId: string, sliceId: string): string | null { + const mDir = resolveMilestoneDir(gsdRoot, milestoneId); + if (!mDir) return null; + + const slicesDir = join(mDir, 'slices'); + if (!existsSync(slicesDir)) return null; + + const exact = join(slicesDir, sliceId); + if (existsSync(exact) && statSync(exact).isDirectory()) return exact; + + const entries = readdirSync(slicesDir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory() && entry.name.startsWith(sliceId)) { + return join(slicesDir, entry.name); + } + } + return null; +} + +/** Resolve a slice-level file (S01-PLAN.md, etc.) */ +export function resolveSliceFile( + gsdRoot: string, milestoneId: string, sliceId: string, suffix: string, +): string | null { + const sDir = resolveSliceDir(gsdRoot, milestoneId, sliceId); + if (!sDir) return null; + + const dirName = basename(sDir); + const candidates = [ + join(sDir, `${sliceId}-${suffix}.md`), + join(sDir, `${dirName}-${suffix}.md`), + join(sDir, `${suffix}.md`), + ]; + + for (const c of candidates) { + if (existsSync(c)) return c; + } + return null; +} + +/** Find all task files in a slice's tasks/ directory */ +export function findTaskFiles( + gsdRoot: string, milestoneId: string, sliceId: string, +): Array<{ id: string; hasPlan: boolean; hasSummary: boolean }> { + const sDir = resolveSliceDir(gsdRoot, milestoneId, sliceId); + if (!sDir) return []; + + const tasksDir = join(sDir, 'tasks'); + if (!existsSync(tasksDir)) return []; + + const files = readdirSync(tasksDir); + const taskMap = new Map(); + + for (const f of files) { + const match = f.match(/^(T\d+).*-(PLAN|SUMMARY)\.md$/i); + if (!match) continue; + const [, id, type] = match; + const existing = taskMap.get(id) ?? { hasPlan: false, hasSummary: false }; + if (type.toUpperCase() === 'PLAN') existing.hasPlan = true; + if (type.toUpperCase() === 'SUMMARY') existing.hasSummary = true; + taskMap.set(id, existing); + } + + return Array.from(taskMap.entries()) + .map(([id, info]) => ({ id, ...info })) + .sort((a, b) => a.id.localeCompare(b.id)); +} diff --git a/packages/mcp-server/src/readers/readers.test.ts b/packages/mcp-server/src/readers/readers.test.ts new file mode 100644 index 000000000..98d157279 --- /dev/null +++ b/packages/mcp-server/src/readers/readers.test.ts @@ -0,0 +1,509 @@ +// GSD MCP Server — reader tests +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdirSync, writeFileSync, rmSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import { randomBytes } from 'node:crypto'; + +import { readProgress } from './state.js'; +import { readRoadmap } from './roadmap.js'; +import { readHistory } from './metrics.js'; +import { readCaptures } from './captures.js'; +import { readKnowledge } from './knowledge.js'; +import { runDoctorLite } from './doctor-lite.js'; + +// --------------------------------------------------------------------------- +// Test fixture helpers +// --------------------------------------------------------------------------- + +function tmpProject(): string { + const dir = join(tmpdir(), `gsd-mcp-test-${randomBytes(4).toString('hex')}`); + mkdirSync(dir, { recursive: true }); + return dir; +} + +function writeFixture(base: string, relPath: string, content: string): void { + const full = join(base, relPath); + mkdirSync(join(full, '..'), { recursive: true }); + writeFileSync(full, content, 'utf-8'); +} + +// --------------------------------------------------------------------------- +// readProgress tests +// --------------------------------------------------------------------------- + +describe('readProgress', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + + writeFixture(projectDir, '.gsd/STATE.md', `# GSD State + +**Active Milestone:** M002: Auth System +**Active Slice:** S01: Login flow +**Phase:** execution +**Requirements Status:** 5 active · 2 validated · 1 deferred · 0 out of scope + +## Milestone Registry + +- ☑ **M001:** Core Setup +- 🔄 **M002:** Auth System +- ⬜ **M003:** Dashboard + +## Blockers + +- Waiting on OAuth provider approval + +## Next Action + +Execute T02 in S01 — implement token refresh. +`); + + // Create filesystem structure + const m1 = '.gsd/milestones/M001/slices/S01/tasks'; + writeFixture(projectDir, `${m1}/T01-PLAN.md`, '# T01'); + writeFixture(projectDir, `${m1}/T01-SUMMARY.md`, '# T01 done'); + + const m2 = '.gsd/milestones/M002/slices/S01/tasks'; + writeFixture(projectDir, `${m2}/T01-PLAN.md`, '# T01'); + writeFixture(projectDir, `${m2}/T01-SUMMARY.md`, '# T01 done'); + writeFixture(projectDir, `${m2}/T02-PLAN.md`, '# T02'); + + mkdirSync(join(projectDir, '.gsd/milestones/M003'), { recursive: true }); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('parses active milestone from STATE.md', () => { + const result = readProgress(projectDir); + assert.deepEqual(result.activeMilestone, { id: 'M002', title: 'Auth System' }); + }); + + it('parses active slice', () => { + const result = readProgress(projectDir); + assert.deepEqual(result.activeSlice, { id: 'S01', title: 'Login flow' }); + }); + + it('parses phase', () => { + const result = readProgress(projectDir); + assert.equal(result.phase, 'execute'); + }); + + it('parses milestone counts from registry', () => { + const result = readProgress(projectDir); + assert.equal(result.milestones.total, 3); + assert.equal(result.milestones.done, 1); + assert.equal(result.milestones.active, 1); + assert.equal(result.milestones.pending, 1); + }); + + it('counts tasks from filesystem', () => { + const result = readProgress(projectDir); + assert.equal(result.tasks.total, 3); + assert.equal(result.tasks.done, 2); + assert.equal(result.tasks.pending, 1); + }); + + it('parses blockers', () => { + const result = readProgress(projectDir); + assert.equal(result.blockers.length, 1); + assert.ok(result.blockers[0].includes('OAuth')); + }); + + it('parses requirements', () => { + const result = readProgress(projectDir); + assert.equal(result.requirements?.active, 5); + assert.equal(result.requirements?.validated, 2); + assert.equal(result.requirements?.deferred, 1); + }); + + it('parses next action', () => { + const result = readProgress(projectDir); + assert.ok(result.nextAction.includes('T02')); + }); + + it('returns defaults for missing .gsd/', () => { + const empty = tmpProject(); + const result = readProgress(empty); + assert.equal(result.phase, 'unknown'); + assert.equal(result.milestones.total, 0); + rmSync(empty, { recursive: true, force: true }); + }); +}); + +// --------------------------------------------------------------------------- +// readRoadmap tests +// --------------------------------------------------------------------------- + +describe('readRoadmap', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + + writeFixture(projectDir, '.gsd/milestones/M001/M001-CONTEXT.md', '# M001: Core Setup\n'); + writeFixture(projectDir, '.gsd/milestones/M001/M001-ROADMAP.md', `# M001: Core Setup + +## Vision + +Build the foundation for the project. + +## Slice Overview + +| ID | Slice | Risk | Depends | Done | After this | +|----|-------|------|---------|------|------------| +| S01 | Database schema | low | — | ☑ | DB ready | +| S02 | API endpoints | medium | S01 | 🟫 | REST API live | +`); + + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/S01-PLAN.md', `# S01: Database schema + +## Tasks + +- [x] **T01: Create migrations** — Set up schema +- [x] **T02: Seed data** — Initial seed +`); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md', '# T01 done'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T02-PLAN.md', '# T02'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T02-SUMMARY.md', '# T02 done'); + + writeFixture(projectDir, '.gsd/milestones/M001/slices/S02/S02-PLAN.md', `# S02: API endpoints + +## Tasks + +- [ ] **T01: Auth routes** — Implement auth +- [ ] **T02: User routes** — CRUD users +`); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S02/tasks/T01-PLAN.md', '# T01'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S02/tasks/T02-PLAN.md', '# T02'); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('returns milestone structure', () => { + const result = readRoadmap(projectDir); + assert.equal(result.milestones.length, 1); + assert.equal(result.milestones[0].id, 'M001'); + assert.equal(result.milestones[0].title, 'Core Setup'); + }); + + it('reads vision from roadmap', () => { + const result = readRoadmap(projectDir); + assert.ok(result.milestones[0].vision.includes('foundation')); + }); + + it('parses slices from roadmap table', () => { + const result = readRoadmap(projectDir); + const slices = result.milestones[0].slices; + assert.equal(slices.length, 2); + assert.equal(slices[0].id, 'S01'); + assert.equal(slices[0].title, 'Database schema'); + assert.equal(slices[1].id, 'S02'); + }); + + it('derives slice status from task summaries', () => { + const result = readRoadmap(projectDir); + const slices = result.milestones[0].slices; + assert.equal(slices[0].status, 'done'); + assert.equal(slices[1].status, 'pending'); + }); + + it('includes tasks in slices', () => { + const result = readRoadmap(projectDir); + const s01Tasks = result.milestones[0].slices[0].tasks; + assert.equal(s01Tasks.length, 2); + assert.equal(s01Tasks[0].status, 'done'); + }); + + it('filters by milestoneId', () => { + const result = readRoadmap(projectDir, 'M999'); + assert.equal(result.milestones.length, 0); + }); +}); + +// --------------------------------------------------------------------------- +// readHistory tests +// --------------------------------------------------------------------------- + +describe('readHistory', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + writeFixture(projectDir, '.gsd/metrics.json', JSON.stringify({ + version: 1, + projectStartedAt: 1700000000000, + units: [ + { + type: 'execute-task', + id: 'M001/S01/T01', + model: 'claude-sonnet-4', + startedAt: 1700001000000, + finishedAt: 1700002000000, + tokens: { input: 10000, output: 3000, cacheRead: 2000, cacheWrite: 1000, total: 16000 }, + cost: 0.05, + toolCalls: 8, + apiRequests: 3, + }, + { + type: 'execute-task', + id: 'M001/S01/T02', + model: 'claude-sonnet-4', + startedAt: 1700003000000, + finishedAt: 1700004000000, + tokens: { input: 15000, output: 5000, cacheRead: 3000, cacheWrite: 1500, total: 24500 }, + cost: 0.08, + toolCalls: 12, + apiRequests: 5, + }, + ], + })); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('returns all entries sorted by most recent', () => { + const result = readHistory(projectDir); + assert.equal(result.entries.length, 2); + assert.equal(result.entries[0].id, 'M001/S01/T02'); // most recent first + }); + + it('computes totals', () => { + const result = readHistory(projectDir); + assert.equal(result.totals.units, 2); + assert.equal(result.totals.cost, 0.13); + assert.equal(result.totals.tokens.total, 40500); + }); + + it('respects limit', () => { + const result = readHistory(projectDir, 1); + assert.equal(result.entries.length, 1); + assert.equal(result.totals.units, 2); // totals still reflect all + }); + + it('returns empty for missing metrics', () => { + const empty = tmpProject(); + mkdirSync(join(empty, '.gsd'), { recursive: true }); + const result = readHistory(empty); + assert.equal(result.entries.length, 0); + assert.equal(result.totals.units, 0); + rmSync(empty, { recursive: true, force: true }); + }); +}); + +// --------------------------------------------------------------------------- +// readCaptures tests +// --------------------------------------------------------------------------- + +describe('readCaptures', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + writeFixture(projectDir, '.gsd/CAPTURES.md', `# Captures + +### CAP-aaa11111 + +**Text:** Add rate limiting to API +**Captured:** 2026-04-01T10:00:00Z +**Status:** pending + +### CAP-bbb22222 + +**Text:** Refactor auth module +**Captured:** 2026-04-02T10:00:00Z +**Status:** resolved +**Classification:** inject +**Resolution:** Added to M003 roadmap +**Rationale:** Important for security +**Resolved:** 2026-04-03T10:00:00Z +**Milestone:** M003 + +### CAP-ccc33333 + +**Text:** Nice to have: dark mode +**Captured:** 2026-04-02T11:00:00Z +**Status:** resolved +**Classification:** defer +**Resolution:** Deferred to future +**Rationale:** Not blocking +**Resolved:** 2026-04-03T11:00:00Z +`); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('reads all captures', () => { + const result = readCaptures(projectDir, 'all'); + assert.equal(result.captures.length, 3); + assert.equal(result.counts.total, 3); + }); + + it('filters pending captures', () => { + const result = readCaptures(projectDir, 'pending'); + assert.equal(result.captures.length, 1); + assert.equal(result.captures[0].id, 'CAP-aaa11111'); + }); + + it('filters actionable captures (inject, replan, quick-task)', () => { + const result = readCaptures(projectDir, 'actionable'); + assert.equal(result.captures.length, 1); + assert.equal(result.captures[0].id, 'CAP-bbb22222'); + }); + + it('counts correctly regardless of filter', () => { + const result = readCaptures(projectDir, 'pending'); + assert.equal(result.counts.total, 3); + assert.equal(result.counts.pending, 1); + assert.equal(result.counts.actionable, 1); + }); + + it('returns empty for missing CAPTURES.md', () => { + const empty = tmpProject(); + mkdirSync(join(empty, '.gsd'), { recursive: true }); + const result = readCaptures(empty); + assert.equal(result.captures.length, 0); + rmSync(empty, { recursive: true, force: true }); + }); +}); + +// --------------------------------------------------------------------------- +// readKnowledge tests +// --------------------------------------------------------------------------- + +describe('readKnowledge', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + writeFixture(projectDir, '.gsd/KNOWLEDGE.md', `# Project Knowledge + +## Rules + +| # | Scope | Rule | Why | Added | +|---|-------|------|-----|-------| +| K001 | auth | Hash passwords with bcrypt | Security requirement | manual | +| K002 | db | Use transactions for multi-table | Data consistency | auto | + +## Patterns + +| # | Pattern | Where | Notes | +|---|---------|-------|-------| +| P001 | Singleton services | services/ | Prevents duplication | + +## Lessons Learned + +| # | What Happened | Root Cause | Fix | Scope | +|---|--------------|------------|-----|-------| +| L001 | CI tests failed | Env diff | Added setup script | testing | +`); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('reads all knowledge entries', () => { + const result = readKnowledge(projectDir); + assert.equal(result.entries.length, 4); + }); + + it('counts by type', () => { + const result = readKnowledge(projectDir); + assert.equal(result.counts.rules, 2); + assert.equal(result.counts.patterns, 1); + assert.equal(result.counts.lessons, 1); + }); + + it('parses rule fields correctly', () => { + const result = readKnowledge(projectDir); + const k001 = result.entries.find((e) => e.id === 'K001'); + assert.ok(k001); + assert.equal(k001.type, 'rule'); + assert.equal(k001.scope, 'auth'); + assert.ok(k001.content.includes('bcrypt')); + }); + + it('returns empty for missing KNOWLEDGE.md', () => { + const empty = tmpProject(); + mkdirSync(join(empty, '.gsd'), { recursive: true }); + const result = readKnowledge(empty); + assert.equal(result.entries.length, 0); + rmSync(empty, { recursive: true, force: true }); + }); +}); + +// --------------------------------------------------------------------------- +// runDoctorLite tests +// --------------------------------------------------------------------------- + +describe('runDoctorLite', () => { + let projectDir: string; + + before(() => { + projectDir = tmpProject(); + + // M001: complete milestone (has summary) + writeFixture(projectDir, '.gsd/PROJECT.md', '# Test Project'); + writeFixture(projectDir, '.gsd/STATE.md', '# GSD State'); + writeFixture(projectDir, '.gsd/milestones/M001/M001-CONTEXT.md', '# M001'); + writeFixture(projectDir, '.gsd/milestones/M001/M001-ROADMAP.md', '# Roadmap'); + writeFixture(projectDir, '.gsd/milestones/M001/M001-SUMMARY.md', '# Done'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/S01-PLAN.md', '# Plan'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T01-PLAN.md', '# T01'); + writeFixture(projectDir, '.gsd/milestones/M001/slices/S01/tasks/T01-SUMMARY.md', '# T01 done'); + + // M002: incomplete — has all tasks done but no SUMMARY + writeFixture(projectDir, '.gsd/milestones/M002/M002-CONTEXT.md', '# M002'); + writeFixture(projectDir, '.gsd/milestones/M002/M002-ROADMAP.md', '# Roadmap'); + writeFixture(projectDir, '.gsd/milestones/M002/slices/S01/S01-PLAN.md', '# Plan'); + writeFixture(projectDir, '.gsd/milestones/M002/slices/S01/tasks/T01-PLAN.md', '# T01'); + writeFixture(projectDir, '.gsd/milestones/M002/slices/S01/tasks/T01-SUMMARY.md', '# T01 done'); + + // M003: empty — no context, no slices + mkdirSync(join(projectDir, '.gsd/milestones/M003'), { recursive: true }); + }); + + after(() => rmSync(projectDir, { recursive: true, force: true })); + + it('detects all-slices-done-missing-summary', () => { + const result = runDoctorLite(projectDir); + const issue = result.issues.find((i) => i.code === 'all_slices_done_missing_summary'); + assert.ok(issue, 'Should detect M002 missing summary'); + assert.equal(issue.unitId, 'M002'); + }); + + it('detects missing context', () => { + const result = runDoctorLite(projectDir); + const issue = result.issues.find( + (i) => i.code === 'missing_context' && i.unitId === 'M003', + ); + assert.ok(issue, 'Should detect M003 missing context'); + }); + + it('scopes to a single milestone', () => { + const result = runDoctorLite(projectDir, 'M001'); + const m002Issues = result.issues.filter((i) => i.unitId.startsWith('M002')); + assert.equal(m002Issues.length, 0, 'Should not include M002 when scoped to M001'); + }); + + it('returns ok:true for healthy project', () => { + const healthy = tmpProject(); + writeFixture(healthy, '.gsd/PROJECT.md', '# Project'); + writeFixture(healthy, '.gsd/STATE.md', '# State'); + const result = runDoctorLite(healthy); + assert.equal(result.ok, true); + rmSync(healthy, { recursive: true, force: true }); + }); + + it('handles missing .gsd/ gracefully', () => { + const empty = tmpProject(); + const result = runDoctorLite(empty); + assert.equal(result.ok, true); + assert.equal(result.issues[0].code, 'no_gsd_directory'); + rmSync(empty, { recursive: true, force: true }); + }); +}); diff --git a/packages/mcp-server/src/readers/roadmap.ts b/packages/mcp-server/src/readers/roadmap.ts new file mode 100644 index 000000000..29a6e1941 --- /dev/null +++ b/packages/mcp-server/src/readers/roadmap.ts @@ -0,0 +1,263 @@ +// GSD MCP Server — roadmap structure reader +// Copyright (c) 2026 Jeremy McSpadden + +import { readFileSync, existsSync } from 'node:fs'; +import { + resolveGsdRoot, + findMilestoneIds, + resolveMilestoneFile, + findSliceIds, + resolveSliceFile, + findTaskFiles, +} from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export interface TaskInfo { + id: string; + title: string; + status: 'done' | 'pending'; +} + +export interface SliceInfo { + id: string; + title: string; + status: 'done' | 'active' | 'pending'; + risk: string; + depends: string[]; + demo: string; + tasks: TaskInfo[]; +} + +export interface MilestoneInfo { + id: string; + title: string; + status: 'done' | 'active' | 'pending' | 'parked'; + vision: string; + slices: SliceInfo[]; +} + +export interface RoadmapResult { + milestones: MilestoneInfo[]; +} + +// --------------------------------------------------------------------------- +// ROADMAP.md table parser +// --------------------------------------------------------------------------- + +function parseRoadmapTable(content: string): Array<{ + id: string; title: string; risk: string; depends: string[]; done: boolean; demo: string; +}> { + const results: Array<{ + id: string; title: string; risk: string; depends: string[]; done: boolean; demo: string; + }> = []; + + // Try table format first: | S01 | Title | risk | depends | done-icon | demo | + const tableSection = content.match(/## (?:Slice[s]?|Slice Overview|Slice Table)\s*\n([\s\S]*?)(?=\n##|\n$|$)/i); + if (tableSection) { + const lines = tableSection[1].split('\n'); + for (const line of lines) { + if (!line.includes('|')) continue; + const cells = line.split('|').map((c) => c.trim()).filter(Boolean); + if (cells.length < 4) continue; + if (cells[0] === 'ID' || cells[0].startsWith('--')) continue; + + const id = cells[0].match(/S\d+/)?.[0]; + if (!id) continue; + + const done = cells.some((c) => c === '\u2611' || c === '\u2705' || c.toLowerCase() === 'done'); + const depends = (cells[3] ?? '').replace(/\u2014/g, '').split(',').map((d) => d.trim()).filter(Boolean); + + results.push({ + id, + title: cells[1] ?? '', + risk: cells[2] ?? 'medium', + depends, + done, + demo: cells[5] ?? '', + }); + } + if (results.length > 0) return results; + } + + // Try checkbox format: - [x] **S01: Title** `risk:high` `depends:[S01]` + const checkboxRe = /^-\s+\[([ xX])\]\s+\*\*(S\d+):\s*(.+?)\*\*(?:.*?`risk:(\w+)`)?(?:.*?`depends:\[([^\]]*)\]`)?/gm; + let match: RegExpExecArray | null; + while ((match = checkboxRe.exec(content)) !== null) { + const [, checked, id, title, risk, deps] = match; + results.push({ + id, + title: title.trim(), + risk: risk ?? 'medium', + depends: deps ? deps.split(',').map((d) => d.trim()).filter(Boolean) : [], + done: checked !== ' ', + demo: '', + }); + } + if (results.length > 0) return results; + + // Try prose headers: ## S01: Title + const headerRe = /^##\s+(S\d+):\s*(.+)/gm; + while ((match = headerRe.exec(content)) !== null) { + results.push({ + id: match[1], + title: match[2].trim(), + risk: 'medium', + depends: [], + done: false, + demo: '', + }); + } + + return results; +} + +// --------------------------------------------------------------------------- +// PLAN.md task parser +// --------------------------------------------------------------------------- + +function parseSlicePlanTasks(content: string): Array<{ id: string; title: string; done: boolean }> { + const results: Array<{ id: string; title: string; done: boolean }> = []; + + // Checkbox format: - [x] **T01: Title** — description + const taskRe = /^-\s+\[([ xX])\]\s+\*\*(T\d+):\s*(.+?)\*\*/gm; + let match: RegExpExecArray | null; + while ((match = taskRe.exec(content)) !== null) { + results.push({ + id: match[2], + title: match[3].trim(), + done: match[1] !== ' ', + }); + } + if (results.length > 0) return results; + + // H3 format: ### T01: Title + const h3Re = /^###\s+(T\d+):\s*(.+)/gm; + while ((match = h3Re.exec(content)) !== null) { + results.push({ + id: match[1], + title: match[2].trim(), + done: false, + }); + } + + return results; +} + +// --------------------------------------------------------------------------- +// Milestone title from CONTEXT.md or ROADMAP.md H1 +// --------------------------------------------------------------------------- + +function readMilestoneTitle(gsdRoot: string, mid: string): string { + const ctxPath = resolveMilestoneFile(gsdRoot, mid, 'CONTEXT'); + if (ctxPath && existsSync(ctxPath)) { + const content = readFileSync(ctxPath, 'utf-8'); + const h1 = content.match(/^#\s+(?:M\d+:?\s*)?(.+)/m); + if (h1) return h1[1].trim(); + } + + const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP'); + if (roadmapPath && existsSync(roadmapPath)) { + const content = readFileSync(roadmapPath, 'utf-8'); + const h1 = content.match(/^#\s+(?:M\d+:?\s*)?(.+)/m); + if (h1) return h1[1].trim(); + } + + return mid; +} + +function readVision(gsdRoot: string, mid: string): string { + const roadmapPath = resolveMilestoneFile(gsdRoot, mid, 'ROADMAP'); + if (!roadmapPath || !existsSync(roadmapPath)) return ''; + + const content = readFileSync(roadmapPath, 'utf-8'); + const section = content.match(/## Vision\s*\n([\s\S]*?)(?=\n##|\n$|$)/i); + return section ? section[1].trim() : ''; +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function readRoadmap(projectDir: string, filterMilestoneId?: string): RoadmapResult { + const gsd = resolveGsdRoot(projectDir); + let milestoneIds = findMilestoneIds(gsd); + + if (filterMilestoneId) { + milestoneIds = milestoneIds.filter((id) => id === filterMilestoneId); + } + + const milestones: MilestoneInfo[] = []; + + for (const mid of milestoneIds) { + const title = readMilestoneTitle(gsd, mid); + const vision = readVision(gsd, mid); + + const summaryPath = resolveMilestoneFile(gsd, mid, 'SUMMARY'); + const hasSummary = summaryPath !== null && existsSync(summaryPath); + + const roadmapPath = resolveMilestoneFile(gsd, mid, 'ROADMAP'); + let roadmapSlices: ReturnType = []; + if (roadmapPath && existsSync(roadmapPath)) { + roadmapSlices = parseRoadmapTable(readFileSync(roadmapPath, 'utf-8')); + } + + const fsSliceIds = findSliceIds(gsd, mid); + const sliceIdSet = new Set([ + ...roadmapSlices.map((s) => s.id), + ...fsSliceIds, + ]); + + const slices: SliceInfo[] = []; + for (const sid of Array.from(sliceIdSet).sort()) { + const roadmapEntry = roadmapSlices.find((s) => s.id === sid); + const taskFiles = findTaskFiles(gsd, mid, sid); + + const planPath = resolveSliceFile(gsd, mid, sid, 'PLAN'); + let planTasks: ReturnType = []; + if (planPath && existsSync(planPath)) { + planTasks = parseSlicePlanTasks(readFileSync(planPath, 'utf-8')); + } + + const tasks: TaskInfo[] = []; + const seenIds = new Set(); + + for (const pt of planTasks) { + const fsTask = taskFiles.find((t) => t.id === pt.id); + const done = fsTask?.hasSummary ?? pt.done; + tasks.push({ id: pt.id, title: pt.title, status: done ? 'done' : 'pending' }); + seenIds.add(pt.id); + } + for (const ft of taskFiles) { + if (seenIds.has(ft.id)) continue; + tasks.push({ id: ft.id, title: ft.id, status: ft.hasSummary ? 'done' : 'pending' }); + } + + const allDone = tasks.length > 0 && tasks.every((t) => t.status === 'done'); + const anyDone = tasks.some((t) => t.status === 'done'); + const sliceStatus: SliceInfo['status'] = allDone ? 'done' : anyDone ? 'active' : 'pending'; + + slices.push({ + id: sid, + title: roadmapEntry?.title ?? sid, + status: sliceStatus, + risk: roadmapEntry?.risk ?? 'medium', + depends: roadmapEntry?.depends ?? [], + demo: roadmapEntry?.demo ?? '', + tasks, + }); + } + + const allSlicesDone = slices.length > 0 && slices.every((s) => s.status === 'done'); + const anySliceActive = slices.some((s) => s.status === 'active' || s.status === 'done'); + const milestoneStatus: MilestoneInfo['status'] = hasSummary + ? 'done' + : allSlicesDone ? 'done' : anySliceActive ? 'active' : 'pending'; + + milestones.push({ id: mid, title, status: milestoneStatus, vision, slices }); + } + + return { milestones }; +} diff --git a/packages/mcp-server/src/readers/state.ts b/packages/mcp-server/src/readers/state.ts new file mode 100644 index 000000000..93ea7d38f --- /dev/null +++ b/packages/mcp-server/src/readers/state.ts @@ -0,0 +1,223 @@ +// GSD MCP Server — project state reader +// Copyright (c) 2026 Jeremy McSpadden + +import { readFileSync, existsSync } from 'node:fs'; +import { + resolveGsdRoot, + resolveRootFile, + findMilestoneIds, + resolveMilestoneDir, + resolveMilestoneFile, + findSliceIds, + findTaskFiles, +} from './paths.js'; + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export interface ProgressResult { + activeMilestone: { id: string; title: string } | null; + activeSlice: { id: string; title: string } | null; + activeTask: { id: string; title: string } | null; + phase: string; + milestones: { total: number; done: number; active: number; pending: number; parked: number }; + slices: { total: number; done: number; active: number; pending: number }; + tasks: { total: number; done: number; pending: number }; + requirements: { active: number; validated: number; deferred: number; outOfScope: number } | null; + blockers: string[]; + nextAction: string; +} + +// --------------------------------------------------------------------------- +// STATE.md parser +// --------------------------------------------------------------------------- + +function parseBoldField(content: string, label: string): string | null { + const re = new RegExp(`\\*\\*${label}:\\*\\*\\s*(.+)`, 'i'); + const m = content.match(re); + return m ? m[1].trim() : null; +} + +function parseActiveRef(value: string | null): { id: string; title: string } | null { + if (!value || value.toLowerCase() === 'none' || value === '—') return null; + // "M001: Flight Simulator" or "M001" + const m = value.match(/^(M\d+|S\d+|T\d+):?\s*(.*)/); + if (m) return { id: m[1], title: m[2] || m[1] }; + return { id: value, title: value }; +} + +function parsePhase(value: string | null): string { + if (!value) return 'unknown'; + const lower = value.toLowerCase().trim(); + if (lower.includes('research') || lower.includes('discuss')) return 'research'; + if (lower.includes('plan')) return 'plan'; + if (lower.includes('execut')) return 'execute'; + if (lower.includes('complete') || lower.includes('done')) return 'complete'; + return lower; +} + +function parseRequirementsLine(value: string | null): ProgressResult['requirements'] | null { + if (!value) return null; + const active = value.match(/(\d+)\s*active/i); + const validated = value.match(/(\d+)\s*validated/i); + const deferred = value.match(/(\d+)\s*deferred/i); + const outOfScope = value.match(/(\d+)\s*out.of.scope/i); + if (!active && !validated && !deferred && !outOfScope) return null; + return { + active: active ? parseInt(active[1], 10) : 0, + validated: validated ? parseInt(validated[1], 10) : 0, + deferred: deferred ? parseInt(deferred[1], 10) : 0, + outOfScope: outOfScope ? parseInt(outOfScope[1], 10) : 0, + }; +} + +function parseBlockers(content: string): string[] { + const section = content.match(/## Blockers\s*\n([\s\S]*?)(?=\n##|\n$|$)/i); + if (!section) return []; + return section[1] + .split('\n') + .map((l) => l.replace(/^[-*]\s*/, '').trim()) + .filter(Boolean); +} + +function parseNextAction(content: string): string { + const section = content.match(/## Next Action\s*\n([\s\S]*?)(?=\n##|\n$|$)/i); + if (!section) return ''; + return section[1].trim().split('\n')[0] || ''; +} + +// --------------------------------------------------------------------------- +// Milestone registry from STATE.md +// --------------------------------------------------------------------------- + +interface RegistryEntry { id: string; status: 'done' | 'active' | 'pending' | 'parked' } + +function parseMilestoneRegistry(content: string): RegistryEntry[] { + const section = content.match(/## Milestone Registry\s*\n([\s\S]*?)(?=\n##|\n$|$)/i); + if (!section) return []; + const entries: RegistryEntry[] = []; + for (const line of section[1].split('\n')) { + const m = line.match(/[-*]\s*(☑|✅|🔄|⬜|⏸)\s*\*\*(M\d+):\*\*/); + if (!m) continue; + const [, icon, id] = m; + let status: RegistryEntry['status'] = 'pending'; + if (icon === '☑' || icon === '✅') status = 'done'; + else if (icon === '🔄') status = 'active'; + else if (icon === '⏸') status = 'parked'; + entries.push({ id, status }); + } + return entries; +} + +// --------------------------------------------------------------------------- +// Count slices/tasks by walking filesystem +// --------------------------------------------------------------------------- + +function countSlicesAndTasks(gsdRoot: string, milestoneIds: string[]): { + slices: ProgressResult['slices']; + tasks: ProgressResult['tasks']; +} { + let sliceTotal = 0, sliceDone = 0, sliceActive = 0; + let taskTotal = 0, taskDone = 0; + + for (const mid of milestoneIds) { + const sliceIds = findSliceIds(gsdRoot, mid); + sliceTotal += sliceIds.length; + + for (const sid of sliceIds) { + const tasks = findTaskFiles(gsdRoot, mid, sid); + taskTotal += tasks.length; + + const allDone = tasks.length > 0 && tasks.every((t) => t.hasSummary); + const anyDone = tasks.some((t) => t.hasSummary); + + if (allDone) { + sliceDone++; + taskDone += tasks.length; + } else { + if (anyDone) sliceActive++; + taskDone += tasks.filter((t) => t.hasSummary).length; + } + } + } + + return { + slices: { + total: sliceTotal, + done: sliceDone, + active: sliceActive, + pending: sliceTotal - sliceDone - sliceActive, + }, + tasks: { total: taskTotal, done: taskDone, pending: taskTotal - taskDone }, + }; +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function readProgress(projectDir: string): ProgressResult { + const gsd = resolveGsdRoot(projectDir); + const statePath = resolveRootFile(gsd, 'STATE.md'); + + // Defaults + const result: ProgressResult = { + activeMilestone: null, + activeSlice: null, + activeTask: null, + phase: 'unknown', + milestones: { total: 0, done: 0, active: 0, pending: 0, parked: 0 }, + slices: { total: 0, done: 0, active: 0, pending: 0 }, + tasks: { total: 0, done: 0, pending: 0 }, + requirements: null, + blockers: [], + nextAction: '', + }; + + if (!existsSync(statePath)) { + // No STATE.md — derive from filesystem only + const milestoneIds = findMilestoneIds(gsd); + result.milestones.total = milestoneIds.length; + result.milestones.pending = milestoneIds.length; + const counts = countSlicesAndTasks(gsd, milestoneIds); + result.slices = counts.slices; + result.tasks = counts.tasks; + return result; + } + + const content = readFileSync(statePath, 'utf-8'); + + // Parse STATE.md fields + result.activeMilestone = parseActiveRef(parseBoldField(content, 'Active Milestone')); + result.activeSlice = parseActiveRef(parseBoldField(content, 'Active Slice')); + result.activeTask = parseActiveRef(parseBoldField(content, 'Active Task')); + result.phase = parsePhase(parseBoldField(content, 'Phase')); + result.requirements = parseRequirementsLine(parseBoldField(content, 'Requirements Status')); + result.blockers = parseBlockers(content); + result.nextAction = parseNextAction(content); + + // Milestone counts from registry + const registry = parseMilestoneRegistry(content); + if (registry.length > 0) { + result.milestones.total = registry.length; + result.milestones.done = registry.filter((e) => e.status === 'done').length; + result.milestones.active = registry.filter((e) => e.status === 'active').length; + result.milestones.parked = registry.filter((e) => e.status === 'parked').length; + result.milestones.pending = registry.length - + result.milestones.done - result.milestones.active - result.milestones.parked; + } else { + // Fallback: count directories + const milestoneIds = findMilestoneIds(gsd); + result.milestones.total = milestoneIds.length; + result.milestones.pending = milestoneIds.length; + } + + // Slice/task counts from filesystem + const milestoneIds = findMilestoneIds(gsd); + const counts = countSlicesAndTasks(gsd, milestoneIds); + result.slices = counts.slices; + result.tasks = counts.tasks; + + return result; +} diff --git a/packages/mcp-server/src/secure-env-collect.test.ts b/packages/mcp-server/src/secure-env-collect.test.ts new file mode 100644 index 000000000..c33ad2949 --- /dev/null +++ b/packages/mcp-server/src/secure-env-collect.test.ts @@ -0,0 +1,265 @@ +// @gsd-build/mcp-server — Tests for secure_env_collect MCP tool +// Copyright (c) 2026 Jeremy McSpadden +// +// Tests the secure_env_collect tool registered in createMcpServer. +// Uses a mock MCP server to intercept tool registration and elicitInput calls. + +import { describe, it, beforeEach } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { createMcpServer } from './server.js'; +import { SessionManager } from './session-manager.js'; + +// --------------------------------------------------------------------------- +// Mock infrastructure +// --------------------------------------------------------------------------- + +/** + * We intercept McpServer construction by monkey-patching the dynamic import. + * Instead, we'll test the tool handler indirectly through the exported + * createMcpServer function — capturing the registered tool handlers. + * + * Since createMcpServer dynamically imports McpServer, we need to test at + * a level that exercises the tool handler logic. We do this by extracting + * the tool handler through the server.tool() calls. + */ + +interface RegisteredTool { + name: string; + description: string; + params: Record; + handler: (args: Record) => Promise; +} + +interface ToolResult { + content?: Array<{ type: string; text: string }>; + isError?: boolean; +} + +/** + * Mock McpServer that captures tool registrations and provides + * a controllable elicitInput response. + */ +class MockMcpServer { + registeredTools: RegisteredTool[] = []; + elicitResponse: { action: string; content?: Record } = { action: 'accept', content: {} }; + + server = { + elicitInput: async (_params: unknown) => { + return this.elicitResponse; + }, + }; + + tool(name: string, description: string, params: Record, handler: (args: Record) => Promise) { + this.registeredTools.push({ name, description, params, handler }); + } + + async connect(_transport: unknown) { /* no-op */ } + async close() { /* no-op */ } + + getToolHandler(name: string): ((args: Record) => Promise) | undefined { + return this.registeredTools.find((t) => t.name === name)?.handler; + } +} + +// --------------------------------------------------------------------------- +// Helper to create a mock MCP server with secure_env_collect registered +// --------------------------------------------------------------------------- + +/** + * Since createMcpServer uses dynamic import for McpServer, we can't easily + * mock it. Instead, we test the env-writer utilities directly (in env-writer.test.ts) + * and test the tool integration by verifying: + * 1. The tool exists in the registered tools list + * 2. The handler produces correct results with mock data + * + * For handler-level testing, we create a standalone test that replicates + * the tool handler logic with a controllable mock. + */ + +function makeTempDir(prefix: string): string { + return mkdtempSync(join(tmpdir(), `${prefix}-`)); +} + +// --------------------------------------------------------------------------- +// Integration test — verify tool is registered +// --------------------------------------------------------------------------- + +describe('secure_env_collect tool registration', () => { + it('createMcpServer registers secure_env_collect tool', async () => { + // This test verifies the tool exists — createMcpServer internally calls + // server.tool('secure_env_collect', ...) which we can't intercept without + // module mocking, but we can verify the server creates successfully + const sm = new SessionManager(); + try { + const { server } = await createMcpServer(sm); + assert.ok(server, 'server should be created'); + // The McpServer internally tracks registered tools — we verify no error + } finally { + await sm.cleanup(); + } + }); +}); + +// --------------------------------------------------------------------------- +// Handler logic tests — using env-writer directly to test the flow +// --------------------------------------------------------------------------- + +describe('secure_env_collect handler logic', () => { + it('skips keys that already exist in .env', async () => { + const tmp = makeTempDir('sec-collect'); + try { + const envPath = join(tmp, '.env'); + writeFileSync(envPath, 'ALREADY_SET=existing-value\n'); + + // Import the utility directly to test the pre-check logic + const { checkExistingEnvKeys } = await import('./env-writer.js'); + const existing = await checkExistingEnvKeys(['ALREADY_SET', 'NEW_KEY'], envPath); + assert.deepStrictEqual(existing, ['ALREADY_SET']); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('writes collected values to .env without returning secret values', async () => { + const tmp = makeTempDir('sec-collect'); + try { + const envPath = join(tmp, '.env'); + const savedKey = process.env.SEC_COLLECT_TEST_KEY; + + const { applySecrets } = await import('./env-writer.js'); + const { applied, errors } = await applySecrets( + [{ key: 'SEC_COLLECT_TEST_KEY', value: 'super-secret-value' }], + 'dotenv', + { envFilePath: envPath }, + ); + + assert.deepStrictEqual(applied, ['SEC_COLLECT_TEST_KEY']); + assert.deepStrictEqual(errors, []); + + // Verify the value was written + const content = readFileSync(envPath, 'utf8'); + assert.ok(content.includes('SEC_COLLECT_TEST_KEY=super-secret-value')); + + // Verify process.env was hydrated + assert.equal(process.env.SEC_COLLECT_TEST_KEY, 'super-secret-value'); + + // Cleanup + if (savedKey === undefined) delete process.env.SEC_COLLECT_TEST_KEY; + else process.env.SEC_COLLECT_TEST_KEY = savedKey; + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('auto-detects vercel destination from vercel.json', async () => { + const tmp = makeTempDir('sec-collect'); + try { + writeFileSync(join(tmp, 'vercel.json'), '{}'); + const { detectDestination } = await import('./env-writer.js'); + assert.equal(detectDestination(tmp), 'vercel'); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('handles empty form values as skipped', async () => { + // Simulate what happens when user leaves a field empty in the form + const formContent: Record = { + 'API_KEY': 'provided-value', + 'OPTIONAL_KEY': '', // empty = skip + }; + + const provided: Array<{ key: string; value: string }> = []; + const skipped: string[] = []; + + for (const [key, raw] of Object.entries(formContent)) { + const value = typeof raw === 'string' ? raw.trim() : ''; + if (value.length > 0) { + provided.push({ key, value }); + } else { + skipped.push(key); + } + } + + assert.deepStrictEqual(provided, [{ key: 'API_KEY', value: 'provided-value' }]); + assert.deepStrictEqual(skipped, ['OPTIONAL_KEY']); + }); + + it('result text never contains secret values', async () => { + const tmp = makeTempDir('sec-collect'); + try { + const envPath = join(tmp, '.env'); + const savedKey = process.env.RESULT_TEXT_TEST; + + const { applySecrets } = await import('./env-writer.js'); + const { applied } = await applySecrets( + [{ key: 'RESULT_TEXT_TEST', value: 'sk-super-secret-abc123' }], + 'dotenv', + { envFilePath: envPath }, + ); + + // Simulate building result text (same logic as the tool handler) + const lines: string[] = [ + 'destination: dotenv (auto-detected)', + ...applied.map((k) => `✓ ${k}: applied`), + ]; + const resultText = lines.join('\n'); + + // The result MUST NOT contain the secret value + assert.ok(!resultText.includes('sk-super-secret-abc123'), 'result text must not contain secret value'); + assert.ok(resultText.includes('RESULT_TEXT_TEST'), 'result text should contain key name'); + + // Cleanup + if (savedKey === undefined) delete process.env.RESULT_TEXT_TEST; + else process.env.RESULT_TEXT_TEST = savedKey; + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + it('handles multiple keys with mixed existing/new/skipped', async () => { + const tmp = makeTempDir('sec-collect'); + try { + const envPath = join(tmp, '.env'); + writeFileSync(envPath, 'EXISTING_A=already-here\n'); + const savedB = process.env.NEW_B; + const savedC = process.env.SKIP_C; + + const { checkExistingEnvKeys, applySecrets } = await import('./env-writer.js'); + + const allKeys = ['EXISTING_A', 'NEW_B', 'SKIP_C']; + const existing = await checkExistingEnvKeys(allKeys, envPath); + assert.deepStrictEqual(existing, ['EXISTING_A']); + + // Simulate form response: NEW_B has value, SKIP_C is empty + const formContent = { NEW_B: 'new-value', SKIP_C: '' }; + const provided: Array<{ key: string; value: string }> = []; + const skipped: string[] = []; + + for (const key of allKeys.filter((k) => !existing.includes(k))) { + const raw = formContent[key as keyof typeof formContent] ?? ''; + if (raw.trim().length > 0) provided.push({ key, value: raw.trim() }); + else skipped.push(key); + } + + const { applied, errors } = await applySecrets(provided, 'dotenv', { envFilePath: envPath }); + + assert.deepStrictEqual(applied, ['NEW_B']); + assert.deepStrictEqual(skipped, ['SKIP_C']); + assert.deepStrictEqual(errors, []); + assert.deepStrictEqual(existing, ['EXISTING_A']); + + // Cleanup + if (savedB === undefined) delete process.env.NEW_B; + else process.env.NEW_B = savedB; + if (savedC === undefined) delete process.env.SKIP_C; + else process.env.SKIP_C = savedC; + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts index 202b4731a..d619ff0f6 100644 --- a/packages/mcp-server/src/server.ts +++ b/packages/mcp-server/src/server.ts @@ -1,5 +1,10 @@ /** - * MCP Server — registers 6 GSD orchestration tools on McpServer. + * MCP Server — registers GSD orchestration, project-state, and workflow tools. + * + * Session tools (6): gsd_execute, gsd_status, gsd_result, gsd_cancel, gsd_query, gsd_resolve_blocker + * Interactive tools (2): ask_user_questions, secure_env_collect via MCP form elicitation + * Read-only tools (6): gsd_progress, gsd_roadmap, gsd_history, gsd_doctor, gsd_captures, gsd_knowledge + * Workflow tools (29): headless-safe planning, metadata persistence, replanning, completion, validation, reassessment, gate result, status, and journal tools * * Uses dynamic imports for @modelcontextprotocol/sdk because TS Node16 * cannot resolve the SDK's subpath exports statically (same pattern as @@ -10,6 +15,14 @@ import { readFile, readdir, stat } from 'node:fs/promises'; import { join, resolve } from 'node:path'; import { z } from 'zod'; import type { SessionManager } from './session-manager.js'; +import { readProgress } from './readers/state.js'; +import { readRoadmap } from './readers/roadmap.js'; +import { readHistory } from './readers/metrics.js'; +import { readCaptures } from './readers/captures.js'; +import { readKnowledge } from './readers/knowledge.js'; +import { runDoctorLite } from './readers/doctor-lite.js'; +import { registerWorkflowTools } from './workflow-tools.js'; +import { applySecrets, checkExistingEnvKeys, detectDestination } from './env-writer.js'; // --------------------------------------------------------------------------- // Constants @@ -17,7 +30,7 @@ import type { SessionManager } from './session-manager.js'; const MCP_PKG = '@modelcontextprotocol/sdk'; const SERVER_NAME = 'gsd'; -const SERVER_VERSION = '2.51.0'; +const SERVER_VERSION = '2.53.0'; // --------------------------------------------------------------------------- // Tool result helpers @@ -33,6 +46,11 @@ function errorContent(message: string): { isError: true; content: Array<{ type: return { isError: true, content: [{ type: 'text' as const, text: message }] }; } +/** Return raw text content without JSON wrapping. */ +function textContent(text: string): { content: Array<{ type: 'text'; text: string }> } { + return { content: [{ type: 'text' as const, text }] }; +} + // --------------------------------------------------------------------------- // gsd_query filesystem reader // --------------------------------------------------------------------------- @@ -95,18 +113,178 @@ async function fileExists(path: string): Promise { // MCP Server type — minimal interface for the dynamically-imported McpServer // --------------------------------------------------------------------------- +interface ElicitResult { + action: 'accept' | 'decline' | 'cancel'; + content?: Record; +} + +interface ElicitRequestFormParams { + mode?: 'form'; + message: string; + requestedSchema: { + type: 'object'; + properties: Record>; + required?: string[]; + }; +} + interface McpServerInstance { tool(name: string, description: string, params: Record, handler: (args: Record) => Promise): unknown; + server: { + elicitInput( + params: AskUserQuestionsElicitRequest | ElicitRequestFormParams, + options?: unknown, + ): Promise; + }; connect(transport: unknown): Promise; close(): Promise; } +interface AskUserQuestionOption { + label: string; + description: string; +} + +interface AskUserQuestion { + id: string; + header: string; + question: string; + options: AskUserQuestionOption[]; + allowMultiple?: boolean; +} + +interface AskUserQuestionsParams { + questions: AskUserQuestion[]; +} + +type AskUserQuestionsContentValue = string | number | boolean | string[]; + +interface AskUserQuestionsElicitResult { + action: 'accept' | 'decline' | 'cancel'; + content?: Record; +} + +interface AskUserQuestionsElicitRequest { + mode: 'form'; + message: string; + requestedSchema: { + type: 'object'; + properties: Record>; + required?: string[]; + }; +} + +const OTHER_OPTION_LABEL = 'None of the above'; + +function normalizeAskUserQuestionsNote(value: AskUserQuestionsContentValue | undefined): string { + return typeof value === 'string' ? value.trim() : ''; +} + +function normalizeAskUserQuestionsAnswers( + value: AskUserQuestionsContentValue | undefined, + allowMultiple: boolean, +): string[] { + if (allowMultiple) { + return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []; + } + + return typeof value === 'string' && value.length > 0 ? [value] : []; +} + +function validateAskUserQuestionsPayload(questions: AskUserQuestion[]): string | null { + if (questions.length === 0 || questions.length > 3) { + return 'Error: questions must contain 1-3 items'; + } + + for (const question of questions) { + if (!question.options || question.options.length === 0) { + return `Error: ask_user_questions requires non-empty options for every question (question "${question.id}" has none)`; + } + } + + return null; +} + +export function buildAskUserQuestionsElicitRequest(questions: AskUserQuestion[]): AskUserQuestionsElicitRequest { + const properties: Record> = {}; + const required = questions.map((question) => question.id); + + for (const question of questions) { + if (question.allowMultiple) { + properties[question.id] = { + type: 'array', + title: question.header, + description: question.question, + minItems: 1, + maxItems: question.options.length, + items: { + anyOf: question.options.map((option) => ({ + const: option.label, + title: option.label, + })), + }, + }; + continue; + } + + properties[question.id] = { + type: 'string', + title: question.header, + description: question.question, + oneOf: [...question.options, { label: OTHER_OPTION_LABEL, description: 'Choose this when the listed options do not fit.' }].map((option) => ({ + const: option.label, + title: option.label, + })), + }; + + properties[`${question.id}__note`] = { + type: 'string', + title: `${question.header} Note`, + description: `Optional note for "${OTHER_OPTION_LABEL}".`, + maxLength: 500, + }; + } + + return { + mode: 'form', + message: 'Please answer the following question(s). For single-select questions, choose "None of the above" and add a note if the provided options do not fit.', + requestedSchema: { + type: 'object', + properties, + required, + }, + }; +} + +export function formatAskUserQuestionsElicitResult( + questions: AskUserQuestion[], + result: AskUserQuestionsElicitResult, +): string { + const answers: Record = {}; + const content = result.content ?? {}; + + for (const question of questions) { + const answerList = normalizeAskUserQuestionsAnswers(content[question.id], !!question.allowMultiple); + + if (!question.allowMultiple && answerList[0] === OTHER_OPTION_LABEL) { + const note = normalizeAskUserQuestionsNote(content[`${question.id}__note`]); + if (note) { + answerList.push(`user_note: ${note}`); + } + } + + answers[question.id] = { answers: answerList }; + } + + return JSON.stringify({ answers }); +} + // --------------------------------------------------------------------------- // createMcpServer // --------------------------------------------------------------------------- /** - * Create and configure an MCP server with 6 GSD orchestration tools. + * Create and configure an MCP server with session, read-only, and workflow tools. * * Returns the McpServer instance — call `connect(transport)` to start serving. * Uses dynamic imports for the MCP SDK to avoid TS subpath resolution issues. @@ -120,7 +298,7 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{ const server: McpServerInstance = new McpServer( { name: SERVER_NAME, version: SERVER_VERSION }, - { capabilities: { tools: {} } }, + { capabilities: { tools: {}, elicitation: {} } }, ); // ----------------------------------------------------------------------- @@ -274,5 +452,283 @@ export async function createMcpServer(sessionManager: SessionManager): Promise<{ }, ); + // ----------------------------------------------------------------------- + // ask_user_questions — structured user input via MCP form elicitation + // ----------------------------------------------------------------------- + server.tool( + 'ask_user_questions', + 'Request user input for one to three short questions and wait for the response. Single-select questions include a free-form "None of the above" path. Multi-select questions allow multiple choices.', + { + questions: z.array(z.object({ + id: z.string().describe('Stable identifier for mapping answers (snake_case)'), + header: z.string().describe('Short header label shown in the UI (12 or fewer chars)'), + question: z.string().describe('Single-sentence prompt shown to the user'), + options: z.array(z.object({ + label: z.string().describe('User-facing label (1-5 words)'), + description: z.string().describe('One short sentence explaining impact/tradeoff if selected'), + })).describe('Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select questions.'), + allowMultiple: z.boolean().optional().describe('If true, the user can select multiple options. No "None of the above" option is added.'), + })).describe('Questions to show the user. Prefer 1 and do not exceed 3.'), + }, + async (args: Record) => { + const { questions } = args as unknown as AskUserQuestionsParams; + try { + const validationError = validateAskUserQuestionsPayload(questions); + if (validationError) return errorContent(validationError); + + const elicitation = await server.server.elicitInput(buildAskUserQuestionsElicitRequest(questions)); + if (elicitation.action !== 'accept' || !elicitation.content) { + return textContent('ask_user_questions was cancelled before receiving a response'); + } + + return textContent(formatAskUserQuestionsElicitResult(questions, elicitation)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // secure_env_collect — collect secrets via MCP form elicitation + // ----------------------------------------------------------------------- + server.tool( + 'secure_env_collect', + 'Collect environment variables securely via form input. Values are written directly to .env (or Vercel/Convex) and NEVER appear in tool output — only key names and applied/skipped status are returned. Use this instead of asking users to manually edit .env files or paste secrets into chat.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + keys: z.array(z.object({ + key: z.string().describe('Env var name, e.g. OPENAI_API_KEY'), + hint: z.string().optional().describe('Format hint shown to user, e.g. "starts with sk-"'), + guidance: z.array(z.string()).optional().describe('Step-by-step instructions for obtaining this key'), + })).min(1).describe('Environment variables to collect'), + destination: z.enum(['dotenv', 'vercel', 'convex']).optional().describe('Where to write secrets. Auto-detected from project files if omitted.'), + envFilePath: z.string().optional().describe('Path to .env file (dotenv only). Defaults to .env in projectDir.'), + environment: z.enum(['development', 'preview', 'production']).optional().describe('Target environment (vercel/convex only)'), + }, + async (args: Record) => { + const { projectDir, keys, destination, envFilePath, environment } = args as { + projectDir: string; + keys: Array<{ key: string; hint?: string; guidance?: string[] }>; + destination?: 'dotenv' | 'vercel' | 'convex'; + envFilePath?: string; + environment?: 'development' | 'preview' | 'production'; + }; + + try { + const resolvedProjectDir = resolve(projectDir); + const resolvedEnvPath = resolve(resolvedProjectDir, envFilePath ?? '.env'); + + // (1) Check which keys already exist + const allKeyNames = keys.map((k) => k.key); + const existingKeys = await checkExistingEnvKeys(allKeyNames, resolvedEnvPath); + const existingSet = new Set(existingKeys); + const pendingKeys = keys.filter((k) => !existingSet.has(k.key)); + + // If all keys already exist, return immediately + if (pendingKeys.length === 0) { + const lines = existingKeys.map((k) => `• ${k}: already set`); + return textContent(`All ${existingKeys.length} key(s) already set.\n${lines.join('\n')}`); + } + + // (2) Build elicitation form — one string field per pending key + const properties: Record> = {}; + const required: string[] = []; + + for (const item of pendingKeys) { + const descParts: string[] = []; + if (item.hint) descParts.push(`Format: ${item.hint}`); + if (item.guidance && item.guidance.length > 0) { + descParts.push('How to get this:'); + item.guidance.forEach((step, i) => descParts.push(`${i + 1}. ${step}`)); + } + descParts.push('Leave empty to skip.'); + + properties[item.key] = { + type: 'string', + title: item.key, + description: descParts.join('\n'), + }; + // Don't mark as required — empty string = skip + } + + // (3) Elicit input from the MCP client + const elicitation = await server.server.elicitInput({ + message: `Enter values for ${pendingKeys.length} environment variable(s). Values are written directly to the project and never shown to the AI.`, + requestedSchema: { + type: 'object', + properties, + required, + }, + }); + + if (elicitation.action !== 'accept' || !elicitation.content) { + return textContent('secure_env_collect was cancelled by user.'); + } + + // (4) Separate provided vs skipped from form response + const provided: Array<{ key: string; value: string }> = []; + const skipped: string[] = []; + + for (const item of pendingKeys) { + const raw = elicitation.content[item.key]; + const value = typeof raw === 'string' ? raw.trim() : ''; + if (value.length > 0) { + provided.push({ key: item.key, value }); + } else { + skipped.push(item.key); + } + } + + // (5) Auto-detect destination if not specified + const resolvedDestination = destination ?? detectDestination(resolvedProjectDir); + + // (6) Write secrets to destination + const { applied, errors } = await applySecrets(provided, resolvedDestination, { + envFilePath: resolvedEnvPath, + environment, + }); + + // (7) Build result — NEVER include secret values + const lines: string[] = [ + `destination: ${resolvedDestination}${!destination ? ' (auto-detected)' : ''}${environment ? ` (${environment})` : ''}`, + ]; + for (const k of applied) lines.push(`✓ ${k}: applied`); + for (const k of skipped) lines.push(`• ${k}: skipped`); + for (const k of existingKeys) lines.push(`• ${k}: already set`); + for (const e of errors) lines.push(`✗ ${e}`); + + return errors.length > 0 && applied.length === 0 + ? errorContent(lines.join('\n')) + : textContent(lines.join('\n')); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ======================================================================= + // READ-ONLY TOOLS — no session required, pure filesystem reads + // ======================================================================= + + // ----------------------------------------------------------------------- + // gsd_progress — structured project progress metrics + // ----------------------------------------------------------------------- + server.tool( + 'gsd_progress', + 'Get structured project progress: active milestone/slice/task, phase, completion counts, blockers, and next action. No session required — reads directly from .gsd/ on disk.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + }, + async (args: Record) => { + const { projectDir } = args as { projectDir: string }; + try { + return jsonContent(readProgress(projectDir)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // gsd_roadmap — milestone/slice/task structure with status + // ----------------------------------------------------------------------- + server.tool( + 'gsd_roadmap', + 'Get the full project roadmap structure: milestones with their slices, tasks, status, risk, and dependencies. Optionally filter to a single milestone. No session required.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + milestoneId: z.string().optional().describe('Filter to a specific milestone (e.g. "M001")'), + }, + async (args: Record) => { + const { projectDir, milestoneId } = args as { projectDir: string; milestoneId?: string }; + try { + return jsonContent(readRoadmap(projectDir, milestoneId)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // gsd_history — execution history with cost/token metrics + // ----------------------------------------------------------------------- + server.tool( + 'gsd_history', + 'Get execution history with cost, token usage, model, and duration per unit. Returns totals across all units. No session required.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + limit: z.number().optional().describe('Max entries to return (most recent first). Default: all.'), + }, + async (args: Record) => { + const { projectDir, limit } = args as { projectDir: string; limit?: number }; + try { + return jsonContent(readHistory(projectDir, limit)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // gsd_doctor — lightweight structural health check + // ----------------------------------------------------------------------- + server.tool( + 'gsd_doctor', + 'Run a lightweight structural health check on the .gsd/ directory. Checks for missing files, status inconsistencies, and orphaned state. No session required.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + scope: z.string().optional().describe('Limit checks to a specific milestone (e.g. "M001")'), + }, + async (args: Record) => { + const { projectDir, scope } = args as { projectDir: string; scope?: string }; + try { + return jsonContent(runDoctorLite(projectDir, scope)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // gsd_captures — pending captures and ideas + // ----------------------------------------------------------------------- + server.tool( + 'gsd_captures', + 'Get captured ideas and thoughts from CAPTURES.md with triage status. Filter by pending, actionable, or all. No session required.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + filter: z.enum(['all', 'pending', 'actionable']).optional().describe('Filter captures (default: "all")'), + }, + async (args: Record) => { + const { projectDir, filter } = args as { projectDir: string; filter?: 'all' | 'pending' | 'actionable' }; + try { + return jsonContent(readCaptures(projectDir, filter ?? 'all')); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + // ----------------------------------------------------------------------- + // gsd_knowledge — project knowledge base + // ----------------------------------------------------------------------- + server.tool( + 'gsd_knowledge', + 'Get the project knowledge base: rules, patterns, and lessons learned accumulated during development. No session required.', + { + projectDir: z.string().describe('Absolute path to the project directory'), + }, + async (args: Record) => { + const { projectDir } = args as { projectDir: string }; + try { + return jsonContent(readKnowledge(projectDir)); + } catch (err) { + return errorContent(err instanceof Error ? err.message : String(err)); + } + }, + ); + + registerWorkflowTools(server); + return { server }; } diff --git a/packages/mcp-server/src/tool-credentials.test.ts b/packages/mcp-server/src/tool-credentials.test.ts new file mode 100644 index 000000000..b6838a29f --- /dev/null +++ b/packages/mcp-server/src/tool-credentials.test.ts @@ -0,0 +1,95 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { loadStoredCredentialEnvKeys, resolveAuthPath } from "./tool-credentials.js"; + +describe("tool credentials", () => { + it("hydrates supported model and tool keys from auth.json", () => { + const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-")); + const authPath = join(tempRoot, "auth.json"); + const env: NodeJS.ProcessEnv = {}; + + try { + writeFileSync(authPath, JSON.stringify({ + anthropic: { type: "api_key", key: "sk-ant-secret" }, + openai: { type: "api_key", key: "sk-openai-secret" }, + tavily: { type: "api_key", key: "tvly-secret" }, + context7: [{ type: "api_key", key: "ctx7-secret" }], + })); + + const loaded = loadStoredCredentialEnvKeys({ authPath, env }); + assert.deepEqual(loaded.sort(), [ + "ANTHROPIC_API_KEY", + "CONTEXT7_API_KEY", + "OPENAI_API_KEY", + "TAVILY_API_KEY", + ]); + assert.equal(env.ANTHROPIC_API_KEY, "sk-ant-secret"); + assert.equal(env.OPENAI_API_KEY, "sk-openai-secret"); + assert.equal(env.TAVILY_API_KEY, "tvly-secret"); + assert.equal(env.CONTEXT7_API_KEY, "ctx7-secret"); + } finally { + rmSync(tempRoot, { recursive: true, force: true }); + } + }); + + it("does not overwrite explicit environment variables", () => { + const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-")); + const authPath = join(tempRoot, "auth.json"); + const env: NodeJS.ProcessEnv = { + BRAVE_API_KEY: "already-set", + }; + + try { + writeFileSync(authPath, JSON.stringify({ + brave: { type: "api_key", key: "from-auth-json" }, + anthropic: { type: "api_key", key: "sk-ant-from-auth-json" }, + })); + + const loaded = loadStoredCredentialEnvKeys({ authPath, env }); + assert.deepEqual(loaded, ["ANTHROPIC_API_KEY"]); + assert.equal(env.BRAVE_API_KEY, "already-set"); + assert.equal(env.ANTHROPIC_API_KEY, "sk-ant-from-auth-json"); + } finally { + rmSync(tempRoot, { recursive: true, force: true }); + } + }); + + it("ignores oauth credentials because they are resolved through auth storage, not env hydration", () => { + const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-auth-")); + const authPath = join(tempRoot, "auth.json"); + const env: NodeJS.ProcessEnv = {}; + + try { + writeFileSync(authPath, JSON.stringify({ + openai: { type: "oauth", access: "oauth-access-token" }, + "google-gemini-cli": { type: "oauth", token: "ya29.oauth-token" }, + })); + + const loaded = loadStoredCredentialEnvKeys({ authPath, env }); + assert.deepEqual(loaded, []); + assert.equal(env.OPENAI_API_KEY, undefined); + assert.equal(env.GEMINI_API_KEY, undefined); + } finally { + rmSync(tempRoot, { recursive: true, force: true }); + } + }); + + it("resolves auth.json from GSD_CODING_AGENT_DIR", () => { + const tempRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-agent-dir-")); + const agentDir = join(tempRoot, "agent"); + mkdirSync(agentDir, { recursive: true }); + + try { + assert.equal( + resolveAuthPath({ GSD_CODING_AGENT_DIR: agentDir }), + join(agentDir, "auth.json"), + ); + } finally { + rmSync(tempRoot, { recursive: true, force: true }); + } + }); +}); diff --git a/packages/mcp-server/src/tool-credentials.ts b/packages/mcp-server/src/tool-credentials.ts new file mode 100644 index 000000000..d19487437 --- /dev/null +++ b/packages/mcp-server/src/tool-credentials.ts @@ -0,0 +1,97 @@ +import { existsSync, readFileSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +type AuthCredential = + | { type?: unknown; key?: unknown } + | Array<{ type?: unknown; key?: unknown }>; + +type AuthStorageData = Record; + +const AUTH_ENV_KEYS = [ + ["anthropic", "ANTHROPIC_API_KEY"], + ["openai", "OPENAI_API_KEY"], + ["github-copilot", "GITHUB_TOKEN"], + ["google", "GEMINI_API_KEY"], + ["groq", "GROQ_API_KEY"], + ["xai", "XAI_API_KEY"], + ["openrouter", "OPENROUTER_API_KEY"], + ["mistral", "MISTRAL_API_KEY"], + ["ollama-cloud", "OLLAMA_API_KEY"], + ["custom-openai", "CUSTOM_OPENAI_API_KEY"], + ["cerebras", "CEREBRAS_API_KEY"], + ["azure-openai-responses", "AZURE_OPENAI_API_KEY"], + ["vercel-ai-gateway", "AI_GATEWAY_API_KEY"], + ["zai", "ZAI_API_KEY"], + ["minimax", "MINIMAX_API_KEY"], + ["minimax-cn", "MINIMAX_CN_API_KEY"], + ["huggingface", "HF_TOKEN"], + ["opencode", "OPENCODE_API_KEY"], + ["opencode-go", "OPENCODE_API_KEY"], + ["kimi-coding", "KIMI_API_KEY"], + ["alibaba-coding-plan", "ALIBABA_API_KEY"], + ["brave", "BRAVE_API_KEY"], + ["brave_answers", "BRAVE_ANSWERS_KEY"], + ["context7", "CONTEXT7_API_KEY"], + ["jina", "JINA_API_KEY"], + ["tavily", "TAVILY_API_KEY"], + ["slack_bot", "SLACK_BOT_TOKEN"], + ["discord_bot", "DISCORD_BOT_TOKEN"], + ["telegram_bot", "TELEGRAM_BOT_TOKEN"], +] as const; + +function expandHome(pathValue: string): string { + if (pathValue === "~") return homedir(); + if (pathValue.startsWith("~/")) return join(homedir(), pathValue.slice(2)); + return pathValue; +} + +function getStoredApiKey(data: AuthStorageData, providerId: string): string | undefined { + const raw = data[providerId]; + const credentials = Array.isArray(raw) ? raw : raw ? [raw] : []; + + for (const credential of credentials) { + if (credential?.type !== "api_key") continue; + if (typeof credential.key !== "string") continue; + if (credential.key.trim().length === 0) continue; + return credential.key; + } + + return undefined; +} + +export function resolveAuthPath(env: NodeJS.ProcessEnv = process.env): string { + const agentDir = env.GSD_CODING_AGENT_DIR?.trim(); + if (agentDir) return join(expandHome(agentDir), "auth.json"); + return join(homedir(), ".gsd", "agent", "auth.json"); +} + +export function loadStoredCredentialEnvKeys(options: { + env?: NodeJS.ProcessEnv; + authPath?: string; +} = {}): string[] { + const env = options.env ?? process.env; + const authPath = options.authPath ?? resolveAuthPath(env); + if (!existsSync(authPath)) return []; + + let parsed: AuthStorageData; + try { + const raw = readFileSync(authPath, "utf-8"); + const data = JSON.parse(raw) as unknown; + if (!data || typeof data !== "object" || Array.isArray(data)) return []; + parsed = data as AuthStorageData; + } catch { + return []; + } + + const loaded: string[] = []; + for (const [providerId, envVar] of AUTH_ENV_KEYS) { + if (env[envVar]) continue; + const key = getStoredApiKey(parsed, providerId); + if (!key) continue; + env[envVar] = key; + loaded.push(envVar); + } + + return loaded; +} diff --git a/packages/mcp-server/src/workflow-tools.test.ts b/packages/mcp-server/src/workflow-tools.test.ts new file mode 100644 index 000000000..8435203c6 --- /dev/null +++ b/packages/mcp-server/src/workflow-tools.test.ts @@ -0,0 +1,1093 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { _getAdapter, closeDatabase } from "../../../src/resources/extensions/gsd/gsd-db.ts"; +import { registerWorkflowTools, WORKFLOW_TOOL_NAMES } from "./workflow-tools.ts"; + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-mcp-workflow-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { + closeDatabase(); + } catch { + // swallow + } + try { + rmSync(base, { recursive: true, force: true }); + } catch { + // swallow + } +} + +function writeWriteGateSnapshot( + base: string, + snapshot: { verifiedDepthMilestones?: string[]; activeQueuePhase?: boolean; pendingGateId?: string | null }, +): void { + mkdirSync(join(base, ".gsd", "runtime"), { recursive: true }); + writeFileSync( + join(base, ".gsd", "runtime", "write-gate-state.json"), + JSON.stringify( + { + verifiedDepthMilestones: snapshot.verifiedDepthMilestones ?? [], + activeQueuePhase: snapshot.activeQueuePhase ?? false, + pendingGateId: snapshot.pendingGateId ?? null, + }, + null, + 2, + ), + "utf-8", + ); +} + +function makeMockServer() { + const tools: Array<{ + name: string; + description: string; + params: Record; + handler: (args: Record) => Promise; + }> = []; + return { + tools, + tool( + name: string, + description: string, + params: Record, + handler: (args: Record) => Promise, + ) { + tools.push({ name, description, params, handler }); + }, + }; +} + +describe("workflow MCP tools", () => { + it("registers the full headless-safe workflow tool surface", () => { + const server = makeMockServer(); + registerWorkflowTools(server as any); + + assert.equal(server.tools.length, WORKFLOW_TOOL_NAMES.length); + assert.deepEqual(server.tools.map((t) => t.name), [...WORKFLOW_TOOL_NAMES]); + }); + + it("gsd_summary_save writes artifact through the shared executor", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const tool = server.tools.find((t) => t.name === "gsd_summary_save"); + assert.ok(tool, "summary tool should be registered"); + const originalCwd = process.cwd(); + + const result = await tool!.handler({ + projectDir: base, + milestone_id: "M001", + slice_id: "S01", + artifact_type: "SUMMARY", + content: "# Summary\n\nHello", + }); + + const text = (result as any).content[0].text as string; + assert.match(text, /Saved SUMMARY artifact/); + assert.equal(process.cwd(), originalCwd, "workflow MCP tools should not mutate process.cwd"); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md")), + "summary file should exist on disk", + ); + } finally { + cleanup(base); + } + }); + + it("rejects workflow tool calls outside the configured project root", async () => { + const base = makeTmpBase(); + const otherBase = makeTmpBase(); + const prevRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT; + try { + process.env.GSD_WORKFLOW_PROJECT_ROOT = base; + const server = makeMockServer(); + registerWorkflowTools(server as any); + const tool = server.tools.find((t) => t.name === "gsd_summary_save"); + assert.ok(tool, "summary tool should be registered"); + + await assert.rejects( + () => + tool!.handler({ + projectDir: otherBase, + milestone_id: "M001", + artifact_type: "SUMMARY", + content: "# Summary", + }), + /configured workflow project root/, + ); + } finally { + if (prevRoot === undefined) { + delete process.env.GSD_WORKFLOW_PROJECT_ROOT; + } else { + process.env.GSD_WORKFLOW_PROJECT_ROOT = prevRoot; + } + cleanup(base); + cleanup(otherBase); + } + }); + + it("rejects non-file executor module URLs", async () => { + const base = makeTmpBase(); + const prevModule = process.env.GSD_WORKFLOW_EXECUTORS_MODULE; + const prevRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT; + try { + process.env.GSD_WORKFLOW_PROJECT_ROOT = base; + process.env.GSD_WORKFLOW_EXECUTORS_MODULE = "data:text/javascript,export default {}"; + const { registerWorkflowTools: freshRegisterWorkflowTools } = await import(`./workflow-tools.ts?bad-module=${randomUUID()}`); + const server = makeMockServer(); + freshRegisterWorkflowTools(server as any); + const tool = server.tools.find((t) => t.name === "gsd_summary_save"); + assert.ok(tool, "summary tool should be registered"); + + await assert.rejects( + () => + tool!.handler({ + projectDir: base, + milestone_id: "M001", + artifact_type: "SUMMARY", + content: "# Summary", + }), + /only supports file: URLs or filesystem paths/, + ); + } finally { + if (prevModule === undefined) { + delete process.env.GSD_WORKFLOW_EXECUTORS_MODULE; + } else { + process.env.GSD_WORKFLOW_EXECUTORS_MODULE = prevModule; + } + if (prevRoot === undefined) { + delete process.env.GSD_WORKFLOW_PROJECT_ROOT; + } else { + process.env.GSD_WORKFLOW_PROJECT_ROOT = prevRoot; + } + cleanup(base); + } + }); + + it("blocks workflow mutation tools while a discussion gate is pending", async () => { + const base = makeTmpBase(); + try { + mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true }); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"), + "# S01\n\n- [ ] **T01: Demo** `est:5m`\n", + ); + writeWriteGateSnapshot(base, { pendingGateId: "depth_verification_M001_confirm" }); + + const server = makeMockServer(); + registerWorkflowTools(server as any); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + assert.ok(taskTool, "task tool should be registered"); + + await assert.rejects( + () => + taskTool!.handler({ + projectDir: base, + taskId: "T01", + sliceId: "S01", + milestoneId: "M001", + oneLiner: "Completed task", + narrative: "Did the work", + verification: "npm test", + }), + /Discussion gate .* has not been confirmed/, + ); + } finally { + cleanup(base); + } + }); + + it("blocks workflow mutation tools during queue mode", async () => { + const base = makeTmpBase(); + try { + mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true }); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"), + "# S01\n\n- [ ] **T01: Demo** `est:5m`\n", + ); + writeWriteGateSnapshot(base, { activeQueuePhase: true }); + + const server = makeMockServer(); + registerWorkflowTools(server as any); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + assert.ok(taskTool, "task tool should be registered"); + + await assert.rejects( + () => + taskTool!.handler({ + projectDir: base, + taskId: "T01", + sliceId: "S01", + milestoneId: "M001", + oneLiner: "Completed task", + narrative: "Did the work", + verification: "npm test", + }), + /planning tool .* not executes work|Cannot gsd_task_complete|Unknown tools are not permitted during queue mode/, + ); + } finally { + cleanup(base); + } + }); + + it("gsd_task_complete and gsd_milestone_status work end-to-end", async () => { + const base = makeTmpBase(); + try { + mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true }); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"), + "# S01\n\n- [ ] **T01: Demo** `est:5m`\n", + ); + + const server = makeMockServer(); + registerWorkflowTools(server as any); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + const statusTool = server.tools.find((t) => t.name === "gsd_milestone_status"); + assert.ok(taskTool, "task tool should be registered"); + assert.ok(statusTool, "status tool should be registered"); + + const taskResult = await taskTool!.handler({ + projectDir: base, + taskId: "T01", + sliceId: "S01", + milestoneId: "M001", + oneLiner: "Completed task", + narrative: "Did the work", + verification: "npm test", + }); + + assert.match((taskResult as any).content[0].text as string, /Completed task T01/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md")), + "task summary should be written to disk", + ); + + const statusResult = await statusTool!.handler({ + projectDir: base, + milestoneId: "M001", + }); + const parsed = JSON.parse((statusResult as any).content[0].text as string); + assert.equal(parsed.milestoneId, "M001"); + assert.equal(parsed.sliceCount, 1); + assert.equal(parsed.slices[0].id, "S01"); + } finally { + cleanup(base); + } + }); + + it("gsd_complete_task alias delegates to gsd_task_complete behavior", async () => { + const base = makeTmpBase(); + try { + mkdirSync(join(base, ".gsd", "milestones", "M002", "slices", "S02"), { recursive: true }); + writeFileSync( + join(base, ".gsd", "milestones", "M002", "slices", "S02", "S02-PLAN.md"), + "# S02\n\n- [ ] **T02: Demo** `est:5m`\n", + ); + + const server = makeMockServer(); + registerWorkflowTools(server as any); + const aliasTool = server.tools.find((t) => t.name === "gsd_complete_task"); + assert.ok(aliasTool, "task completion alias should be registered"); + + const result = await aliasTool!.handler({ + projectDir: base, + taskId: "T02", + sliceId: "S02", + milestoneId: "M002", + oneLiner: "Completed task via alias", + narrative: "Did the work through alias", + verification: "npm test", + }); + + assert.match((result as any).content[0].text as string, /Completed task T02/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M002", "slices", "S02", "tasks", "T02-SUMMARY.md")), + "alias should write task summary to disk", + ); + } finally { + cleanup(base); + } + }); + + it("gsd_plan_milestone and gsd_plan_slice work end-to-end", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + + const milestoneResult = await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M001", + title: "Workflow MCP planning", + vision: "Plan milestone over MCP.", + slices: [ + { + sliceId: "S01", + title: "Bridge planning", + risk: "medium", + depends: [], + demo: "Milestone plan persists through MCP.", + goal: "Persist roadmap state.", + successCriteria: "ROADMAP.md renders from DB.", + proofLevel: "integration", + integrationClosure: "Prompts and MCP call the same handler.", + observabilityImpact: "Executor tests cover output paths.", + }, + ], + }); + assert.match((milestoneResult as any).content[0].text as string, /Planned milestone M001/); + + const sliceResult = await sliceTool!.handler({ + projectDir: base, + milestoneId: "M001", + sliceId: "S01", + goal: "Persist slice plan over MCP.", + tasks: [ + { + taskId: "T01", + title: "Add planning bridge", + description: "Implement the shared executor path.", + estimate: "15m", + files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"], + verify: "node --test", + inputs: ["ROADMAP.md"], + expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"], + }, + ], + }); + assert.match((sliceResult as any).content[0].text as string, /Planned slice S01/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md")), + "slice plan should exist on disk", + ); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-PLAN.md")), + "task plan should exist on disk", + ); + } finally { + cleanup(base); + } + }); + + it("gsd_requirement_save opens the DB before inline requirement writes", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const requirementTool = server.tools.find((t) => t.name === "gsd_requirement_save"); + assert.ok(requirementTool, "requirement tool should be registered"); + + closeDatabase(); + + const result = await requirementTool!.handler({ + projectDir: base, + class: "operability", + description: "Inline MCP requirement save regression", + why: "Reproduce missing ensureDbOpen in workflow-tools", + source: "user", + status: "active", + primary_owner: "M010/S10", + validation: "n/a", + }); + + assert.match((result as any).content[0].text as string, /Saved requirement R\d+/); + assert.ok(existsSync(join(base, ".gsd", "REQUIREMENTS.md")), "REQUIREMENTS.md should be written to disk"); + const row = _getAdapter()! + .prepare("SELECT id, class, description FROM requirements WHERE description = ?") + .get("Inline MCP requirement save regression") as Record | undefined; + assert.ok(row, "requirement should be written to the database"); + assert.equal(row["class"], "operability"); + } finally { + cleanup(base); + } + }); + + it("gsd_plan_task reopens the DB before inline task planning writes", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + const taskTool = server.tools.find((t) => t.name === "gsd_plan_task"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + assert.ok(taskTool, "task planning tool should be registered"); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M010", + title: "Inline task planning DB reopen", + vision: "Seed a slice, close the DB, then plan another task inline.", + slices: [ + { + sliceId: "S10", + title: "Inline task planning", + risk: "medium", + depends: [], + demo: "Inline gsd_plan_task reopens the DB after it was closed.", + goal: "Preserve MCP task planning after the DB adapter is closed.", + successCriteria: "The second task plan persists after a closed DB is reopened.", + proofLevel: "integration", + integrationClosure: "The inline MCP handler reopens the DB before planning.", + observabilityImpact: "workflow-tools MCP tests cover the inline reopen path.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M010", + sliceId: "S10", + goal: "Create the initial slice plan before closing the DB.", + tasks: [ + { + taskId: "T10", + title: "Seed existing task", + description: "Create the initial task plan before closing the DB.", + estimate: "5m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M010-ROADMAP.md"], + expectedOutput: ["T10-PLAN.md"], + }, + ], + }); + + closeDatabase(); + + const result = await taskTool!.handler({ + projectDir: base, + milestoneId: "M010", + sliceId: "S10", + taskId: "T11", + title: "Reopen and plan", + description: "Exercise the inline plan-task path after the DB was closed.", + estimate: "5m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M010-ROADMAP.md", "S10-PLAN.md"], + expectedOutput: ["T11-PLAN.md"], + }); + + assert.match((result as any).content[0].text as string, /Planned task T11/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M010", "slices", "S10", "tasks", "T11-PLAN.md")), + "T11 plan should be written after reopening the DB", + ); + } finally { + cleanup(base); + } + }); + + it("gsd_replan_slice and gsd_slice_replan work end-to-end", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + const canonicalTool = server.tools.find((t) => t.name === "gsd_replan_slice"); + const aliasTool = server.tools.find((t) => t.name === "gsd_slice_replan"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + assert.ok(taskTool, "task completion tool should be registered"); + assert.ok(canonicalTool, "slice replanning tool should be registered"); + assert.ok(aliasTool, "slice replanning alias should be registered"); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M099", + title: "Slice replanning", + vision: "Drive replan parity over MCP.", + slices: [ + { + sliceId: "S09", + title: "Replan slice", + risk: "medium", + depends: [], + demo: "Slice replans after a blocker task completes.", + goal: "Prepare replan state.", + successCriteria: "Plan and replan artifacts update over MCP.", + proofLevel: "integration", + integrationClosure: "Replan uses the shared executor path.", + observabilityImpact: "Tests cover replan artifacts.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M099", + sliceId: "S09", + goal: "Plan a slice that will be replanned.", + tasks: [ + { + taskId: "T09", + title: "Blocker task", + description: "Finish the blocker-discovery task.", + estimate: "5m", + files: ["src/blocker.ts"], + verify: "node --test", + inputs: ["M099-ROADMAP.md"], + expectedOutput: ["T09-SUMMARY.md"], + }, + { + taskId: "T10", + title: "Pending task", + description: "Original follow-up task.", + estimate: "10m", + files: ["src/pending.ts"], + verify: "node --test", + inputs: ["S09-PLAN.md"], + expectedOutput: ["Updated plan"], + }, + ], + }); + await taskTool!.handler({ + projectDir: base, + milestoneId: "M099", + sliceId: "S09", + taskId: "T09", + oneLiner: "Completed blocker task", + narrative: "Prepared the slice for replanning.", + verification: "node --test", + }); + + const canonicalResult = await canonicalTool!.handler({ + projectDir: base, + milestoneId: "M099", + sliceId: "S09", + blockerTaskId: "T09", + blockerDescription: "Original approach is no longer viable.", + whatChanged: "Updated the remaining task and added remediation work.", + updatedTasks: [ + { + taskId: "T10", + title: "Pending task (updated)", + description: "Updated follow-up task after replanning.", + estimate: "15m", + files: ["src/pending.ts", "src/replanned.ts"], + verify: "node --test", + inputs: ["S09-PLAN.md"], + expectedOutput: ["Updated plan"], + }, + { + taskId: "T11", + title: "Remediation task", + description: "New task introduced by the replan.", + estimate: "20m", + files: ["src/remediation.ts"], + verify: "node --test", + inputs: ["S09-REPLAN.md"], + expectedOutput: ["Remediation patch"], + }, + ], + removedTaskIds: [], + }); + assert.match((canonicalResult as any).content[0].text as string, /Replanned slice S09/); + + const aliasResult = await aliasTool!.handler({ + projectDir: base, + milestoneId: "M099", + sliceId: "S09", + blockerTaskId: "T09", + blockerDescription: "Alias path confirms the same replan flow.", + whatChanged: "Removed the remediation task after the alias check.", + updatedTasks: [ + { + taskId: "T10", + title: "Pending task (updated again)", + description: "Alias adjusted the remaining pending task.", + estimate: "12m", + files: ["src/pending.ts"], + verify: "node --test", + inputs: ["S09-PLAN.md"], + expectedOutput: ["Updated plan"], + }, + ], + removedTaskIds: ["T11"], + }); + assert.match((aliasResult as any).content[0].text as string, /Replanned slice S09/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M099", "slices", "S09", "S09-REPLAN.md")), + "replan artifact should exist on disk", + ); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M099", "slices", "S09", "S09-PLAN.md")), + "updated plan should exist on disk", + ); + const removedTask = _getAdapter()!.prepare( + "SELECT id FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?", + ).get("M099", "S09", "T11"); + assert.equal(removedTask, undefined, "alias should remove the replanned task"); + } finally { + cleanup(base); + } + }); + + it("gsd_slice_complete and gsd_complete_slice work end-to-end", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + const canonicalTool = server.tools.find((t) => t.name === "gsd_slice_complete"); + const aliasTool = server.tools.find((t) => t.name === "gsd_complete_slice"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + assert.ok(taskTool, "task completion tool should be registered"); + assert.ok(canonicalTool, "slice completion tool should be registered"); + assert.ok(aliasTool, "slice completion alias should be registered"); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M003", + title: "Demo milestone", + vision: "Prepare canonical slice completion state.", + slices: [ + { + sliceId: "S03", + title: "Demo Slice", + risk: "medium", + depends: [], + demo: "Canonical slice completes through MCP.", + goal: "Seed workflow state.", + successCriteria: "Slice summary and UAT files are written.", + proofLevel: "integration", + integrationClosure: "Planning and completion share the MCP bridge.", + observabilityImpact: "Workflow tests cover canonical completion.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M003", + sliceId: "S03", + goal: "Complete canonical slice over MCP.", + tasks: [ + { + taskId: "T03", + title: "Canonical task", + description: "Seed a completed task for slice completion.", + estimate: "5m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M003-ROADMAP.md"], + expectedOutput: ["S03-SUMMARY.md", "S03-UAT.md"], + }, + ], + }); + await taskTool!.handler({ + projectDir: base, + milestoneId: "M003", + sliceId: "S03", + taskId: "T03", + oneLiner: "Completed canonical task", + narrative: "Prepared the canonical slice for completion.", + verification: "node --test", + }); + + const canonicalResult = await canonicalTool!.handler({ + projectDir: base, + milestoneId: "M003", + sliceId: "S03", + sliceTitle: "Demo Slice", + oneLiner: "Completed canonical slice", + narrative: "Did the slice work", + verification: "npm test", + uatContent: "## UAT\n\nPASS", + }); + assert.match((canonicalResult as any).content[0].text as string, /Completed slice S03/); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M004", + title: "Alias milestone", + vision: "Prepare alias slice completion state.", + slices: [ + { + sliceId: "S04", + title: "Alias Slice", + risk: "medium", + depends: [], + demo: "Alias slice completes through MCP.", + goal: "Seed alias workflow state.", + successCriteria: "Alias summary and UAT files are written.", + proofLevel: "integration", + integrationClosure: "Alias reaches the shared slice executor.", + observabilityImpact: "Workflow tests cover alias completion.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M004", + sliceId: "S04", + goal: "Complete alias slice over MCP.", + tasks: [ + { + taskId: "T04", + title: "Alias task", + description: "Seed a completed task for alias slice completion.", + estimate: "5m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M004-ROADMAP.md"], + expectedOutput: ["S04-SUMMARY.md", "S04-UAT.md"], + }, + ], + }); + await taskTool!.handler({ + projectDir: base, + milestoneId: "M004", + sliceId: "S04", + taskId: "T04", + oneLiner: "Completed alias task", + narrative: "Prepared the alias slice for completion.", + verification: "node --test", + }); + + const aliasResult = await aliasTool!.handler({ + projectDir: base, + milestoneId: "M004", + sliceId: "S04", + sliceTitle: "Alias Slice", + oneLiner: "Completed alias slice", + narrative: "Did the slice work via alias", + verification: "npm test", + uatContent: "## UAT\n\nPASS", + }); + assert.match((aliasResult as any).content[0].text as string, /Completed slice S04/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M004", "slices", "S04", "S04-SUMMARY.md")), + "alias should write slice summary to disk", + ); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M004", "slices", "S04", "S04-UAT.md")), + "alias should write slice UAT to disk", + ); + } finally { + cleanup(base); + } + }); + + it("gsd_validate_milestone and gsd_milestone_complete work end-to-end", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + const completeSliceTool = server.tools.find((t) => t.name === "gsd_slice_complete"); + const validateTool = server.tools.find((t) => t.name === "gsd_validate_milestone"); + const completeMilestoneAlias = server.tools.find((t) => t.name === "gsd_milestone_complete"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + assert.ok(taskTool, "task completion tool should be registered"); + assert.ok(completeSliceTool, "slice completion tool should be registered"); + assert.ok(validateTool, "milestone validation tool should be registered"); + assert.ok(completeMilestoneAlias, "milestone completion alias should be registered"); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M005", + title: "Milestone lifecycle", + vision: "Drive validation and completion over MCP.", + slices: [ + { + sliceId: "S05", + title: "Lifecycle slice", + risk: "medium", + depends: [], + demo: "Milestone can validate and complete.", + goal: "Seed milestone completion state.", + successCriteria: "Summary and validation artifacts are written.", + proofLevel: "integration", + integrationClosure: "Lifecycle tools share the MCP bridge.", + observabilityImpact: "Tests cover milestone end-to-end behavior.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M005", + sliceId: "S05", + goal: "Prepare a complete milestone.", + tasks: [ + { + taskId: "T05", + title: "Lifecycle task", + description: "Seed a fully completed slice.", + estimate: "10m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M005-ROADMAP.md"], + expectedOutput: ["M005-VALIDATION.md", "M005-SUMMARY.md"], + }, + ], + }); + await taskTool!.handler({ + projectDir: base, + milestoneId: "M005", + sliceId: "S05", + taskId: "T05", + oneLiner: "Completed lifecycle task", + narrative: "Prepared the milestone for closure.", + verification: "node --test", + }); + await completeSliceTool!.handler({ + projectDir: base, + milestoneId: "M005", + sliceId: "S05", + sliceTitle: "Lifecycle Slice", + oneLiner: "Completed lifecycle slice", + narrative: "Closed the milestone slice.", + verification: "node --test", + uatContent: "## UAT\n\nPASS", + }); + + const validationResult = await validateTool!.handler({ + projectDir: base, + milestoneId: "M005", + verdict: "pass", + remediationRound: 0, + successCriteriaChecklist: "- [x] Lifecycle verified", + sliceDeliveryAudit: "| Slice | Verdict |\n| --- | --- |\n| S05 | pass |", + crossSliceIntegration: "No cross-slice mismatches found.", + requirementCoverage: "No requirement gaps remain.", + verdictRationale: "The milestone delivered its scope.", + }); + assert.match((validationResult as any).content[0].text as string, /Validated milestone M005/); + + const completionResult = await completeMilestoneAlias!.handler({ + projectDir: base, + milestoneId: "M005", + title: "Milestone lifecycle", + oneLiner: "Milestone closed successfully", + narrative: "Validation passed and all slices were complete.", + verificationPassed: true, + }); + assert.match((completionResult as any).content[0].text as string, /Completed milestone M005/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M005", "M005-VALIDATION.md")), + "validation artifact should exist on disk", + ); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M005", "M005-SUMMARY.md")), + "milestone summary should exist on disk", + ); + } finally { + cleanup(base); + } + }); + + it("gsd_reassess_roadmap, gsd_roadmap_reassess, and gsd_save_gate_result work end-to-end", async () => { + const base = makeTmpBase(); + try { + const server = makeMockServer(); + registerWorkflowTools(server as any); + const milestoneTool = server.tools.find((t) => t.name === "gsd_plan_milestone"); + const sliceTool = server.tools.find((t) => t.name === "gsd_plan_slice"); + const taskTool = server.tools.find((t) => t.name === "gsd_task_complete"); + const completeSliceTool = server.tools.find((t) => t.name === "gsd_slice_complete"); + const reassessTool = server.tools.find((t) => t.name === "gsd_reassess_roadmap"); + const reassessAlias = server.tools.find((t) => t.name === "gsd_roadmap_reassess"); + const gateTool = server.tools.find((t) => t.name === "gsd_save_gate_result"); + assert.ok(milestoneTool, "milestone planning tool should be registered"); + assert.ok(sliceTool, "slice planning tool should be registered"); + assert.ok(taskTool, "task completion tool should be registered"); + assert.ok(completeSliceTool, "slice completion tool should be registered"); + assert.ok(reassessTool, "roadmap reassessment tool should be registered"); + assert.ok(reassessAlias, "roadmap reassessment alias should be registered"); + assert.ok(gateTool, "gate result tool should be registered"); + + await milestoneTool!.handler({ + projectDir: base, + milestoneId: "M006", + title: "Roadmap reassessment", + vision: "Drive gate results and reassessment over MCP.", + slices: [ + { + sliceId: "S06", + title: "Completed slice", + risk: "medium", + depends: [], + demo: "Completed slice triggers reassessment.", + goal: "Seed reassessment state.", + successCriteria: "Assessment and roadmap artifacts are written.", + proofLevel: "integration", + integrationClosure: "Roadmap updates share the MCP bridge.", + observabilityImpact: "Tests cover reassessment behavior.", + }, + { + sliceId: "S07", + title: "Follow-up slice", + risk: "low", + depends: ["S06"], + demo: "Follow-up slice remains pending.", + goal: "Leave room for roadmap edits.", + successCriteria: "Roadmap mutation succeeds.", + proofLevel: "integration", + integrationClosure: "Pending slice can be modified after reassessment.", + observabilityImpact: "Tests observe roadmap mutation output.", + }, + ], + }); + await sliceTool!.handler({ + projectDir: base, + milestoneId: "M006", + sliceId: "S06", + goal: "Complete the first slice.", + tasks: [ + { + taskId: "T06", + title: "Seed completed slice", + description: "Prepare gate and reassessment state.", + estimate: "10m", + files: ["packages/mcp-server/src/workflow-tools.ts"], + verify: "node --test", + inputs: ["M006-ROADMAP.md"], + expectedOutput: ["S06-ASSESSMENT.md", "M006-ROADMAP.md"], + }, + ], + }); + + const gateResult = await gateTool!.handler({ + projectDir: base, + milestoneId: "M006", + sliceId: "S06", + gateId: "Q3", + verdict: "pass", + rationale: "Threat surface is covered.", + findings: "No new attack surface was introduced.", + }); + assert.match((gateResult as any).content[0].text as string, /Gate Q3 result saved/); + const gateRows = _getAdapter()!.prepare( + "SELECT status, verdict, rationale FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ?", + ).all("M006", "S06", "Q3") as Array>; + assert.equal(gateRows.length, 1); + assert.equal(gateRows[0]["status"], "complete"); + assert.equal(gateRows[0]["verdict"], "pass"); + + await taskTool!.handler({ + projectDir: base, + milestoneId: "M006", + sliceId: "S06", + taskId: "T06", + oneLiner: "Completed reassessment task", + narrative: "Prepared the slice for reassessment.", + verification: "node --test", + }); + await completeSliceTool!.handler({ + projectDir: base, + milestoneId: "M006", + sliceId: "S06", + sliceTitle: "Completed slice", + oneLiner: "Completed reassessment slice", + narrative: "Closed the completed slice before reassessment.", + verification: "node --test", + uatContent: "## UAT\n\nPASS", + }); + + const reassessResult = await reassessTool!.handler({ + projectDir: base, + milestoneId: "M006", + completedSliceId: "S06", + verdict: "roadmap-adjusted", + assessment: "Insert remediation work after the completed slice.", + sliceChanges: { + modified: [ + { + sliceId: "S07", + title: "Follow-up slice (adjusted)", + risk: "medium", + depends: ["S06"], + demo: "Adjusted demo", + }, + ], + added: [ + { + sliceId: "S08", + title: "Remediation slice", + risk: "high", + depends: ["S07"], + demo: "Remediation demo", + }, + ], + removed: [], + }, + }); + assert.match((reassessResult as any).content[0].text as string, /Reassessed roadmap for milestone M006 after S06/); + + const reassessAliasResult = await reassessAlias!.handler({ + projectDir: base, + milestoneId: "M006", + completedSliceId: "S06", + verdict: "roadmap-confirmed", + assessment: "No further changes needed after the first reassessment.", + sliceChanges: { + modified: [], + added: [], + removed: [], + }, + }); + assert.match((reassessAliasResult as any).content[0].text as string, /Reassessed roadmap for milestone M006 after S06/); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M006", "slices", "S06", "S06-ASSESSMENT.md")), + "assessment artifact should exist on disk", + ); + assert.ok( + existsSync(join(base, ".gsd", "milestones", "M006", "M006-ROADMAP.md")), + "roadmap artifact should exist on disk", + ); + } finally { + cleanup(base); + } + }); +}); + +describe("URL scheme regex — Windows drive letter safety", () => { + // This is the regex used in getWriteGateModuleCandidates() and + // getWorkflowExecutorModuleCandidates() to reject non-file URL schemes. + // It must NOT match single-letter Windows drive prefixes (C:, D:, etc.). + const urlSchemeRegex = /^[a-z]{2,}:/i; + + it("rejects multi-letter URL schemes", () => { + assert.ok(urlSchemeRegex.test("http://example.com"), "http: should match"); + assert.ok(urlSchemeRegex.test("https://example.com"), "https: should match"); + assert.ok(urlSchemeRegex.test("ftp://files.example.com"), "ftp: should match"); + assert.ok(urlSchemeRegex.test("file:///C:/Users"), "file: should match"); + assert.ok(urlSchemeRegex.test("node:fs"), "node: should match"); + }); + + it("allows single-letter Windows drive prefixes", () => { + assert.ok(!urlSchemeRegex.test("C:\\Users\\user\\project"), "C:\\ should not match"); + assert.ok(!urlSchemeRegex.test("D:\\other\\path"), "D:\\ should not match"); + assert.ok(!urlSchemeRegex.test("c:\\lowercase\\drive"), "c:\\ should not match"); + assert.ok(!urlSchemeRegex.test("E:/forward/slash/path"), "E:/ should not match"); + }); + + it("allows bare filesystem paths", () => { + assert.ok(!urlSchemeRegex.test("/usr/local/lib/module.js"), "unix absolute path should not match"); + assert.ok(!urlSchemeRegex.test("./relative/path.js"), "relative path should not match"); + assert.ok(!urlSchemeRegex.test("../parent/path.js"), "parent relative path should not match"); + }); +}); diff --git a/packages/mcp-server/src/workflow-tools.ts b/packages/mcp-server/src/workflow-tools.ts new file mode 100644 index 000000000..9abbddbeb --- /dev/null +++ b/packages/mcp-server/src/workflow-tools.ts @@ -0,0 +1,1413 @@ +/** + * Workflow MCP tools — exposes the core GSD mutation/read handlers over MCP. + */ + +import { isAbsolute, relative, resolve } from "node:path"; +import { pathToFileURL } from "node:url"; +import { z } from "zod"; + +type WorkflowToolExecutors = { + SUPPORTED_SUMMARY_ARTIFACT_TYPES: readonly string[]; + executeMilestoneStatus: (params: { milestoneId: string }, basePath?: string) => Promise; + executePlanMilestone: ( + params: { + milestoneId: string; + title: string; + vision: string; + slices: Array<{ + sliceId: string; + title: string; + risk: string; + depends: string[]; + demo: string; + goal: string; + successCriteria: string; + proofLevel: string; + integrationClosure: string; + observabilityImpact: string; + }>; + status?: string; + dependsOn?: string[]; + successCriteria?: string[]; + keyRisks?: Array<{ risk: string; whyItMatters: string }>; + proofStrategy?: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>; + verificationContract?: string; + verificationIntegration?: string; + verificationOperational?: string; + verificationUat?: string; + definitionOfDone?: string[]; + requirementCoverage?: string; + boundaryMapMarkdown?: string; + }, + basePath?: string, + ) => Promise; + executePlanSlice: ( + params: { + milestoneId: string; + sliceId: string; + goal: string; + tasks: Array<{ + taskId: string; + title: string; + description: string; + estimate: string; + files: string[]; + verify: string; + inputs: string[]; + expectedOutput: string[]; + observabilityImpact?: string; + }>; + successCriteria?: string; + proofLevel?: string; + integrationClosure?: string; + observabilityImpact?: string; + }, + basePath?: string, + ) => Promise; + executeReplanSlice: ( + params: { + milestoneId: string; + sliceId: string; + blockerTaskId: string; + blockerDescription: string; + whatChanged: string; + updatedTasks: Array<{ + taskId: string; + title: string; + description: string; + estimate: string; + files: string[]; + verify: string; + inputs: string[]; + expectedOutput: string[]; + fullPlanMd?: string; + }>; + removedTaskIds: string[]; + }, + basePath?: string, + ) => Promise; + executeSliceComplete: ( + params: { + sliceId: string; + milestoneId: string; + sliceTitle: string; + oneLiner: string; + narrative: string; + verification: string; + uatContent: string; + deviations?: string; + knownLimitations?: string; + followUps?: string; + keyFiles?: string[] | string; + keyDecisions?: string[] | string; + patternsEstablished?: string[] | string; + observabilitySurfaces?: string[] | string; + provides?: string[] | string; + requirementsSurfaced?: string[] | string; + drillDownPaths?: string[] | string; + affects?: string[] | string; + requirementsAdvanced?: Array<{ id: string; how: string } | string>; + requirementsValidated?: Array<{ id: string; proof: string } | string>; + requirementsInvalidated?: Array<{ id: string; what: string } | string>; + filesModified?: Array<{ path: string; description: string } | string>; + requires?: Array<{ slice: string; provides: string } | string>; + }, + basePath?: string, + ) => Promise; + executeCompleteMilestone: ( + params: { + milestoneId: string; + title: string; + oneLiner: string; + narrative: string; + verificationPassed: boolean; + successCriteriaResults?: string; + definitionOfDoneResults?: string; + requirementOutcomes?: string; + keyDecisions?: string[]; + keyFiles?: string[]; + lessonsLearned?: string[]; + followUps?: string; + deviations?: string; + }, + basePath?: string, + ) => Promise; + executeValidateMilestone: ( + params: { + milestoneId: string; + verdict: "pass" | "needs-attention" | "needs-remediation"; + remediationRound: number; + successCriteriaChecklist: string; + sliceDeliveryAudit: string; + crossSliceIntegration: string; + requirementCoverage: string; + verificationClasses?: string; + verdictRationale: string; + remediationPlan?: string; + }, + basePath?: string, + ) => Promise; + executeReassessRoadmap: ( + params: { + milestoneId: string; + completedSliceId: string; + verdict: string; + assessment: string; + sliceChanges: { + modified: Array<{ + sliceId: string; + title: string; + risk?: string; + depends?: string[]; + demo?: string; + }>; + added: Array<{ + sliceId: string; + title: string; + risk?: string; + depends?: string[]; + demo?: string; + }>; + removed: string[]; + }; + }, + basePath?: string, + ) => Promise; + executeSaveGateResult: ( + params: { + milestoneId: string; + sliceId: string; + gateId: string; + taskId?: string; + verdict: "pass" | "flag" | "omitted"; + rationale: string; + findings?: string; + }, + basePath?: string, + ) => Promise; + executeSummarySave: ( + params: { + milestone_id: string; + slice_id?: string; + task_id?: string; + artifact_type: string; + content: string; + }, + basePath?: string, + ) => Promise; + executeTaskComplete: ( + params: { + taskId: string; + sliceId: string; + milestoneId: string; + oneLiner: string; + narrative: string; + verification: string; + deviations?: string; + knownIssues?: string; + keyFiles?: string[]; + keyDecisions?: string[]; + blockerDiscovered?: boolean; + verificationEvidence?: Array< + { command: string; exitCode: number; verdict: string; durationMs: number } | string + >; + }, + basePath?: string, + ) => Promise; +}; + +type WorkflowWriteGateModule = { + loadWriteGateSnapshot: (basePath?: string) => { + verifiedDepthMilestones: string[]; + activeQueuePhase: boolean; + pendingGateId: string | null; + }; + shouldBlockPendingGateInSnapshot: ( + snapshot: { + verifiedDepthMilestones: string[]; + activeQueuePhase: boolean; + pendingGateId: string | null; + }, + toolName: string, + milestoneId: string | null, + queuePhaseActive?: boolean, + ) => { block: boolean; reason?: string }; + shouldBlockQueueExecutionInSnapshot: ( + snapshot: { + verifiedDepthMilestones: string[]; + activeQueuePhase: boolean; + pendingGateId: string | null; + }, + toolName: string, + input: string, + queuePhaseActive?: boolean, + ) => { block: boolean; reason?: string }; +}; + +type WorkflowDbBootstrapModule = { + ensureDbOpen: (basePath?: string) => Promise; +}; + +let workflowToolExecutorsPromise: Promise | null = null; +let workflowExecutionQueue: Promise = Promise.resolve(); +let workflowWriteGatePromise: Promise | null = null; + +function getAllowedProjectRoot(env: NodeJS.ProcessEnv = process.env): string | null { + const configuredRoot = env.GSD_WORKFLOW_PROJECT_ROOT?.trim(); + return configuredRoot ? resolve(configuredRoot) : null; +} + +function isWithinRoot(candidatePath: string, rootPath: string): boolean { + const rel = relative(rootPath, candidatePath); + return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); +} + +function validateProjectDir(projectDir: string, env: NodeJS.ProcessEnv = process.env): string { + if (!isAbsolute(projectDir)) { + throw new Error(`projectDir must be an absolute path. Received: ${projectDir}`); + } + + const resolvedProjectDir = resolve(projectDir); + const allowedRoot = getAllowedProjectRoot(env); + if (allowedRoot && !isWithinRoot(resolvedProjectDir, allowedRoot)) { + throw new Error( + `projectDir must stay within the configured workflow project root. Received: ${resolvedProjectDir}; allowed root: ${allowedRoot}`, + ); + } + + return resolvedProjectDir; +} + +function parseToolArgs(schema: z.ZodType, args: Record): T { + return schema.parse(args); +} + +function parseWorkflowArgs( + schema: z.ZodType, + args: Record, +): T { + const parsed = parseToolArgs(schema, args); + return { + ...parsed, + projectDir: validateProjectDir(parsed.projectDir), + }; +} + +function isWorkflowToolExecutors(value: unknown): value is WorkflowToolExecutors { + if (!value || typeof value !== "object") return false; + const record = value as Record; + const functionExports = [ + "executeMilestoneStatus", + "executePlanMilestone", + "executePlanSlice", + "executeReplanSlice", + "executeSliceComplete", + "executeCompleteMilestone", + "executeValidateMilestone", + "executeReassessRoadmap", + "executeSaveGateResult", + "executeSummarySave", + "executeTaskComplete", + ]; + + return Array.isArray(record.SUPPORTED_SUMMARY_ARTIFACT_TYPES) && + functionExports.every((key) => typeof record[key] === "function"); +} + +function getSupportedSummaryArtifactTypes(executors: WorkflowToolExecutors): readonly string[] { + return executors.SUPPORTED_SUMMARY_ARTIFACT_TYPES; +} + +function getWriteGateModuleCandidates(): string[] { + const candidates: string[] = []; + const explicitModule = process.env.GSD_WORKFLOW_WRITE_GATE_MODULE?.trim(); + if (explicitModule) { + if (/^[a-z]{2,}:/i.test(explicitModule) && !explicitModule.startsWith("file:")) { + throw new Error("GSD_WORKFLOW_WRITE_GATE_MODULE only supports file: URLs or filesystem paths."); + } + candidates.push(explicitModule.startsWith("file:") ? explicitModule : toFileUrl(explicitModule)); + } + + candidates.push( + new URL("../../../src/resources/extensions/gsd/bootstrap/write-gate.js", import.meta.url).href, + new URL("../../../dist/resources/extensions/gsd/bootstrap/write-gate.js", import.meta.url).href, + new URL("../../../src/resources/extensions/gsd/bootstrap/write-gate.ts", import.meta.url).href, + ); + + return [...new Set(candidates)]; +} + +function toFileUrl(modulePath: string): string { + return pathToFileURL(resolve(modulePath)).href; +} + +/** @internal — exported for testing only */ +export function _buildImportCandidates(relativePath: string): string[] { + // Build candidate paths: try the given path first, then swap src/<->dist/ + // and try .ts extension. This handles both dev (tsx from src/) and prod + // (compiled from dist/) execution contexts. + const candidates: string[] = [relativePath]; + const swapped = relativePath.includes("/src/") + ? relativePath.replace("/src/", "/dist/") + : relativePath.includes("/dist/") + ? relativePath.replace("/dist/", "/src/") + : null; + if (swapped) candidates.push(swapped); + // Also try .ts variants for dev-mode tsx execution + if (relativePath.endsWith(".js")) { + candidates.push(relativePath.replace(/\.js$/, ".ts")); + if (swapped) candidates.push(swapped.replace(/\.js$/, ".ts")); + } + return candidates; +} + +async function importLocalModule(relativePath: string): Promise { + const candidates = _buildImportCandidates(relativePath) + .map((p) => new URL(p, import.meta.url).href); + + let lastErr: unknown; + for (const candidate of candidates) { + try { + return await import(candidate) as T; + } catch (err) { + lastErr = err; + } + } + throw lastErr; +} + +function getWorkflowExecutorModuleCandidates(env: NodeJS.ProcessEnv = process.env): string[] { + const candidates: string[] = []; + const explicitModule = env.GSD_WORKFLOW_EXECUTORS_MODULE?.trim(); + if (explicitModule) { + if (/^[a-z]{2,}:/i.test(explicitModule) && !explicitModule.startsWith("file:")) { + throw new Error("GSD_WORKFLOW_EXECUTORS_MODULE only supports file: URLs or filesystem paths."); + } + candidates.push(explicitModule.startsWith("file:") ? explicitModule : toFileUrl(explicitModule)); + } + + candidates.push( + new URL("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.js", import.meta.url).href, + new URL("../../../dist/resources/extensions/gsd/tools/workflow-tool-executors.js", import.meta.url).href, + new URL("../../../src/resources/extensions/gsd/tools/workflow-tool-executors.ts", import.meta.url).href, + ); + + return [...new Set(candidates)]; +} + +async function getWorkflowToolExecutors(): Promise { + if (!workflowToolExecutorsPromise) { + workflowToolExecutorsPromise = (async () => { + const attempts: string[] = []; + for (const candidate of getWorkflowExecutorModuleCandidates()) { + try { + const loaded = await import(candidate); + if (isWorkflowToolExecutors(loaded)) { + return loaded; + } + attempts.push(`${candidate} (module shape mismatch)`); + } catch (err) { + attempts.push(`${candidate} (${err instanceof Error ? err.message : String(err)})`); + } + } + + throw new Error( + "Unable to load GSD workflow executor bridge for MCP mutation tools. " + + "Set GSD_WORKFLOW_EXECUTORS_MODULE to an importable workflow-tool-executors module, " + + "or run the MCP server from a GSD checkout that includes src/resources/extensions/gsd/tools/workflow-tool-executors.(js|ts). " + + `Attempts: ${attempts.join("; ")}`, + ); + })(); + } + return workflowToolExecutorsPromise; +} + +async function getWorkflowWriteGateModule(): Promise { + if (!workflowWriteGatePromise) { + workflowWriteGatePromise = (async () => { + const attempts: string[] = []; + for (const candidate of getWriteGateModuleCandidates()) { + try { + const loaded = await import(candidate); + if ( + loaded && + typeof loaded.loadWriteGateSnapshot === "function" && + typeof loaded.shouldBlockPendingGateInSnapshot === "function" && + typeof loaded.shouldBlockQueueExecutionInSnapshot === "function" + ) { + return loaded as WorkflowWriteGateModule; + } + attempts.push(`${candidate} (module shape mismatch)`); + } catch (err) { + attempts.push(`${candidate} (${err instanceof Error ? err.message : String(err)})`); + } + } + + throw new Error( + "Unable to load GSD write-gate bridge for workflow MCP tools. " + + `Attempts: ${attempts.join("; ")}`, + ); + })(); + } + return workflowWriteGatePromise; +} + +interface McpToolServer { + tool( + name: string, + description: string, + params: Record, + handler: (args: Record) => Promise, + ): unknown; +} + +export const WORKFLOW_TOOL_NAMES = [ + "gsd_decision_save", + "gsd_save_decision", + "gsd_requirement_update", + "gsd_update_requirement", + "gsd_requirement_save", + "gsd_save_requirement", + "gsd_milestone_generate_id", + "gsd_generate_milestone_id", + "gsd_plan_milestone", + "gsd_plan_slice", + "gsd_plan_task", + "gsd_task_plan", + "gsd_replan_slice", + "gsd_slice_replan", + "gsd_slice_complete", + "gsd_complete_slice", + "gsd_skip_slice", + "gsd_complete_milestone", + "gsd_milestone_complete", + "gsd_validate_milestone", + "gsd_milestone_validate", + "gsd_reassess_roadmap", + "gsd_roadmap_reassess", + "gsd_save_gate_result", + "gsd_summary_save", + "gsd_task_complete", + "gsd_complete_task", + "gsd_milestone_status", + "gsd_journal_query", +] as const; + +async function runSerializedWorkflowOperation(fn: () => Promise): Promise { + // The shared DB adapter and workflow log base path are process-global, so + // workflow MCP mutations must not overlap within a single server process. + const prior = workflowExecutionQueue; + let release!: () => void; + workflowExecutionQueue = new Promise((resolve) => { + release = resolve; + }); + + await prior; + try { + return await fn(); + } finally { + release(); + } +} + +async function runSerializedWorkflowDbOperation( + projectDir: string, + fn: () => Promise, +): Promise { + return runSerializedWorkflowOperation(async () => { + const { ensureDbOpen } = await importLocalModule( + "../../../src/resources/extensions/gsd/bootstrap/dynamic-tools.js", + ); + const dbAvailable = await ensureDbOpen(projectDir); + if (!dbAvailable) { + throw new Error("GSD database is not available"); + } + return fn(); + }); +} + +async function enforceWorkflowWriteGate( + toolName: string, + projectDir: string, + milestoneId: string | null = null, +): Promise { + const writeGate = await getWorkflowWriteGateModule(); + const snapshot = writeGate.loadWriteGateSnapshot(projectDir); + const pendingGate = writeGate.shouldBlockPendingGateInSnapshot( + snapshot, + toolName, + milestoneId, + snapshot.activeQueuePhase, + ); + if (pendingGate.block) { + throw new Error(pendingGate.reason ?? "workflow tool blocked by pending discussion gate"); + } + + const queueGuard = writeGate.shouldBlockQueueExecutionInSnapshot( + snapshot, + toolName, + "", + snapshot.activeQueuePhase, + ); + if (queueGuard.block) { + throw new Error(queueGuard.reason ?? "workflow tool blocked during queue mode"); + } +} + +async function handleTaskComplete( + projectDir: string, + args: Omit, "projectDir">, +): Promise { + await enforceWorkflowWriteGate("gsd_task_complete", projectDir, args.milestoneId); + const { + taskId, + sliceId, + milestoneId, + oneLiner, + narrative, + verification, + deviations, + knownIssues, + keyFiles, + keyDecisions, + blockerDiscovered, + verificationEvidence, + } = args; + const { executeTaskComplete } = await getWorkflowToolExecutors(); + return runSerializedWorkflowOperation(() => + executeTaskComplete( + { + taskId, + sliceId, + milestoneId, + oneLiner, + narrative, + verification, + deviations, + knownIssues, + keyFiles, + keyDecisions, + blockerDiscovered, + verificationEvidence, + }, + projectDir, + ), + ); +} + +async function handleSliceComplete( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_slice_complete", projectDir, args.milestoneId); + const { executeSliceComplete } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeSliceComplete(params, projectDir)); +} + +async function handleReplanSlice( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_replan_slice", projectDir, args.milestoneId); + const { executeReplanSlice } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeReplanSlice(params, projectDir)); +} + +async function handleCompleteMilestone( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_complete_milestone", projectDir, args.milestoneId); + const { executeCompleteMilestone } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeCompleteMilestone(params, projectDir)); +} + +async function handleValidateMilestone( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_validate_milestone", projectDir, args.milestoneId); + const { executeValidateMilestone } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeValidateMilestone(params, projectDir)); +} + +async function handleReassessRoadmap( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_reassess_roadmap", projectDir, args.milestoneId); + const { executeReassessRoadmap } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeReassessRoadmap(params, projectDir)); +} + +async function handleSaveGateResult( + projectDir: string, + args: z.infer, +): Promise { + await enforceWorkflowWriteGate("gsd_save_gate_result", projectDir, args.milestoneId); + const { executeSaveGateResult } = await getWorkflowToolExecutors(); + const { projectDir: _projectDir, ...params } = args; + return runSerializedWorkflowOperation(() => executeSaveGateResult(params, projectDir)); +} + +async function ensureMilestoneDbRow(milestoneId: string): Promise { + try { + const { insertMilestone } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js"); + insertMilestone({ id: milestoneId, status: "queued" }); + } catch { + // Ignore pre-existing rows or transient DB availability issues. + } +} + +const projectDirParam = z.string().describe("Absolute path to the project directory within the configured workflow root"); + +const planMilestoneParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + title: z.string().describe("Milestone title"), + vision: z.string().describe("Milestone vision"), + slices: z.array(z.object({ + sliceId: z.string(), + title: z.string(), + risk: z.string(), + depends: z.array(z.string()), + demo: z.string(), + goal: z.string(), + successCriteria: z.string(), + proofLevel: z.string(), + integrationClosure: z.string(), + observabilityImpact: z.string(), + })).describe("Planned slices for the milestone"), + status: z.string().optional().describe("Milestone status"), + dependsOn: z.array(z.string()).optional().describe("Milestone dependencies"), + successCriteria: z.array(z.string()).optional().describe("Top-level success criteria bullets"), + keyRisks: z.array(z.object({ + risk: z.string(), + whyItMatters: z.string(), + })).optional().describe("Structured risk entries"), + proofStrategy: z.array(z.object({ + riskOrUnknown: z.string(), + retireIn: z.string(), + whatWillBeProven: z.string(), + })).optional().describe("Structured proof strategy entries"), + verificationContract: z.string().optional(), + verificationIntegration: z.string().optional(), + verificationOperational: z.string().optional(), + verificationUat: z.string().optional(), + definitionOfDone: z.array(z.string()).optional(), + requirementCoverage: z.string().optional(), + boundaryMapMarkdown: z.string().optional(), +}; +const planMilestoneSchema = z.object(planMilestoneParams); + +const planSliceParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + sliceId: z.string().describe("Slice ID (e.g. S01)"), + goal: z.string().describe("Slice goal"), + tasks: z.array(z.object({ + taskId: z.string(), + title: z.string(), + description: z.string(), + estimate: z.string(), + files: z.array(z.string()), + verify: z.string(), + inputs: z.array(z.string()), + expectedOutput: z.array(z.string()), + observabilityImpact: z.string().optional(), + })).describe("Planned tasks for the slice"), + successCriteria: z.string().optional(), + proofLevel: z.string().optional(), + integrationClosure: z.string().optional(), + observabilityImpact: z.string().optional(), +}; +const planSliceSchema = z.object(planSliceParams); + +const completeMilestoneParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + title: z.string().describe("Milestone title"), + oneLiner: z.string().describe("One-sentence summary of what the milestone achieved"), + narrative: z.string().describe("Detailed narrative of what happened during the milestone"), + verificationPassed: z.boolean().describe("Must be true after milestone verification succeeds"), + successCriteriaResults: z.string().optional(), + definitionOfDoneResults: z.string().optional(), + requirementOutcomes: z.string().optional(), + keyDecisions: z.array(z.string()).optional(), + keyFiles: z.array(z.string()).optional(), + lessonsLearned: z.array(z.string()).optional(), + followUps: z.string().optional(), + deviations: z.string().optional(), +}; +const completeMilestoneSchema = z.object(completeMilestoneParams); + +const validateMilestoneParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + verdict: z.enum(["pass", "needs-attention", "needs-remediation"]).describe("Validation verdict"), + remediationRound: z.number().describe("Remediation round (0 for first validation)"), + successCriteriaChecklist: z.string().describe("Markdown checklist of success criteria with evidence"), + sliceDeliveryAudit: z.string().describe("Markdown auditing each slice's claimed vs delivered output"), + crossSliceIntegration: z.string().describe("Markdown describing cross-slice issues or closure"), + requirementCoverage: z.string().describe("Markdown describing requirement coverage and gaps"), + verificationClasses: z.string().optional(), + verdictRationale: z.string().describe("Why this verdict was chosen"), + remediationPlan: z.string().optional(), +}; +const validateMilestoneSchema = z.object(validateMilestoneParams); + +const roadmapSliceChangeSchema = z.object({ + sliceId: z.string(), + title: z.string(), + risk: z.string().optional(), + depends: z.array(z.string()).optional(), + demo: z.string().optional(), +}); + +const reassessRoadmapParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + completedSliceId: z.string().describe("Slice ID that just completed"), + verdict: z.string().describe("Assessment verdict such as roadmap-confirmed or roadmap-adjusted"), + assessment: z.string().describe("Assessment text explaining the roadmap decision"), + sliceChanges: z.object({ + modified: z.array(roadmapSliceChangeSchema), + added: z.array(roadmapSliceChangeSchema), + removed: z.array(z.string()), + }).describe("Slice changes to apply"), +}; +const reassessRoadmapSchema = z.object(reassessRoadmapParams); + +const saveGateResultParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + sliceId: z.string().describe("Slice ID (e.g. S01)"), + gateId: z.enum(["Q3", "Q4", "Q5", "Q6", "Q7", "Q8"]).describe("Gate ID"), + taskId: z.string().optional().describe("Task ID for task-scoped gates"), + verdict: z.enum(["pass", "flag", "omitted"]).describe("Gate verdict"), + rationale: z.string().describe("One-sentence justification"), + findings: z.string().optional().describe("Detailed markdown findings"), +}; +const saveGateResultSchema = z.object(saveGateResultParams); + +const replanSliceParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + sliceId: z.string().describe("Slice ID (e.g. S01)"), + blockerTaskId: z.string().describe("Task ID that discovered the blocker"), + blockerDescription: z.string().describe("Description of the blocker"), + whatChanged: z.string().describe("Summary of what changed in the plan"), + updatedTasks: z.array(z.object({ + taskId: z.string(), + title: z.string(), + description: z.string(), + estimate: z.string(), + files: z.array(z.string()), + verify: z.string(), + inputs: z.array(z.string()), + expectedOutput: z.array(z.string()), + fullPlanMd: z.string().optional(), + })).describe("Tasks to upsert into the replanned slice"), + removedTaskIds: z.array(z.string()).describe("Task IDs to remove from the slice"), +}; +const replanSliceSchema = z.object(replanSliceParams); + +const sliceCompleteParams = { + projectDir: projectDirParam, + sliceId: z.string().describe("Slice ID (e.g. S01)"), + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + sliceTitle: z.string().describe("Title of the slice"), + oneLiner: z.string().describe("One-line summary of what the slice accomplished"), + narrative: z.string().describe("Detailed narrative of what happened across all tasks"), + verification: z.string().describe("What was verified across all tasks"), + uatContent: z.string().describe("UAT test content (markdown body)"), + deviations: z.string().optional(), + knownLimitations: z.string().optional(), + followUps: z.string().optional(), + keyFiles: z.union([z.array(z.string()), z.string()]).optional(), + keyDecisions: z.union([z.array(z.string()), z.string()]).optional(), + patternsEstablished: z.union([z.array(z.string()), z.string()]).optional(), + observabilitySurfaces: z.union([z.array(z.string()), z.string()]).optional(), + provides: z.union([z.array(z.string()), z.string()]).optional(), + requirementsSurfaced: z.union([z.array(z.string()), z.string()]).optional(), + drillDownPaths: z.union([z.array(z.string()), z.string()]).optional(), + affects: z.union([z.array(z.string()), z.string()]).optional(), + requirementsAdvanced: z.array(z.union([ + z.object({ id: z.string(), how: z.string() }), + z.string(), + ])).optional(), + requirementsValidated: z.array(z.union([ + z.object({ id: z.string(), proof: z.string() }), + z.string(), + ])).optional(), + requirementsInvalidated: z.array(z.union([ + z.object({ id: z.string(), what: z.string() }), + z.string(), + ])).optional(), + filesModified: z.array(z.union([ + z.object({ path: z.string(), description: z.string() }), + z.string(), + ])).optional(), + requires: z.array(z.union([ + z.object({ slice: z.string(), provides: z.string() }), + z.string(), + ])).optional(), +}; +const sliceCompleteSchema = z.object(sliceCompleteParams); + +const summarySaveParams = { + projectDir: projectDirParam, + milestone_id: z.string().describe("Milestone ID (e.g. M001)"), + slice_id: z.string().optional().describe("Slice ID (e.g. S01)"), + task_id: z.string().optional().describe("Task ID (e.g. T01)"), + artifact_type: z.string().describe("Artifact type to save (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT)"), + content: z.string().describe("The full markdown content of the artifact"), +}; +const summarySaveSchema = z.object(summarySaveParams); + +const decisionSaveParams = { + projectDir: projectDirParam, + scope: z.string().describe("Scope of the decision (e.g. architecture, library, observability)"), + decision: z.string().describe("What is being decided"), + choice: z.string().describe("The choice made"), + rationale: z.string().describe("Why this choice was made"), + revisable: z.string().optional().describe("Whether this can be revisited"), + when_context: z.string().optional().describe("When/context for the decision"), + made_by: z.enum(["human", "agent", "collaborative"]).optional().describe("Who made the decision"), +}; +const decisionSaveSchema = z.object(decisionSaveParams); + +const requirementUpdateParams = { + projectDir: projectDirParam, + id: z.string().describe("Requirement ID (e.g. R001)"), + status: z.string().optional().describe("New status"), + validation: z.string().optional().describe("Validation criteria or proof"), + notes: z.string().optional().describe("Additional notes"), + description: z.string().optional().describe("Updated description"), + primary_owner: z.string().optional().describe("Primary owning slice"), + supporting_slices: z.string().optional().describe("Supporting slices"), +}; +const requirementUpdateSchema = z.object(requirementUpdateParams); + +const requirementSaveParams = { + projectDir: projectDirParam, + class: z.string().describe("Requirement class"), + description: z.string().describe("Short description of the requirement"), + why: z.string().describe("Why this requirement matters"), + source: z.string().describe("Origin of the requirement"), + status: z.string().optional().describe("Requirement status"), + primary_owner: z.string().optional().describe("Primary owning slice"), + supporting_slices: z.string().optional().describe("Supporting slices"), + validation: z.string().optional().describe("Validation criteria"), + notes: z.string().optional().describe("Additional notes"), +}; +const requirementSaveSchema = z.object(requirementSaveParams); + +const milestoneGenerateIdParams = { + projectDir: projectDirParam, +}; +const milestoneGenerateIdSchema = z.object(milestoneGenerateIdParams); + +const planTaskParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + sliceId: z.string().describe("Slice ID (e.g. S01)"), + taskId: z.string().describe("Task ID (e.g. T01)"), + title: z.string().describe("Task title"), + description: z.string().describe("Task description / steps block"), + estimate: z.string().describe("Task estimate"), + files: z.array(z.string()).describe("Files likely touched"), + verify: z.string().describe("Verification command or block"), + inputs: z.array(z.string()).describe("Input files or references"), + expectedOutput: z.array(z.string()).describe("Expected output files or artifacts"), + observabilityImpact: z.string().optional().describe("Task observability impact"), +}; +const planTaskSchema = z.object(planTaskParams); + +const skipSliceParams = { + projectDir: projectDirParam, + sliceId: z.string().describe("Slice ID (e.g. S02)"), + milestoneId: z.string().describe("Milestone ID (e.g. M003)"), + reason: z.string().optional().describe("Reason for skipping this slice"), +}; +const skipSliceSchema = z.object(skipSliceParams); + +const taskCompleteParams = { + projectDir: projectDirParam, + taskId: z.string().describe("Task ID (e.g. T01)"), + sliceId: z.string().describe("Slice ID (e.g. S01)"), + milestoneId: z.string().describe("Milestone ID (e.g. M001)"), + oneLiner: z.string().describe("One-line summary of what was accomplished"), + narrative: z.string().describe("Detailed narrative of what happened during the task"), + verification: z.string().describe("What was verified and how"), + deviations: z.string().optional().describe("Deviations from the task plan"), + knownIssues: z.string().optional().describe("Known issues discovered but not fixed"), + keyFiles: z.array(z.string()).optional().describe("List of key files created or modified"), + keyDecisions: z.array(z.string()).optional().describe("List of key decisions made during this task"), + blockerDiscovered: z.boolean().optional().describe("Whether a plan-invalidating blocker was discovered"), + verificationEvidence: z.array(z.union([ + z.object({ + command: z.string(), + exitCode: z.number(), + verdict: z.string(), + durationMs: z.number(), + }), + z.string(), + ])).optional().describe("Verification evidence entries"), +}; +const taskCompleteSchema = z.object(taskCompleteParams); + +const milestoneStatusParams = { + projectDir: projectDirParam, + milestoneId: z.string().describe("Milestone ID to query (e.g. M001)"), +}; +const milestoneStatusSchema = z.object(milestoneStatusParams); + +const journalQueryParams = { + projectDir: projectDirParam, + flowId: z.string().optional().describe("Filter by flow ID"), + unitId: z.string().optional().describe("Filter by unit ID"), + rule: z.string().optional().describe("Filter by rule name"), + eventType: z.string().optional().describe("Filter by event type"), + after: z.string().optional().describe("ISO-8601 lower bound (inclusive)"), + before: z.string().optional().describe("ISO-8601 upper bound (inclusive)"), + limit: z.number().optional().describe("Maximum entries to return"), +}; +const journalQuerySchema = z.object(journalQueryParams); + +export function registerWorkflowTools(server: McpToolServer): void { + server.tool( + "gsd_decision_save", + "Record a project decision to the GSD database and regenerate DECISIONS.md.", + decisionSaveParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(decisionSaveSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_decision_save", projectDir); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { saveDecisionToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return saveDecisionToDb(params, projectDir); + }); + return { content: [{ type: "text" as const, text: `Saved decision ${result.id}` }] }; + }, + ); + + server.tool( + "gsd_save_decision", + "Alias for gsd_decision_save. Record a project decision to the GSD database and regenerate DECISIONS.md.", + decisionSaveParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(decisionSaveSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_decision_save", projectDir); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { saveDecisionToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return saveDecisionToDb(params, projectDir); + }); + return { content: [{ type: "text" as const, text: `Saved decision ${result.id}` }] }; + }, + ); + + server.tool( + "gsd_requirement_update", + "Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md.", + requirementUpdateParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(requirementUpdateSchema, args); + const { projectDir, id, ...updates } = parsed; + await enforceWorkflowWriteGate("gsd_requirement_update", projectDir); + await runSerializedWorkflowDbOperation(projectDir, async () => { + const { updateRequirementInDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return updateRequirementInDb(id, updates, projectDir); + }); + return { content: [{ type: "text" as const, text: `Updated requirement ${id}` }] }; + }, + ); + + server.tool( + "gsd_update_requirement", + "Alias for gsd_requirement_update. Update an existing requirement in the GSD database and regenerate REQUIREMENTS.md.", + requirementUpdateParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(requirementUpdateSchema, args); + const { projectDir, id, ...updates } = parsed; + await enforceWorkflowWriteGate("gsd_requirement_update", projectDir); + await runSerializedWorkflowDbOperation(projectDir, async () => { + const { updateRequirementInDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return updateRequirementInDb(id, updates, projectDir); + }); + return { content: [{ type: "text" as const, text: `Updated requirement ${id}` }] }; + }, + ); + + server.tool( + "gsd_requirement_save", + "Record a new requirement to the GSD database and regenerate REQUIREMENTS.md.", + requirementSaveParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(requirementSaveSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_requirement_save", projectDir); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { saveRequirementToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return saveRequirementToDb(params, projectDir); + }); + return { content: [{ type: "text" as const, text: `Saved requirement ${result.id}` }] }; + }, + ); + + server.tool( + "gsd_save_requirement", + "Alias for gsd_requirement_save. Record a new requirement to the GSD database and regenerate REQUIREMENTS.md.", + requirementSaveParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(requirementSaveSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_requirement_save", projectDir); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { saveRequirementToDb } = await importLocalModule("../../../src/resources/extensions/gsd/db-writer.js"); + return saveRequirementToDb(params, projectDir); + }); + return { content: [{ type: "text" as const, text: `Saved requirement ${result.id}` }] }; + }, + ); + + server.tool( + "gsd_milestone_generate_id", + "Generate the next milestone ID for a new GSD milestone.", + milestoneGenerateIdParams, + async (args: Record) => { + const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args); + await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir); + const id = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { + claimReservedId, + findMilestoneIds, + getReservedMilestoneIds, + nextMilestoneId, + } = await importLocalModule("../../../src/resources/extensions/gsd/milestone-ids.js"); + const reserved = claimReservedId(); + if (reserved) { + await ensureMilestoneDbRow(reserved); + return reserved; + } + const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])]; + const nextId = nextMilestoneId(allIds); + await ensureMilestoneDbRow(nextId); + return nextId; + }); + return { content: [{ type: "text" as const, text: id }] }; + }, + ); + + server.tool( + "gsd_generate_milestone_id", + "Alias for gsd_milestone_generate_id. Generate the next milestone ID for a new GSD milestone.", + milestoneGenerateIdParams, + async (args: Record) => { + const { projectDir } = parseWorkflowArgs(milestoneGenerateIdSchema, args); + await enforceWorkflowWriteGate("gsd_milestone_generate_id", projectDir); + const id = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { + claimReservedId, + findMilestoneIds, + getReservedMilestoneIds, + nextMilestoneId, + } = await importLocalModule("../../../src/resources/extensions/gsd/milestone-ids.js"); + const reserved = claimReservedId(); + if (reserved) { + await ensureMilestoneDbRow(reserved); + return reserved; + } + const allIds = [...new Set([...findMilestoneIds(projectDir), ...getReservedMilestoneIds()])]; + const nextId = nextMilestoneId(allIds); + await ensureMilestoneDbRow(nextId); + return nextId; + }); + return { content: [{ type: "text" as const, text: id }] }; + }, + ); + + server.tool( + "gsd_plan_milestone", + "Write milestone planning state to the GSD database and render ROADMAP.md from DB.", + planMilestoneParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(planMilestoneSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_plan_milestone", projectDir, params.milestoneId); + const { executePlanMilestone } = await getWorkflowToolExecutors(); + return runSerializedWorkflowOperation(() => executePlanMilestone(params, projectDir)); + }, + ); + + server.tool( + "gsd_plan_slice", + "Write slice/task planning state to the GSD database and render plan artifacts from DB.", + planSliceParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(planSliceSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_plan_slice", projectDir, params.milestoneId); + const { executePlanSlice } = await getWorkflowToolExecutors(); + return runSerializedWorkflowOperation(() => executePlanSlice(params, projectDir)); + }, + ); + + server.tool( + "gsd_plan_task", + "Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.", + planTaskParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(planTaskSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_plan_task", projectDir, params.milestoneId); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { handlePlanTask } = await importLocalModule("../../../src/resources/extensions/gsd/tools/plan-task.js"); + return handlePlanTask(params, projectDir); + }); + if ("error" in result) { + throw new Error(result.error); + } + return { + content: [{ type: "text" as const, text: `Planned task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }], + }; + }, + ); + + server.tool( + "gsd_task_plan", + "Alias for gsd_plan_task. Write task planning state to the GSD database and render tasks/T##-PLAN.md from DB.", + planTaskParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(planTaskSchema, args); + const { projectDir, ...params } = parsed; + await enforceWorkflowWriteGate("gsd_plan_task", projectDir, params.milestoneId); + const result = await runSerializedWorkflowDbOperation(projectDir, async () => { + const { handlePlanTask } = await importLocalModule("../../../src/resources/extensions/gsd/tools/plan-task.js"); + return handlePlanTask(params, projectDir); + }); + if ("error" in result) { + throw new Error(result.error); + } + return { + content: [{ type: "text" as const, text: `Planned task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }], + }; + }, + ); + + server.tool( + "gsd_replan_slice", + "Replan a slice after a blocker is discovered, preserving completed tasks and re-rendering PLAN.md + REPLAN.md.", + replanSliceParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(replanSliceSchema, args); + return handleReplanSlice(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_slice_replan", + "Alias for gsd_replan_slice. Replan a slice after a blocker is discovered.", + replanSliceParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(replanSliceSchema, args); + return handleReplanSlice(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_slice_complete", + "Record a completed slice to the GSD database, render SUMMARY.md + UAT.md, and update roadmap projection.", + sliceCompleteParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(sliceCompleteSchema, args); + return handleSliceComplete(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_complete_slice", + "Alias for gsd_slice_complete. Record a completed slice to the GSD database and render summary/UAT artifacts.", + sliceCompleteParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(sliceCompleteSchema, args); + return handleSliceComplete(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_skip_slice", + "Mark a slice as skipped so auto-mode advances past it without executing.", + skipSliceParams, + async (args: Record) => { + const { projectDir, milestoneId, sliceId, reason } = parseWorkflowArgs(skipSliceSchema, args); + await enforceWorkflowWriteGate("gsd_skip_slice", projectDir, milestoneId); + await runSerializedWorkflowDbOperation(projectDir, async () => { + const { getSlice, updateSliceStatus } = await importLocalModule("../../../src/resources/extensions/gsd/gsd-db.js"); + const { invalidateStateCache } = await importLocalModule("../../../src/resources/extensions/gsd/state.js"); + const { rebuildState } = await importLocalModule("../../../src/resources/extensions/gsd/doctor.js"); + const slice = getSlice(milestoneId, sliceId); + if (!slice) { + throw new Error(`Slice ${sliceId} not found in milestone ${milestoneId}`); + } + if (slice.status === "complete" || slice.status === "done") { + throw new Error(`Slice ${sliceId} is already complete and cannot be skipped`); + } + if (slice.status !== "skipped") { + updateSliceStatus(milestoneId, sliceId, "skipped"); + invalidateStateCache(); + await rebuildState(projectDir); + } + }); + return { + content: [{ type: "text" as const, text: `Skipped slice ${sliceId} (${milestoneId}). Reason: ${reason ?? "User-directed skip"}.` }], + }; + }, + ); + + server.tool( + "gsd_complete_milestone", + "Record a completed milestone to the GSD database and render its SUMMARY.md.", + completeMilestoneParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(completeMilestoneSchema, args); + return handleCompleteMilestone(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_milestone_complete", + "Alias for gsd_complete_milestone. Record a completed milestone to the GSD database and render its SUMMARY.md.", + completeMilestoneParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(completeMilestoneSchema, args); + return handleCompleteMilestone(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_validate_milestone", + "Validate a milestone, persist validation results to the GSD database, and render VALIDATION.md.", + validateMilestoneParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(validateMilestoneSchema, args); + return handleValidateMilestone(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_milestone_validate", + "Alias for gsd_validate_milestone. Validate a milestone and render VALIDATION.md.", + validateMilestoneParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(validateMilestoneSchema, args); + return handleValidateMilestone(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_reassess_roadmap", + "Reassess a milestone roadmap after a slice completes, writing ASSESSMENT.md and re-rendering ROADMAP.md.", + reassessRoadmapParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(reassessRoadmapSchema, args); + return handleReassessRoadmap(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_roadmap_reassess", + "Alias for gsd_reassess_roadmap. Reassess a roadmap after slice completion.", + reassessRoadmapParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(reassessRoadmapSchema, args); + return handleReassessRoadmap(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_save_gate_result", + "Save a quality gate result to the GSD database.", + saveGateResultParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(saveGateResultSchema, args); + return handleSaveGateResult(parsed.projectDir, parsed); + }, + ); + + server.tool( + "gsd_summary_save", + "Save a GSD summary/research/context/assessment artifact to the database and disk.", + summarySaveParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(summarySaveSchema, args); + const { projectDir, milestone_id, slice_id, task_id, artifact_type, content } = parsed; + await enforceWorkflowWriteGate("gsd_summary_save", projectDir, milestone_id); + const executors = await getWorkflowToolExecutors(); + const supportedArtifactTypes = getSupportedSummaryArtifactTypes(executors); + if (!supportedArtifactTypes.includes(artifact_type)) { + throw new Error( + `artifact_type must be one of: ${supportedArtifactTypes.join(", ")}`, + ); + } + return runSerializedWorkflowOperation(() => + executors.executeSummarySave({ milestone_id, slice_id, task_id, artifact_type, content }, projectDir), + ); + }, + ); + + server.tool( + "gsd_task_complete", + "Record a completed task to the GSD database and render its SUMMARY.md.", + taskCompleteParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(taskCompleteSchema, args); + const { projectDir, ...taskArgs } = parsed; + return handleTaskComplete(projectDir, taskArgs); + }, + ); + + server.tool( + "gsd_complete_task", + "Alias for gsd_task_complete. Record a completed task to the GSD database and render its SUMMARY.md.", + taskCompleteParams, + async (args: Record) => { + const parsed = parseWorkflowArgs(taskCompleteSchema, args); + const { projectDir, ...taskArgs } = parsed; + return handleTaskComplete(projectDir, taskArgs); + }, + ); + + server.tool( + "gsd_milestone_status", + "Read the current status of a milestone and all its slices from the GSD database.", + milestoneStatusParams, + async (args: Record) => { + const { projectDir, milestoneId } = parseWorkflowArgs(milestoneStatusSchema, args); + await enforceWorkflowWriteGate("gsd_milestone_status", projectDir, milestoneId); + const { executeMilestoneStatus } = await getWorkflowToolExecutors(); + return runSerializedWorkflowOperation(() => executeMilestoneStatus({ milestoneId }, projectDir)); + }, + ); + + server.tool( + "gsd_journal_query", + "Query the structured event journal for auto-mode iterations.", + journalQueryParams, + async (args: Record) => { + const { projectDir, limit, ...filters } = parseWorkflowArgs(journalQuerySchema, args); + const { queryJournal } = await importLocalModule("../../../src/resources/extensions/gsd/journal.js"); + const entries = queryJournal(projectDir, filters).slice(0, limit ?? 100); + if (entries.length === 0) { + return { content: [{ type: "text" as const, text: "No matching journal entries found." }] }; + } + return { content: [{ type: "text" as const, text: JSON.stringify(entries, null, 2) }] }; + }, + ); +} diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.json index 779b48aca..1e62e4af6 100644 --- a/packages/mcp-server/tsconfig.json +++ b/packages/mcp-server/tsconfig.json @@ -20,5 +20,5 @@ "rootDir": "./src" }, "include": ["src/**/*.ts"], - "exclude": ["node_modules", "dist", "**/*.d.ts", "src/**/*.d.ts"] + "exclude": ["node_modules", "dist", "**/*.d.ts", "src/**/*.d.ts", "src/**/*.test.ts"] } diff --git a/packages/native/package.json b/packages/native/package.json index 1bb3b009d..42bc47668 100644 --- a/packages/native/package.json +++ b/packages/native/package.json @@ -2,7 +2,7 @@ "name": "@gsd/native", "version": "0.1.0", "description": "Native Rust bindings for GSD \u2014 high-performance native modules via N-API", - "type": "module", + "type": "commonjs", "main": "./dist/index.js", "types": "./dist/index.d.ts", "scripts": { @@ -14,75 +14,75 @@ "exports": { ".": { "types": "./dist/index.d.ts", - "import": "./dist/index.js" + "default": "./dist/index.js" }, "./grep": { "types": "./dist/grep/index.d.ts", - "import": "./dist/grep/index.js" + "default": "./dist/grep/index.js" }, "./ps": { "types": "./dist/ps/index.d.ts", - "import": "./dist/ps/index.js" + "default": "./dist/ps/index.js" }, "./glob": { "types": "./dist/glob/index.d.ts", - "import": "./dist/glob/index.js" + "default": "./dist/glob/index.js" }, "./clipboard": { "types": "./dist/clipboard/index.d.ts", - "import": "./dist/clipboard/index.js" + "default": "./dist/clipboard/index.js" }, "./ast": { "types": "./dist/ast/index.d.ts", - "import": "./dist/ast/index.js" + "default": "./dist/ast/index.js" }, "./html": { "types": "./dist/html/index.d.ts", - "import": "./dist/html/index.js" + "default": "./dist/html/index.js" }, "./text": { "types": "./dist/text/index.d.ts", - "import": "./dist/text/index.js" + "default": "./dist/text/index.js" }, "./fd": { "types": "./dist/fd/index.d.ts", - "import": "./dist/fd/index.js" + "default": "./dist/fd/index.js" }, "./image": { "types": "./dist/image/index.d.ts", - "import": "./dist/image/index.js" + "default": "./dist/image/index.js" }, "./xxhash": { "types": "./dist/xxhash/index.d.ts", - "import": "./dist/xxhash/index.js" + "default": "./dist/xxhash/index.js" }, "./diff": { "types": "./dist/diff/index.d.ts", - "import": "./dist/diff/index.js" + "default": "./dist/diff/index.js" }, "./gsd-parser": { "types": "./dist/gsd-parser/index.d.ts", - "import": "./dist/gsd-parser/index.js" + "default": "./dist/gsd-parser/index.js" }, "./highlight": { "types": "./dist/highlight/index.d.ts", - "import": "./dist/highlight/index.js" + "default": "./dist/highlight/index.js" }, "./json-parse": { "types": "./dist/json-parse/index.d.ts", - "import": "./dist/json-parse/index.js" + "default": "./dist/json-parse/index.js" }, "./stream-process": { "types": "./dist/stream-process/index.d.ts", - "import": "./dist/stream-process/index.js" + "default": "./dist/stream-process/index.js" }, "./truncate": { "types": "./dist/truncate/index.d.ts", - "import": "./dist/truncate/index.js" + "default": "./dist/truncate/index.js" }, "./ttsr": { "types": "./dist/ttsr/index.d.ts", - "import": "./dist/ttsr/index.js" + "default": "./dist/ttsr/index.js" } }, "files": [ diff --git a/packages/native/src/__tests__/module-compat.test.mjs b/packages/native/src/__tests__/module-compat.test.mjs new file mode 100644 index 000000000..949fd16d3 --- /dev/null +++ b/packages/native/src/__tests__/module-compat.test.mjs @@ -0,0 +1,91 @@ +/** + * Tests that the @gsd/native package.json is correctly configured + * for Node.js module resolution (ESM/CJS compatibility). + * + * Regression test for #2861: "type": "module" + "import"-only export + * conditions caused crashes on Node.js v24 when the parent package also + * declared "type": "module" and strict ESM resolution was enforced. + */ + +import { test, describe } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const pkgPath = path.resolve(__dirname, "..", "..", "package.json"); +const pkg = JSON.parse(readFileSync(pkgPath, "utf8")); + +describe("@gsd/native module compatibility (#2861)", () => { + test("package.json must not declare type: module (compiled output is CJS-compatible)", () => { + // The compiled output uses createRequire() to load .node addons. + // Declaring "type": "module" forces Node.js to treat .js files as ESM, + // but the package needs "type": "commonjs" to override the parent + // package's "type": "module" and ensure correct CJS semantics. + assert.notEqual( + pkg.type, + "module", + 'package.json must not set "type": "module" — this causes crashes on Node.js v24 ' + + "when the parent package also declares ESM (see #2861)", + ); + }); + + test("package.json should explicitly declare type: commonjs", () => { + // When installed as a dependency under a parent with "type": "module" + // (e.g. gsd-pi), an absent "type" field would inherit the parent's + // ESM setting. Explicit "commonjs" overrides this. + assert.equal( + pkg.type, + "commonjs", + 'package.json must explicitly set "type": "commonjs" to override ' + + "the parent package's ESM declaration", + ); + }); + + test("all export conditions must use 'default' (not 'import'-only)", () => { + // The "import" condition key restricts resolution to ESM import + // statements only. Using "default" ensures the export works for both + // require() and import, which is essential for a CJS package that may + // be consumed from ESM code via Node's CJS interop. + const exportsMap = pkg.exports; + assert.ok(exportsMap, "package.json must have an exports map"); + + for (const [subpath, conditions] of Object.entries(exportsMap)) { + assert.ok( + !conditions.import || conditions.default, + `exports["${subpath}"] uses "import" condition without "default" — ` + + `this breaks CJS consumers and Node.js v24 strict resolution`, + ); + } + }); + + test("native.ts source must not use bare import.meta.url (parse-time error in CJS)", () => { + // When compiled to CJS, import.meta is a *parse-time* syntax error -- + // typeof guards don't help because Node rejects the syntax before + // executing any code. The source must wrap import.meta access in + // an indirect eval so the CJS parser never sees the bare syntax. + const nativeSrc = readFileSync( + path.resolve(__dirname, "..", "native.ts"), + "utf8", + ); + + // Bare import.meta.url (NOT wrapped) would crash at parse time in CJS. + // These regexes match direct usage like fileURLToPath(import.meta.url) + // and createRequire(import.meta.url), but NOT indirect patterns that + // hide import.meta from the CJS parser. + const hasBareImportMetaDirname = /path\.dirname\(.*fileURLToPath\(import\.meta\.url\)\)/.test(nativeSrc); + const hasBareImportMetaRequire = /createRequire\(import\.meta\.url\)/.test(nativeSrc); + + assert.ok( + !hasBareImportMetaDirname, + "native.ts must not use bare import.meta.url in fileURLToPath() -- " + + "this is a parse-time syntax error in CJS; use indirect eval", + ); + assert.ok( + !hasBareImportMetaRequire, + "native.ts must not use bare import.meta.url in createRequire() -- " + + "this is a parse-time syntax error in CJS; use indirect eval", + ); + }); +}); diff --git a/packages/native/src/native.ts b/packages/native/src/native.ts index b310cef28..05d4288b1 100644 --- a/packages/native/src/native.ts +++ b/packages/native/src/native.ts @@ -8,14 +8,15 @@ * 3. native/addon/gsd_engine.dev.node (local debug build) */ -import { createRequire } from "node:module"; import * as path from "node:path"; -import { fileURLToPath } from "node:url"; -const __dirname = path.dirname(fileURLToPath(import.meta.url)); -const require = createRequire(import.meta.url); +// __dirname and require are available in both execution contexts: +// - CJS (production build via tsc): provided natively by Node +// - ESM (CI test loader): injected by the dist-redirect.mjs preamble +const _dirname = __dirname; +const _require = require; -const addonDir = path.resolve(__dirname, "..", "..", "..", "native", "addon"); +const addonDir = path.resolve(_dirname, "..", "..", "..", "native", "addon"); const platformTag = `${process.platform}-${process.arch}`; /** Map Node.js platform/arch to the npm package suffix */ @@ -36,7 +37,7 @@ function loadNative(): Record { const packageSuffix = platformPackageMap[platformTag]; if (packageSuffix) { try { - _loadedSuccessfully = true; return require(`@gsd-build/engine-${packageSuffix}`) as Record; + _loadedSuccessfully = true; return _require(`@gsd-build/engine-${packageSuffix}`) as Record; } catch (err) { const message = err instanceof Error ? err.message : String(err); errors.push(`@gsd-build/engine-${packageSuffix}: ${message}`); @@ -46,7 +47,7 @@ function loadNative(): Record { // 2. Try local release build (native/addon/gsd_engine.{platform}.node) const releasePath = path.join(addonDir, `gsd_engine.${platformTag}.node`); try { - _loadedSuccessfully = true; return require(releasePath) as Record; + _loadedSuccessfully = true; return _require(releasePath) as Record; } catch (err) { const message = err instanceof Error ? err.message : String(err); errors.push(`${releasePath}: ${message}`); @@ -55,7 +56,7 @@ function loadNative(): Record { // 3. Try local dev build (native/addon/gsd_engine.dev.node) const devPath = path.join(addonDir, "gsd_engine.dev.node"); try { - _loadedSuccessfully = true; return require(devPath) as Record; + _loadedSuccessfully = true; return _require(devPath) as Record; } catch (err) { const message = err instanceof Error ? err.message : String(err); errors.push(`${devPath}: ${message}`); diff --git a/packages/pi-agent-core/src/agent-loop.test.ts b/packages/pi-agent-core/src/agent-loop.test.ts new file mode 100644 index 000000000..e0a11aa06 --- /dev/null +++ b/packages/pi-agent-core/src/agent-loop.test.ts @@ -0,0 +1,410 @@ +// agent-loop tests +// Covers: pauseTurn handling (#2869), schema overload retry cap (#2783) + +import { describe, it, mock } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; +import { Type } from "@sinclair/typebox"; +import { agentLoop, MAX_CONSECUTIVE_VALIDATION_FAILURES } from "./agent-loop.js"; +import type { AgentContext, AgentLoopConfig, AgentTool, AgentEvent, AgentMessage } from "./types.js"; +import { AssistantMessageEventStream, EventStream } from "@gsd/pi-ai"; +import type { AssistantMessage, AssistantMessageEvent, Model } from "@gsd/pi-ai"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +describe("agent-loop — pauseTurn handling (#2869)", () => { + it("sets hasMoreToolCalls when stopReason is pauseTurn", () => { + const source = readFileSync(join(__dirname, "agent-loop.ts"), "utf-8"); + + // The agent loop must treat pauseTurn as a reason to continue the inner + // loop, just like toolUse. This prevents incomplete server_tool_use blocks + // from being saved to history, which would cause a 400 on the next request. + assert.match( + source, + /pauseTurn/, + "agent-loop.ts must handle the pauseTurn stop reason", + ); + + // Verify it sets hasMoreToolCalls = true for pauseTurn + assert.match( + source, + /stopReason\s*===?\s*["']pauseTurn["']/, + 'agent-loop.ts must check for stopReason === "pauseTurn"', + ); + }); + + it("pauseTurn is in the StopReason union type", () => { + // Read the pi-ai types to ensure pauseTurn is a valid StopReason + const typesPath = join(__dirname, "..", "..", "pi-ai", "src", "types.ts"); + const typesSource = readFileSync(typesPath, "utf-8"); + assert.match( + typesSource, + /["']pauseTurn["']/, + 'StopReason type must include "pauseTurn"', + ); + }); + + it("uses provider-supplied external tool results instead of the placeholder", async () => { + const externalMessage = makeAssistantMessage({ + content: [ + { + type: "toolCall", + id: "tc-external-1", + name: "bash", + arguments: { command: "echo hi" }, + externalResult: { + content: [{ type: "text", text: "hi\n" }], + details: { source: "claude-code" }, + isError: false, + }, + } as any, + ], + stopReason: "toolUse", + provider: "claude-code", + }); + + const mockStream = createMockStreamFn([externalMessage]); + + const context: AgentContext = { + systemPrompt: "You are a test agent.", + messages: [{ role: "user", content: [{ type: "text", text: "Run the command" }], timestamp: Date.now() }], + tools: [], + }; + + const config: AgentLoopConfig = { + model: { ...TEST_MODEL, provider: "claude-code" }, + convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"), + toolExecution: "sequential", + externalToolExecution: true, + }; + + const stream = agentLoop( + [{ role: "user", content: [{ type: "text", text: "Run the command" }], timestamp: Date.now() }], + context, + config, + undefined, + mockStream as any, + ); + + const events = await collectEvents(stream); + const toolEnd = events.find( + (event): event is Extract => event.type === "tool_execution_end", + ); + + assert.ok(toolEnd, "expected tool_execution_end event"); + assert.deepEqual(toolEnd.result.content, [{ type: "text", text: "hi\n" }]); + assert.deepEqual(toolEnd.result.details, { source: "claude-code" }); + assert.equal(toolEnd.isError, false); + }); +}); + +/** + * Regression tests for #2783: Stuck-loop on execute-task — tool-call schema + * overload causes unbounded retry + budget burn. + * + * When the LLM repeatedly emits tool calls with arguments that fail schema + * validation, the agent loop retries indefinitely. Each failed validation + * returns an error tool result, the LLM retries with the same broken args, + * and the cycle never breaks — burning budget with no progress. + * + * The fix caps consecutive validation failures per turn at + * MAX_CONSECUTIVE_VALIDATION_FAILURES (default 3). Once the cap is hit, the + * loop injects a synthetic stop so the agent terminates cleanly instead of + * spinning forever. + */ + +// ─── Helpers ────────────────────────────────────────────────────────────────── + +const TEST_MODEL: Model<"anthropic-messages"> = { + id: "claude-test", + name: "Test Model", + api: "anthropic-messages", + provider: "anthropic", + contextWindow: 200_000, + maxOutput: 4096, + supportsImages: false, + supportsPromptCache: false, + thinkingLevel: undefined, +}; + +function makeToolWithSchema(): AgentTool { + return { + name: "write_file", + label: "Write File", + description: "Write content to a file", + parameters: Type.Object({ + path: Type.String(), + content: Type.String(), + }), + execute: async () => ({ + content: [{ type: "text" as const, text: "done" }], + details: {}, + }), + }; +} + +/** + * Creates a mock streamFn that returns assistant messages from a queue. + * Each call pops the next message. The messages simulate the LLM repeatedly + * emitting the same tool call with broken arguments. + */ +function createMockStreamFn(responses: AssistantMessage[]) { + let callIndex = 0; + + return function mockStreamFn(): AssistantMessageEventStream { + const message = responses[callIndex] ?? responses[responses.length - 1]; + callIndex++; + + const stream = new AssistantMessageEventStream(); + // Simulate async delivery + queueMicrotask(() => { + stream.push({ type: "start", partial: message }); + stream.push({ type: "done", message }); + stream.end(message); + }); + return stream; + }; +} + +function makeAssistantMessage(overrides: Partial = {}): AssistantMessage { + return { + role: "assistant", + content: [], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-test", + usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, totalTokens: 150, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, + stopReason: "stop", + timestamp: Date.now(), + ...overrides, + }; +} + +function makeToolCallMessage(toolCallArgs: Record): AssistantMessage { + return makeAssistantMessage({ + content: [ + { + type: "toolCall", + id: `tc_${Date.now()}_${Math.random()}`, + name: "write_file", + arguments: toolCallArgs, + }, + ], + stopReason: "toolUse", + }); +} + +function collectEvents(stream: EventStream): Promise { + return new Promise(async (resolve) => { + const events: AgentEvent[] = []; + for await (const event of stream) { + events.push(event); + } + resolve(events); + }); +} + +// ─── Tests ──────────────────────────────────────────────────────────────────── + +describe("agent-loop — schema overload retry cap (#2783)", () => { + + it("terminates after MAX_CONSECUTIVE_VALIDATION_FAILURES consecutive schema failures", async () => { + const tool = makeToolWithSchema(); + + // LLM keeps sending tool calls with invalid args (missing required 'content' field) + const badToolCall = makeToolCallMessage({ path: "/tmp/test" }); // missing 'content' + const finalStop = makeAssistantMessage({ content: [{ type: "text", text: "I give up." }], stopReason: "stop" }); + + // Create enough bad responses to exceed the cap, plus a final stop + const responses: AssistantMessage[] = []; + for (let i = 0; i < MAX_CONSECUTIVE_VALIDATION_FAILURES + 5; i++) { + responses.push(badToolCall); + } + responses.push(finalStop); + + const mockStream = createMockStreamFn(responses); + + const context: AgentContext = { + systemPrompt: "You are a test agent.", + messages: [{ role: "user", content: [{ type: "text", text: "Write a file" }], timestamp: Date.now() }], + tools: [tool], + }; + + const config: AgentLoopConfig = { + model: TEST_MODEL, + convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"), + toolExecution: "sequential", + }; + + const stream = agentLoop( + [{ role: "user", content: [{ type: "text", text: "Write a file" }], timestamp: Date.now() }], + context, + config, + undefined, + mockStream as any, + ); + + const events = await collectEvents(stream); + + // Must have terminated (agent_end event present) + const agentEnd = events.find((e) => e.type === "agent_end"); + assert.ok(agentEnd, "agent loop must emit agent_end after hitting retry cap"); + + // Count how many turns had validation errors (tool_execution_end with isError: true) + const toolErrors = events.filter( + (e) => e.type === "tool_execution_end" && e.isError === true, + ); + + // Must not exceed the cap + assert.ok( + toolErrors.length <= MAX_CONSECUTIVE_VALIDATION_FAILURES, + `Expected at most ${MAX_CONSECUTIVE_VALIDATION_FAILURES} validation error tool results, got ${toolErrors.length}`, + ); + }); + + it("resets the failure counter when a tool call succeeds", async () => { + const tool = makeToolWithSchema(); + + // Pattern: 2 failures, 1 success, 2 failures, 1 success, then stop + const badCall = makeToolCallMessage({ path: "/tmp/test" }); // missing 'content' + const goodCall = makeToolCallMessage({ path: "/tmp/test", content: "hello" }); + const finalStop = makeAssistantMessage({ content: [{ type: "text", text: "Done." }], stopReason: "stop" }); + + const responses = [badCall, badCall, goodCall, badCall, badCall, goodCall, finalStop]; + const mockStream = createMockStreamFn(responses); + + const context: AgentContext = { + systemPrompt: "You are a test agent.", + messages: [{ role: "user", content: [{ type: "text", text: "Write a file" }], timestamp: Date.now() }], + tools: [tool], + }; + + const config: AgentLoopConfig = { + model: TEST_MODEL, + convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"), + toolExecution: "sequential", + }; + + const stream = agentLoop( + [{ role: "user", content: [{ type: "text", text: "Write a file" }], timestamp: Date.now() }], + context, + config, + undefined, + mockStream as any, + ); + + const events = await collectEvents(stream); + + // Must complete successfully since failures never reached cap consecutively + const agentEnd = events.find((e) => e.type === "agent_end"); + assert.ok(agentEnd, "agent loop must complete normally when failures are interspersed with successes"); + + // Should have processed all 6 tool-bearing turns + const toolExecEnds = events.filter((e) => e.type === "tool_execution_end"); + assert.ok(toolExecEnds.length >= 4, `Expected at least 4 tool executions (2 bad + 1 good + 2 bad + 1 good), got ${toolExecEnds.length}`); + }); + + it("exports MAX_CONSECUTIVE_VALIDATION_FAILURES as a configurable constant", () => { + assert.equal(typeof MAX_CONSECUTIVE_VALIDATION_FAILURES, "number"); + assert.ok(MAX_CONSECUTIVE_VALIDATION_FAILURES >= 2, "Cap must be at least 2 to allow one retry"); + assert.ok(MAX_CONSECUTIVE_VALIDATION_FAILURES <= 10, "Cap must not be unreasonably high"); + }); + + it("does NOT trip schema overload cap on tool execution errors like bash exit code 1 (#3618)", async () => { + // Simulates the real scenario: a tool (bash) that passes validation but + // throws during execution (e.g. rg/grep returning exit code 1 = no matches). + // These are valid tool invocations — the schema was correct, the tool ran, + // it just returned a non-zero exit code. The cap should only trigger for + // preparation/schema failures, not execution failures. + const bashTool: AgentTool = { + name: "bash", + label: "Bash", + description: "Run a bash command", + parameters: Type.Object({ + command: Type.String(), + }), + execute: async () => { + // Simulate bash tool rejecting on non-zero exit code + throw new Error("(no output)\n\nCommand exited with code 1"); + }, + }; + + // LLM sends valid tool calls (schema is correct) that fail at execution + const validBashCall = makeAssistantMessage({ + content: [ + { + type: "toolCall", + id: `tc_bash_${Date.now()}_${Math.random()}`, + name: "bash", + arguments: { command: "rg -l 'nonexistent' src/" }, + }, + ], + stopReason: "toolUse", + }); + const finalStop = makeAssistantMessage({ + content: [{ type: "text", text: "No references found." }], + stopReason: "stop", + }); + + // Send more than MAX_CONSECUTIVE_VALIDATION_FAILURES bash calls that throw + const responses: AssistantMessage[] = []; + for (let i = 0; i < MAX_CONSECUTIVE_VALIDATION_FAILURES + 2; i++) { + responses.push(validBashCall); + } + responses.push(finalStop); + + const mockStream = createMockStreamFn(responses); + + const context: AgentContext = { + systemPrompt: "You are a test agent.", + messages: [{ role: "user", content: [{ type: "text", text: "Search for references" }], timestamp: Date.now() }], + tools: [bashTool], + }; + + const config: AgentLoopConfig = { + model: TEST_MODEL, + convertToLlm: (msgs) => msgs.filter((m): m is any => m.role !== "custom"), + toolExecution: "sequential", + }; + + const stream = agentLoop( + [{ role: "user", content: [{ type: "text", text: "Search for references" }], timestamp: Date.now() }], + context, + config, + undefined, + mockStream as any, + ); + + const events = await collectEvents(stream); + + // Must complete normally — execution errors should NOT trigger the cap + const agentEnd = events.find((e) => e.type === "agent_end"); + assert.ok(agentEnd, "agent loop must emit agent_end"); + + // Count tool execution errors + const toolErrors = events.filter( + (e) => e.type === "tool_execution_end" && e.isError === true, + ); + + // All bash calls should have been attempted (not capped early) + assert.ok( + toolErrors.length >= MAX_CONSECUTIVE_VALIDATION_FAILURES + 2, + `Expected all ${MAX_CONSECUTIVE_VALIDATION_FAILURES + 2} bash execution errors to be processed (not capped), got ${toolErrors.length}`, + ); + + // The stop message should NOT contain the schema overload text + const allMessages = (agentEnd as any).messages as AgentMessage[]; + const lastMessage = allMessages[allMessages.length - 1]; + const lastText = lastMessage.role === "assistant" + ? (lastMessage as AssistantMessage).content.find((c) => c.type === "text") + : undefined; + if (lastText && lastText.type === "text") { + assert.ok( + !lastText.text.includes("consecutive turns with all tool calls failing"), + "Final message must NOT contain schema overload stop text for execution-only errors", + ); + } + }); +}); diff --git a/packages/pi-agent-core/src/agent-loop.ts b/packages/pi-agent-core/src/agent-loop.ts index fad23b145..a99b596c8 100644 --- a/packages/pi-agent-core/src/agent-loop.ts +++ b/packages/pi-agent-core/src/agent-loop.ts @@ -22,6 +22,15 @@ import type { StreamFn, } from "./types.js"; +/** + * Maximum number of consecutive turns where ALL tool calls in the turn fail + * schema validation before the loop terminates. This prevents unbounded retry + * loops when the LLM repeatedly emits tool calls with arguments that cannot + * pass validation (e.g., schema overload, truncated JSON, missing required + * fields). See: https://github.com/gsd-build/gsd-2/issues/2783 + */ +export const MAX_CONSECUTIVE_VALIDATION_FAILURES = 3; + export const ZERO_USAGE = { input: 0, output: 0, @@ -175,6 +184,12 @@ async function runLoop( // Check for steering messages at start (user may have typed while waiting) let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || []; + // Track consecutive turns where ALL tool calls fail validation. + // When the LLM repeatedly emits tool calls with schema-overloaded or malformed + // arguments, each turn produces only error tool results. Without a cap, this + // creates an unbounded retry loop that burns budget. (#2783) + let consecutiveAllToolErrorTurns = 0; + // Outer loop: continues when queued follow-up messages arrive after agent would stop while (true) { let hasMoreToolCalls = true; @@ -231,16 +246,26 @@ async function runLoop( return; } - // Check for tool calls + // Check for tool calls or paused server turn const toolCalls = message.content.filter((c) => c.type === "toolCall"); - hasMoreToolCalls = toolCalls.length > 0; + hasMoreToolCalls = + toolCalls.length > 0 || message.stopReason === "pauseTurn"; const toolResults: ToolResultMessage[] = []; if (hasMoreToolCalls && config.externalToolExecution) { // External execution mode: tools were handled by the provider // (e.g., Claude Code SDK). Emit tool_execution events for each - // tool call. The TUI adds these as components after the message. + // tool call. Prefer any provider-supplied externalResult attached + // to the tool call so the UI can show the real stdout/stderr + // instead of a generic placeholder. for (const tc of toolCalls as AgentToolCall[]) { + const externalResult = (tc as AgentToolCall & { + externalResult?: { + content?: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; + details?: Record; + isError?: boolean; + }; + }).externalResult; stream.push({ type: "tool_execution_start", toolCallId: tc.id, @@ -251,11 +276,16 @@ async function runLoop( type: "tool_execution_end", toolCallId: tc.id, toolName: tc.name, - result: { - content: [{ type: "text", text: "(executed by Claude Code)" }], - details: {}, - }, - isError: false, + result: externalResult + ? { + content: externalResult.content ?? [{ type: "text", text: "" }], + details: externalResult.details ?? {}, + } + : { + content: [{ type: "text", text: "(executed by Claude Code)" }], + details: {}, + }, + isError: externalResult?.isError ?? false, }); } // Don't add tool results to context or loop back — the streamSimple @@ -276,6 +306,54 @@ async function runLoop( currentContext.messages.push(result); newMessages.push(result); } + + // Schema overload detection (#2783): count only preparation-phase + // errors (schema validation, tool-not-found, tool-blocked) toward the + // consecutive failure cap. Tool execution errors — such as bash + // commands returning non-zero exit codes (e.g. grep/rg exit 1 for + // "no matches") — are valid tool usage and must NOT trigger the cap. + // See: #3618 + const hasPreparationErrors = toolExecution.preparationErrorCount > 0; + const allToolsFailedPreparation = + toolResults.length > 0 && + toolExecution.preparationErrorCount === toolResults.length; + if (allToolsFailedPreparation) { + consecutiveAllToolErrorTurns++; + } else if (!hasPreparationErrors) { + // Reset only when there are zero preparation errors this turn. + // Mixed turns (some prep errors, some successes) don't reset, + // but they also don't increment — this avoids masking a + // pattern of alternating schema failures with one working call. + consecutiveAllToolErrorTurns = 0; + } + + if (consecutiveAllToolErrorTurns >= MAX_CONSECUTIVE_VALIDATION_FAILURES) { + // Force-stop: the LLM is stuck retrying broken tool calls. + // Emit the turn_end and terminate the agent loop cleanly. + stream.push({ type: "turn_end", message, toolResults }); + const stopMessage: AssistantMessage = { + role: "assistant", + content: [ + { + type: "text", + text: `Agent stopped: ${consecutiveAllToolErrorTurns} consecutive turns with all tool calls failing. This usually means the model is repeatedly sending arguments that do not match the tool schema.`, + }, + ], + api: config.model.api, + provider: config.model.provider, + model: config.model.id, + usage: ZERO_USAGE, + stopReason: "error", + errorMessage: "Schema overload: consecutive tool validation failures exceeded cap", + timestamp: Date.now(), + }; + emitMessagePair(stream, stopMessage); + newMessages.push(stopMessage); + stream.push({ type: "turn_end", message: stopMessage, toolResults: [] }); + stream.push({ type: "agent_end", messages: newMessages }); + stream.end(newMessages); + return; + } } stream.push({ type: "turn_end", message, toolResults }); @@ -398,6 +476,19 @@ async function streamAssistantResponse( return await response.result(); } +/** + * Result from executing tool calls in a turn. Includes metadata about + * error provenance so the schema overload detector can distinguish + * preparation failures (schema validation, tool-not-found, tool-blocked) + * from execution failures (the tool ran but threw, e.g. bash exit code 1). + */ +interface ToolExecutionResult { + toolResults: ToolResultMessage[]; + steeringMessages?: AgentMessage[]; + /** Number of tool results that failed during preparation (validation/schema). */ + preparationErrorCount: number; +} + /** * Execute tool calls from an assistant message. */ @@ -407,7 +498,7 @@ async function executeToolCalls( config: AgentLoopConfig, signal: AbortSignal | undefined, stream: EventStream, -): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> { +): Promise { const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall") as AgentToolCall[]; if (config.toolExecution === "sequential") { return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, signal, stream); @@ -422,9 +513,10 @@ async function executeToolCallsSequential( config: AgentLoopConfig, signal: AbortSignal | undefined, stream: EventStream, -): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> { +): Promise { const results: ToolResultMessage[] = []; let steeringMessages: AgentMessage[] | undefined; + let preparationErrorCount = 0; for (let index = 0; index < toolCalls.length; index++) { const toolCall = toolCalls[index]; @@ -437,6 +529,9 @@ async function executeToolCallsSequential( const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal); if (preparation.kind === "immediate") { + if (preparation.isError) { + preparationErrorCount++; + } results.push(emitToolCallOutcome(toolCall, preparation.result, preparation.isError, stream)); } else { const executed = await executePreparedToolCall(preparation, signal, stream); @@ -466,7 +561,7 @@ async function executeToolCallsSequential( } } - return { toolResults: results, steeringMessages }; + return { toolResults: results, steeringMessages, preparationErrorCount }; } async function executeToolCallsParallel( @@ -476,10 +571,11 @@ async function executeToolCallsParallel( config: AgentLoopConfig, signal: AbortSignal | undefined, stream: EventStream, -): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> { +): Promise { const results: ToolResultMessage[] = []; const runnableCalls: PreparedToolCall[] = []; let steeringMessages: AgentMessage[] | undefined; + let preparationErrorCount = 0; for (let index = 0; index < toolCalls.length; index++) { const toolCall = toolCalls[index]; @@ -492,6 +588,9 @@ async function executeToolCallsParallel( const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, signal); if (preparation.kind === "immediate") { + if (preparation.isError) { + preparationErrorCount++; + } results.push(emitToolCallOutcome(toolCall, preparation.result, preparation.isError, stream)); } else { runnableCalls.push(preparation); @@ -508,7 +607,7 @@ async function executeToolCallsParallel( for (const skipped of remainingCalls) { results.push(skipToolCall(skipped, stream)); } - return { toolResults: results, steeringMessages }; + return { toolResults: results, steeringMessages, preparationErrorCount }; } } } @@ -540,7 +639,7 @@ async function executeToolCallsParallel( } } - return { toolResults: results, steeringMessages }; + return { toolResults: results, steeringMessages, preparationErrorCount }; } type PreparedToolCall = { diff --git a/packages/pi-agent-core/src/agent.test.ts b/packages/pi-agent-core/src/agent.test.ts index e0b838cd4..4ecd23af2 100644 --- a/packages/pi-agent-core/src/agent.test.ts +++ b/packages/pi-agent-core/src/agent.test.ts @@ -8,6 +8,8 @@ import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; import { join, dirname } from "node:path"; import { fileURLToPath } from "node:url"; +import { Agent } from "./agent.ts"; +import { getModel, type AssistantMessageEventStream } from "@gsd/pi-ai"; const __dirname = dirname(fileURLToPath(import.meta.url)); @@ -50,4 +52,84 @@ describe("Agent — activeInferenceModel (#1844 Bug 2)", () => { assert.ok(setLine < abortLine, "activeInferenceModel must be set before streaming infrastructure is created"); }); + + it("getProviderOptions are forwarded into the provider stream call", async () => { + let capturedOptions: Record | undefined; + const agent = new Agent({ + initialState: { + model: getModel("anthropic", "claude-3-5-sonnet-20241022"), + systemPrompt: "test", + tools: [], + }, + getProviderOptions: async () => ({ customRuntimeOption: "present" }), + streamFn: (_model, _context, options): AssistantMessageEventStream => { + capturedOptions = options as Record | undefined; + return { + async *[Symbol.asyncIterator]() { + yield { + type: "start", + partial: { + role: "assistant", + content: [], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-3-5-sonnet-20241022", + usage: { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 0, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }, + stopReason: "stop", + timestamp: Date.now(), + }, + }; + yield { + type: "done", + message: { + role: "assistant", + content: [{ type: "text", text: "ok" }], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-3-5-sonnet-20241022", + usage: { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 0, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }, + stopReason: "stop", + timestamp: Date.now(), + }, + }; + }, + result: async () => ({ + role: "assistant", + content: [{ type: "text", text: "ok" }], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-3-5-sonnet-20241022", + usage: { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 0, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }, + stopReason: "stop", + timestamp: Date.now(), + }), + [Symbol.asyncDispose]: async () => {}, + } as AssistantMessageEventStream; + }, + }); + + await agent.prompt("hello"); + assert.equal(capturedOptions?.customRuntimeOption, "present"); + }); }); diff --git a/packages/pi-agent-core/src/agent.ts b/packages/pi-agent-core/src/agent.ts index e65ae7a35..924dd8d39 100644 --- a/packages/pi-agent-core/src/agent.ts +++ b/packages/pi-agent-core/src/agent.ts @@ -108,6 +108,14 @@ export interface AgentOptions { * switches mid-session are handled correctly. */ externalToolExecution?: (model: Model) => boolean; + + /** + * Optional provider-specific options to merge into the next stream call. + * + * Use this for runtime-only callbacks or handles that should not live in + * shared agent state, such as UI bridges for external CLI providers. + */ + getProviderOptions?: (model: Model) => Record | undefined | Promise | undefined>; } /** @@ -152,6 +160,7 @@ export class Agent { private _beforeToolCall?: AgentLoopConfig["beforeToolCall"]; private _afterToolCall?: AgentLoopConfig["afterToolCall"]; private _externalToolExecution?: (model: Model) => boolean; + private _getProviderOptions?: AgentOptions["getProviderOptions"]; constructor(opts: AgentOptions = {}) { this._state = { ...this._state, ...opts.initialState }; @@ -167,6 +176,7 @@ export class Agent { this._transport = opts.transport ?? "sse"; this._maxRetryDelayMs = opts.maxRetryDelayMs; this._externalToolExecution = opts.externalToolExecution; + this._getProviderOptions = opts.getProviderOptions; } /** @@ -486,8 +496,10 @@ export class Agent { }; let skipInitialSteeringPoll = options?.skipInitialSteeringPoll === true; + const providerOptions = await this._getProviderOptions?.(model); const config: AgentLoopConfig = { + ...(providerOptions ?? {}), model, reasoning, sessionId: this._sessionId, diff --git a/packages/pi-agent-core/src/proxy.ts b/packages/pi-agent-core/src/proxy.ts index 619521bda..574ec2bf6 100644 --- a/packages/pi-agent-core/src/proxy.ts +++ b/packages/pi-agent-core/src/proxy.ts @@ -47,7 +47,7 @@ export type ProxyAssistantMessageEvent = | { type: "toolcall_end"; contentIndex: number } | { type: "done"; - reason: Extract; + reason: Extract; usage: AssistantMessage["usage"]; } | { diff --git a/packages/pi-ai/src/env-api-keys.ts b/packages/pi-ai/src/env-api-keys.ts index b6577d99d..1036c4b28 100644 --- a/packages/pi-ai/src/env-api-keys.ts +++ b/packages/pi-ai/src/env-api-keys.ts @@ -137,6 +137,7 @@ export function getEnvApiKey(provider: any): string | undefined { "opencode-go": "OPENCODE_API_KEY", "kimi-coding": "KIMI_API_KEY", "alibaba-coding-plan": "ALIBABA_API_KEY", + ollama: "OLLAMA_API_KEY", "ollama-cloud": "OLLAMA_API_KEY", "custom-openai": "CUSTOM_OPENAI_API_KEY", }; diff --git a/packages/pi-ai/src/index.ts b/packages/pi-ai/src/index.ts index a75aaf7f4..8b81cc22e 100644 --- a/packages/pi-ai/src/index.ts +++ b/packages/pi-ai/src/index.ts @@ -12,7 +12,10 @@ export * from "./providers/google-vertex.js"; export * from "./providers/mistral.js"; export * from "./providers/openai-completions.js"; export * from "./providers/openai-responses.js"; +export * from "./providers/provider-capabilities.js"; export * from "./providers/register-builtins.js"; +export type { ProviderSwitchReport } from "./providers/transform-messages.js"; +export { createEmptyReport, hasTransformations, transformMessagesWithReport } from "./providers/transform-messages.js"; export * from "./stream.js"; export * from "./types.js"; export * from "./utils/event-stream.js"; @@ -27,4 +30,5 @@ export type { } from "./utils/oauth/types.js"; export * from "./utils/overflow.js"; export * from "./utils/typebox-helpers.js"; +export * from "./utils/repair-tool-json.js"; export * from "./utils/validation.js"; diff --git a/packages/pi-ai/src/providers/amazon-bedrock.ts b/packages/pi-ai/src/providers/amazon-bedrock.ts index e8df99217..dee0c363e 100644 --- a/packages/pi-ai/src/providers/amazon-bedrock.ts +++ b/packages/pi-ai/src/providers/amazon-bedrock.ts @@ -43,7 +43,7 @@ import { AssistantMessageEventStream } from "../utils/event-stream.js"; import { parseStreamingJson } from "../utils/json-parse.js"; import { sanitizeSurrogates } from "../utils/sanitize-unicode.js"; import { adjustMaxTokensForThinking, buildBaseOptions, clampReasoning } from "./simple-options.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; export interface BedrockOptions extends StreamOptions { region?: string; @@ -487,7 +487,7 @@ function convertMessages( cacheRetention: CacheRetention, ): Message[] { const result: Message[] = []; - const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId); + const transformedMessages = transformMessagesWithReport(context.messages, model, normalizeToolCallId, "bedrock-converse-stream"); for (let i = 0; i < transformedMessages.length; i++) { const m = transformedMessages[i]; diff --git a/packages/pi-ai/src/providers/anthropic-shared.test.ts b/packages/pi-ai/src/providers/anthropic-shared.test.ts index a20c72d40..6e08bc52e 100644 --- a/packages/pi-ai/src/providers/anthropic-shared.test.ts +++ b/packages/pi-ai/src/providers/anthropic-shared.test.ts @@ -1,6 +1,6 @@ import { describe, it } from "node:test"; import assert from "node:assert/strict"; -import { convertTools } from "./anthropic-shared.js"; +import { convertTools, mapStopReason } from "./anthropic-shared.js"; const makeTool = (name: string) => ({ @@ -55,3 +55,29 @@ describe("convertTools cache_control", () => { assert.deepEqual((result[0] as any).cache_control, { type: "ephemeral" }); }); }); + +describe("mapStopReason", () => { + it("maps end_turn to stop", () => { + assert.equal(mapStopReason("end_turn"), "stop"); + }); + + it("maps max_tokens to length", () => { + assert.equal(mapStopReason("max_tokens"), "length"); + }); + + it("maps tool_use to toolUse", () => { + assert.equal(mapStopReason("tool_use"), "toolUse"); + }); + + it("maps pause_turn to pauseTurn (not stop)", () => { + // pause_turn means the server paused a long-running turn (e.g. native + // web search hit its iteration limit). Mapping it to "stop" causes the + // agent loop to exit, leaving an incomplete server_tool_use block in + // history which triggers a 400 on the next request. + assert.equal(mapStopReason("pause_turn"), "pauseTurn"); + }); + + it("throws on unknown stop reason", () => { + assert.throws(() => mapStopReason("bogus"), /Unhandled stop reason/); + }); +}); diff --git a/packages/pi-ai/src/providers/anthropic-shared.ts b/packages/pi-ai/src/providers/anthropic-shared.ts index 693ec54e6..567609147 100644 --- a/packages/pi-ai/src/providers/anthropic-shared.ts +++ b/packages/pi-ai/src/providers/anthropic-shared.ts @@ -31,8 +31,9 @@ import type { export type AnthropicApi = "anthropic-messages" | "anthropic-vertex"; import type { AssistantMessageEventStream } from "../utils/event-stream.js"; import { parseStreamingJson } from "../utils/json-parse.js"; +import { hasXmlParameterTags, repairToolJson } from "../utils/repair-tool-json.js"; import { sanitizeSurrogates } from "../utils/sanitize-unicode.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; export type AnthropicEffort = "low" | "medium" | "high" | "max"; @@ -234,7 +235,7 @@ export function convertMessages( ): MessageParam[] { const params: MessageParam[] = []; - const transformedMessages = transformMessages(messages, model, normalizeToolCallId); + const transformedMessages = transformMessagesWithReport(messages, model, normalizeToolCallId, "anthropic-messages"); for (let i = 0; i < transformedMessages.length; i++) { const msg = transformedMessages[i]; @@ -513,7 +514,7 @@ export function mapStopReason(reason: string): StopReason { case "refusal": return "error"; case "pause_turn": - return "stop"; + return "pauseTurn"; case "stop_sequence": return "stop"; case "sensitive": @@ -707,7 +708,22 @@ export function processAnthropicStream( partial: output, }); } else if (block.type === "toolCall") { - block.arguments = parseStreamingJson(block.partialJson); + // Try strict parse first; if it fails, attempt YAML bullet + // repair (#2660) before falling back to the lenient streaming + // parser which silently swallows errors. + const raw = block.partialJson ?? ""; + const rawForParse = hasXmlParameterTags(raw) ? repairToolJson(raw) : raw; + let parsed: Record | undefined; + try { + parsed = JSON.parse(rawForParse); + } catch { + try { + parsed = JSON.parse(repairToolJson(rawForParse)); + } catch { + // Fall through to streaming parser + } + } + block.arguments = parsed ?? parseStreamingJson(block.partialJson); delete (block as any).partialJson; stream.push({ type: "toolcall_end", diff --git a/packages/pi-ai/src/providers/anthropic.ts b/packages/pi-ai/src/providers/anthropic.ts index 21c0da707..57ee1b5be 100644 --- a/packages/pi-ai/src/providers/anthropic.ts +++ b/packages/pi-ai/src/providers/anthropic.ts @@ -34,9 +34,6 @@ async function getAnthropicClass(): Promise { return _AnthropicClass; } -// Stealth mode: Mimic Claude Code's tool naming exactly -const claudeCodeVersion = "2.1.62"; - function mergeHeaders(...headerSources: (Record | undefined)[]): Record { const merged: Record = {}; for (const headers of headerSources) { @@ -47,10 +44,6 @@ function mergeHeaders(...headerSources: (Record | undefined)[]): return merged; } -function isOAuthToken(apiKey: string): boolean { - return apiKey.includes("sk-ant-oat"); -} - async function createClient( model: Model<"anthropic-messages">, apiKey: string, @@ -97,30 +90,7 @@ async function createClient( betaFeatures.push("interleaved-thinking-2025-05-14"); } - // OAuth: Bearer auth, Claude Code identity headers - if (isOAuthToken(apiKey)) { - const client = new AnthropicClass({ - apiKey: null, - authToken: apiKey, - baseURL: model.baseUrl, - dangerouslyAllowBrowser: true, - defaultHeaders: mergeHeaders( - { - accept: "application/json", - "anthropic-dangerous-direct-browser-access": "true", - ...(betaFeatures.length > 0 ? { "anthropic-beta": `claude-code-20250219,oauth-2025-04-20,${betaFeatures.join(",")}` } : {}), - "user-agent": `claude-cli/${claudeCodeVersion}`, - "x-app": "cli", - }, - model.headers, - optionsHeaders, - ), - }); - - return { client, isOAuthToken: true }; - } - - // API key auth + // API key auth (Anthropic OAuth removed per TOS compliance — use API keys or Claude CLI) // Alibaba Coding Plan uses Bearer token auth instead of x-api-key const isAlibabaProvider = model.provider === "alibaba-coding-plan"; const client = new AnthropicClass({ diff --git a/packages/pi-ai/src/providers/google-shared.ts b/packages/pi-ai/src/providers/google-shared.ts index e6a31771f..7984bdd4b 100644 --- a/packages/pi-ai/src/providers/google-shared.ts +++ b/packages/pi-ai/src/providers/google-shared.ts @@ -5,7 +5,7 @@ import { type Content, FinishReason, FunctionCallingConfigMode, type Part } from "@google/genai"; import type { Context, ImageContent, Model, StopReason, TextContent, Tool } from "../types.js"; import { sanitizeSurrogates } from "../utils/sanitize-unicode.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; type GoogleApiType = "google-generative-ai" | "google-gemini-cli" | "google-vertex"; @@ -80,7 +80,7 @@ export function convertMessages(model: Model, contex return id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64); }; - const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId); + const transformedMessages = transformMessagesWithReport(context.messages, model, normalizeToolCallId, "google-generative-ai"); for (const msg of transformedMessages) { if (msg.role === "user") { diff --git a/packages/pi-ai/src/providers/mistral.ts b/packages/pi-ai/src/providers/mistral.ts index 7c9b54b91..0a6a28e5c 100644 --- a/packages/pi-ai/src/providers/mistral.ts +++ b/packages/pi-ai/src/providers/mistral.ts @@ -39,7 +39,7 @@ import { shortHash } from "../utils/hash.js"; import { parseStreamingJson } from "../utils/json-parse.js"; import { sanitizeSurrogates } from "../utils/sanitize-unicode.js"; import { buildBaseOptions, clampReasoning } from "./simple-options.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; const MISTRAL_TOOL_CALL_ID_LENGTH = 9; const MAX_MISTRAL_ERROR_BODY_CHARS = 4000; @@ -79,7 +79,7 @@ export const streamMistral: StreamFunction<"mistral-conversations", MistralOptio }); const normalizeMistralToolCallId = createMistralToolCallIdNormalizer(); - const transformedMessages = transformMessages(context.messages, model, (id) => normalizeMistralToolCallId(id)); + const transformedMessages = transformMessagesWithReport(context.messages, model, (id) => normalizeMistralToolCallId(id), "mistral-conversations"); let payload = buildChatPayload(model, context, transformedMessages, options); const nextPayload = await options?.onPayload?.(payload, model); diff --git a/packages/pi-ai/src/providers/openai-completions.ts b/packages/pi-ai/src/providers/openai-completions.ts index 261082aa2..51213ad39 100644 --- a/packages/pi-ai/src/providers/openai-completions.ts +++ b/packages/pi-ai/src/providers/openai-completions.ts @@ -39,7 +39,7 @@ import { finalizeStream, handleStreamError, } from "./openai-shared.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; /** * Check if conversation messages contain tool calls or tool results. @@ -455,7 +455,7 @@ export function convertMessages( return id; }; - const transformedMessages = transformMessages(context.messages, model, (id) => normalizeToolCallId(id)); + const transformedMessages = transformMessagesWithReport(context.messages, model, (id) => normalizeToolCallId(id), "openai-completions"); if (context.systemPrompt) { const useDeveloperRole = model.reasoning && compat.supportsDeveloperRole; diff --git a/packages/pi-ai/src/providers/openai-responses-shared.ts b/packages/pi-ai/src/providers/openai-responses-shared.ts index 10ac5ee1b..8227dcff5 100644 --- a/packages/pi-ai/src/providers/openai-responses-shared.ts +++ b/packages/pi-ai/src/providers/openai-responses-shared.ts @@ -30,7 +30,7 @@ import type { AssistantMessageEventStream } from "../utils/event-stream.js"; import { shortHash } from "../utils/hash.js"; import { parseStreamingJson } from "../utils/json-parse.js"; import { sanitizeSurrogates } from "../utils/sanitize-unicode.js"; -import { transformMessages } from "./transform-messages.js"; +import { transformMessagesWithReport } from "./transform-messages.js"; // ============================================================================= // Utilities @@ -108,7 +108,7 @@ export function convertResponsesMessages( return `${normalizedCallId}|${normalizedItemId}`; }; - const transformedMessages = transformMessages(context.messages, model, normalizeToolCallId); + const transformedMessages = transformMessagesWithReport(context.messages, model, normalizeToolCallId, "openai-responses"); const includeSystemPrompt = options?.includeSystemPrompt ?? true; if (includeSystemPrompt && context.systemPrompt) { diff --git a/packages/pi-ai/src/providers/provider-capabilities.test.ts b/packages/pi-ai/src/providers/provider-capabilities.test.ts new file mode 100644 index 000000000..7b8728975 --- /dev/null +++ b/packages/pi-ai/src/providers/provider-capabilities.test.ts @@ -0,0 +1,174 @@ +// GSD-2 — Provider Capabilities Registry Tests (ADR-005 Phase 1) +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; + +import { + PROVIDER_CAPABILITIES, + getProviderCapabilities, + getUnsupportedFeatures, + mergeCapabilityOverrides, + getRegisteredApis, +} from "./provider-capabilities.js"; + +// ─── Registry Completeness ────────────────────────────────────────────────── + +describe("PROVIDER_CAPABILITIES registry", () => { + const EXPECTED_APIS = [ + "anthropic-messages", + "anthropic-vertex", + "openai-responses", + "azure-openai-responses", + "openai-codex-responses", + "openai-completions", + "google-generative-ai", + "google-gemini-cli", + "google-vertex", + "mistral-conversations", + "bedrock-converse-stream", + "ollama-chat", + ]; + + test("covers all expected API providers", () => { + for (const api of EXPECTED_APIS) { + assert.ok( + PROVIDER_CAPABILITIES[api], + `Missing capability entry for API: ${api}`, + ); + } + }); + + test("getRegisteredApis returns all entries", () => { + const registered = getRegisteredApis(); + for (const api of EXPECTED_APIS) { + assert.ok(registered.includes(api), `getRegisteredApis missing: ${api}`); + } + }); + + test("all entries have required fields", () => { + for (const [api, caps] of Object.entries(PROVIDER_CAPABILITIES)) { + assert.equal(typeof caps.toolCalling, "boolean", `${api}.toolCalling`); + assert.equal(typeof caps.maxTools, "number", `${api}.maxTools`); + assert.equal(typeof caps.imageToolResults, "boolean", `${api}.imageToolResults`); + assert.equal(typeof caps.structuredOutput, "boolean", `${api}.structuredOutput`); + assert.ok(caps.toolCallIdFormat, `${api}.toolCallIdFormat`); + assert.equal(typeof caps.toolCallIdFormat.maxLength, "number", `${api}.toolCallIdFormat.maxLength`); + assert.ok(caps.toolCallIdFormat.allowedChars instanceof RegExp, `${api}.toolCallIdFormat.allowedChars`); + assert.ok( + ["full", "text-only", "none"].includes(caps.thinkingPersistence), + `${api}.thinkingPersistence is "${caps.thinkingPersistence}"`, + ); + assert.ok(Array.isArray(caps.unsupportedSchemaFeatures), `${api}.unsupportedSchemaFeatures`); + } + }); +}); + +// ─── Provider-specific Values ─────────────────────────────────────────────── + +describe("provider-specific capabilities", () => { + test("Anthropic supports full thinking persistence", () => { + assert.equal(PROVIDER_CAPABILITIES["anthropic-messages"].thinkingPersistence, "full"); + }); + + test("Anthropic supports image tool results", () => { + assert.equal(PROVIDER_CAPABILITIES["anthropic-messages"].imageToolResults, true); + }); + + test("Anthropic tool call ID is 64 chars max", () => { + assert.equal(PROVIDER_CAPABILITIES["anthropic-messages"].toolCallIdFormat.maxLength, 64); + }); + + test("Mistral tool call ID is 9 chars max", () => { + assert.equal(PROVIDER_CAPABILITIES["mistral-conversations"].toolCallIdFormat.maxLength, 9); + }); + + test("Mistral has no thinking persistence", () => { + assert.equal(PROVIDER_CAPABILITIES["mistral-conversations"].thinkingPersistence, "none"); + }); + + test("Google does not support patternProperties", () => { + assert.ok( + PROVIDER_CAPABILITIES["google-generative-ai"].unsupportedSchemaFeatures.includes("patternProperties"), + ); + }); + + test("Google does not support const", () => { + assert.ok( + PROVIDER_CAPABILITIES["google-generative-ai"].unsupportedSchemaFeatures.includes("const"), + ); + }); + + test("OpenAI Responses does not support image tool results", () => { + assert.equal(PROVIDER_CAPABILITIES["openai-responses"].imageToolResults, false); + }); + + test("OpenAI Responses has text-only thinking persistence", () => { + assert.equal(PROVIDER_CAPABILITIES["openai-responses"].thinkingPersistence, "text-only"); + }); +}); + +// ─── getProviderCapabilities ──────────────────────────────────────────────── + +describe("getProviderCapabilities", () => { + test("returns known provider capabilities", () => { + const caps = getProviderCapabilities("anthropic-messages"); + assert.equal(caps.toolCalling, true); + assert.equal(caps.thinkingPersistence, "full"); + }); + + test("returns permissive defaults for unknown providers", () => { + const caps = getProviderCapabilities("unknown-provider-xyz"); + assert.equal(caps.toolCalling, true); + assert.equal(caps.imageToolResults, true); + assert.deepEqual(caps.unsupportedSchemaFeatures, []); + }); +}); + +// ─── getUnsupportedFeatures ───────────────────────────────────────────────── + +describe("getUnsupportedFeatures", () => { + test("returns unsupported features for Google", () => { + const unsupported = getUnsupportedFeatures("google-generative-ai", ["patternProperties", "const"]); + assert.deepEqual(unsupported, ["patternProperties", "const"]); + }); + + test("returns empty for Anthropic with any features", () => { + const unsupported = getUnsupportedFeatures("anthropic-messages", ["patternProperties", "const"]); + assert.deepEqual(unsupported, []); + }); + + test("returns empty for unknown provider", () => { + const unsupported = getUnsupportedFeatures("unknown-xyz", ["patternProperties"]); + assert.deepEqual(unsupported, []); + }); +}); + +// ─── mergeCapabilityOverrides ─────────────────────────────────────────────── + +describe("mergeCapabilityOverrides", () => { + test("overrides individual fields", () => { + const merged = mergeCapabilityOverrides("openai-responses", { + imageToolResults: true, + }); + assert.equal(merged.imageToolResults, true); + // Non-overridden fields preserved + assert.equal(merged.toolCalling, true); + assert.equal(merged.thinkingPersistence, "text-only"); + }); + + test("deep-merges toolCallIdFormat", () => { + const merged = mergeCapabilityOverrides("anthropic-messages", { + toolCallIdFormat: { maxLength: 128 }, + }); + assert.equal(merged.toolCallIdFormat.maxLength, 128); + // allowedChars preserved from base + assert.ok(merged.toolCallIdFormat.allowedChars instanceof RegExp); + }); + + test("uses permissive defaults for unknown provider", () => { + const merged = mergeCapabilityOverrides("unknown-xyz", { + imageToolResults: false, + }); + assert.equal(merged.imageToolResults, false); + assert.equal(merged.toolCalling, true); // from default + }); +}); diff --git a/packages/pi-ai/src/providers/provider-capabilities.ts b/packages/pi-ai/src/providers/provider-capabilities.ts new file mode 100644 index 000000000..b49a1f319 --- /dev/null +++ b/packages/pi-ai/src/providers/provider-capabilities.ts @@ -0,0 +1,215 @@ +// GSD-2 — Provider Capabilities Registry (ADR-005 Phase 1) +// Declarative registry of what each API provider supports, consolidating +// scattered knowledge from *-shared.ts files into a queryable data structure. + +import type { Api } from "../types.js"; + +// ─── Types ────────────────────────────────────────────────────────────────── + +/** + * Declarative capability profile for an API provider. + * Used by the model router to filter incompatible models and by the tool + * system to adjust tool sets per provider. + */ +export interface ProviderCapabilities { + /** Whether models from this provider support tool/function calling */ + toolCalling: boolean; + /** Maximum number of tools the provider handles well (0 = unlimited) */ + maxTools: number; + /** Whether tool results can contain images */ + imageToolResults: boolean; + /** Whether the provider supports structured JSON output */ + structuredOutput: boolean; + /** Tool call ID format constraints */ + toolCallIdFormat: { + maxLength: number; + allowedChars: RegExp; + }; + /** Whether thinking/reasoning blocks are preserved cross-turn */ + thinkingPersistence: "full" | "text-only" | "none"; + /** Schema features NOT supported (tools using these get filtered) */ + unsupportedSchemaFeatures: string[]; +} + +// ─── Registry ─────────────────────────────────────────────────────────────── + +/** + * Built-in provider capability profiles. + * + * Sources (consolidated from scattered *-shared.ts files): + * - anthropic-shared.ts: normalizeToolCallId (64-char, [a-zA-Z0-9_-]) + * - openai-responses-shared.ts: ID normalization (64-char, fc_ prefix), image-in-tool-result workaround + * - google-shared.ts: sanitizeSchemaForGoogle (patternProperties, const), requiresToolCallId + * - mistral.ts: MISTRAL_TOOL_CALL_ID_LENGTH = 9 + * - amazon-bedrock.ts: normalizeToolCallId (64-char, [a-zA-Z0-9_-]) + */ +export const PROVIDER_CAPABILITIES: Record = { + "anthropic-messages": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "full", + unsupportedSchemaFeatures: [], + }, + "anthropic-vertex": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "full", + unsupportedSchemaFeatures: [], + }, + "openai-responses": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, // images sent as separate user message, not in tool result + structuredOutput: true, + toolCallIdFormat: { maxLength: 512, allowedChars: /^.+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], + }, + "azure-openai-responses": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, + structuredOutput: true, + toolCallIdFormat: { maxLength: 512, allowedChars: /^.+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], + }, + "openai-codex-responses": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], + }, + "openai-completions": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], + }, + "google-generative-ai": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: ["patternProperties", "const"], + }, + "google-gemini-cli": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: ["patternProperties", "const"], + }, + "google-vertex": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: ["patternProperties", "const"], + }, + "mistral-conversations": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, + structuredOutput: true, + toolCallIdFormat: { maxLength: 9, allowedChars: /^[a-zA-Z0-9]+$/ }, + thinkingPersistence: "none", + unsupportedSchemaFeatures: [], + }, + "bedrock-converse-stream": { + toolCalling: true, + maxTools: 0, + imageToolResults: true, // Bedrock supports image content blocks in tool results + structuredOutput: true, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], + }, + "ollama-chat": { + toolCalling: true, + maxTools: 0, + imageToolResults: false, + structuredOutput: false, + toolCallIdFormat: { maxLength: 64, allowedChars: /^[a-zA-Z0-9_-]+$/ }, + thinkingPersistence: "none", + unsupportedSchemaFeatures: [], + }, +}; + +// ─── Default (permissive) profile for unknown providers ───────────────────── + +const DEFAULT_CAPABILITIES: ProviderCapabilities = { + toolCalling: true, + maxTools: 0, + imageToolResults: true, + structuredOutput: true, + toolCallIdFormat: { maxLength: 512, allowedChars: /^.+$/ }, + thinkingPersistence: "text-only", + unsupportedSchemaFeatures: [], +}; + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Get capabilities for a provider API. Returns a permissive default for + * unknown providers (preserving existing behavior per ADR-005 principle 5). + */ +export function getProviderCapabilities(api: string): ProviderCapabilities { + return PROVIDER_CAPABILITIES[api] ?? DEFAULT_CAPABILITIES; +} + +/** + * Check if a provider supports all required schema features. + * Returns the list of unsupported features (empty if all supported). + */ +export function getUnsupportedFeatures(api: string, requiredFeatures: string[]): string[] { + const caps = getProviderCapabilities(api); + return requiredFeatures.filter(f => caps.unsupportedSchemaFeatures.includes(f)); +} + +/** + * Deep-merge user-provided capability overrides with built-in defaults. + * Partial overrides merge with the built-in profile for the given API. + */ +export function mergeCapabilityOverrides( + api: string, + overrides: Partial> & { + toolCallIdFormat?: Partial; + }, +): ProviderCapabilities { + const base = getProviderCapabilities(api); + return { + ...base, + ...overrides, + toolCallIdFormat: overrides.toolCallIdFormat + ? { ...base.toolCallIdFormat, ...overrides.toolCallIdFormat } + : base.toolCallIdFormat, + }; +} + +/** + * Get all registered API names in the capability registry. + * Used by lint rules to verify all providers in register-builtins.ts + * have corresponding capability entries. + */ +export function getRegisteredApis(): string[] { + return Object.keys(PROVIDER_CAPABILITIES); +} diff --git a/packages/pi-ai/src/providers/transform-messages-report.test.ts b/packages/pi-ai/src/providers/transform-messages-report.test.ts new file mode 100644 index 000000000..85ae585ba --- /dev/null +++ b/packages/pi-ai/src/providers/transform-messages-report.test.ts @@ -0,0 +1,189 @@ +// GSD-2 — ProviderSwitchReport Tests (ADR-005 Phase 3) +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; + +import { transformMessages, createEmptyReport, hasTransformations } from "./transform-messages.js"; +import type { ProviderSwitchReport } from "./transform-messages.js"; +import type { Message, Model, AssistantMessage, ToolCall } from "../types.js"; + +// ─── Helpers ──────────────────────────────────────────────────────────────── + +function makeModel(overrides: Partial> = {}): Model { + return { + id: "claude-sonnet-4-6", + name: "Claude Sonnet 4.6", + api: "anthropic-messages", + provider: "anthropic", + baseUrl: "", + reasoning: false, + input: ["text", "image"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 200000, + maxTokens: 8192, + ...overrides, + } as Model; +} + +function makeAssistantMsg(overrides: Partial = {}): AssistantMessage { + return { + role: "assistant", + content: [], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-sonnet-4-6", + usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, + stopReason: "stop", + timestamp: Date.now(), + ...overrides, + }; +} + +// ─── createEmptyReport / hasTransformations ───────────────────────────────── + +describe("createEmptyReport", () => { + test("creates report with zero counters", () => { + const report = createEmptyReport("anthropic-messages", "openai-responses"); + assert.equal(report.fromApi, "anthropic-messages"); + assert.equal(report.toApi, "openai-responses"); + assert.equal(report.thinkingBlocksDropped, 0); + assert.equal(report.thinkingBlocksDowngraded, 0); + assert.equal(report.toolCallIdsRemapped, 0); + assert.equal(report.syntheticToolResultsInserted, 0); + assert.equal(report.thoughtSignaturesDropped, 0); + }); +}); + +describe("hasTransformations", () => { + test("returns false for empty report", () => { + const report = createEmptyReport("a", "b"); + assert.equal(hasTransformations(report), false); + }); + + test("returns true when any counter is non-zero", () => { + const report = createEmptyReport("a", "b"); + report.thinkingBlocksDropped = 1; + assert.equal(hasTransformations(report), true); + }); +}); + +// ─── Report Tracking in transformMessages ─────────────────────────────────── + +describe("transformMessages with report tracking", () => { + test("tracks thinking blocks dropped for redacted cross-model", () => { + const model = makeModel({ id: "gpt-5", api: "openai-responses", provider: "openai" }); + const messages: Message[] = [ + makeAssistantMsg({ + content: [ + { type: "thinking", thinking: "", redacted: true }, + { type: "text", text: "Hello" }, + ], + }), + ]; + const report = createEmptyReport("anthropic-messages", "openai-responses"); + transformMessages(messages, model, undefined, report); + assert.equal(report.thinkingBlocksDropped, 1); + }); + + test("tracks thinking blocks downgraded to plain text", () => { + const model = makeModel({ id: "gpt-5", api: "openai-responses", provider: "openai" }); + const messages: Message[] = [ + makeAssistantMsg({ + content: [ + { type: "thinking", thinking: "Let me think about this..." }, + { type: "text", text: "Here is my answer" }, + ], + }), + ]; + const report = createEmptyReport("anthropic-messages", "openai-responses"); + transformMessages(messages, model, undefined, report); + assert.equal(report.thinkingBlocksDowngraded, 1); + }); + + test("tracks tool call IDs remapped", () => { + const model = makeModel({ id: "claude-sonnet-4-6", api: "anthropic-messages", provider: "anthropic" }); + const toolCall: ToolCall = { + type: "toolCall", + id: "original-long-id-that-needs-normalization|with-special-chars", + name: "bash", + arguments: { command: "ls" }, + }; + const messages: Message[] = [ + makeAssistantMsg({ + provider: "openai", + api: "openai-responses", + model: "gpt-5", + content: [toolCall], + }), + ]; + const normalizer = (id: string) => id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64); + const report = createEmptyReport("openai-responses", "anthropic-messages"); + transformMessages(messages, model, normalizer, report); + assert.equal(report.toolCallIdsRemapped, 1); + }); + + test("tracks thought signatures dropped", () => { + const model = makeModel({ id: "claude-sonnet-4-6", api: "anthropic-messages", provider: "anthropic" }); + const toolCall: ToolCall = { + type: "toolCall", + id: "tc_001", + name: "bash", + arguments: { command: "ls" }, + thoughtSignature: "some-opaque-signature", + }; + const messages: Message[] = [ + makeAssistantMsg({ + provider: "google", + api: "google-generative-ai", + model: "gemini-2.5-pro", + content: [toolCall], + }), + ]; + const report = createEmptyReport("google-generative-ai", "anthropic-messages"); + transformMessages(messages, model, undefined, report); + assert.equal(report.thoughtSignaturesDropped, 1); + }); + + test("tracks synthetic tool results inserted", () => { + const model = makeModel(); + const toolCall: ToolCall = { + type: "toolCall", + id: "tc_orphan", + name: "bash", + arguments: { command: "ls" }, + }; + // Assistant message with tool call followed by another assistant (no tool result) + const messages: Message[] = [ + makeAssistantMsg({ content: [toolCall, { type: "text", text: "Using bash" }] }), + makeAssistantMsg({ content: [{ type: "text", text: "Next message" }] }), + ]; + const report = createEmptyReport("anthropic-messages", "anthropic-messages"); + transformMessages(messages, model, undefined, report); + assert.equal(report.syntheticToolResultsInserted, 1); + }); + + test("does not count transformations for same-model messages", () => { + const model = makeModel(); + const messages: Message[] = [ + makeAssistantMsg({ + content: [ + { type: "thinking", thinking: "Let me think..." }, + { type: "text", text: "Answer" }, + ], + }), + ]; + const report = createEmptyReport("anthropic-messages", "anthropic-messages"); + transformMessages(messages, model, undefined, report); + assert.equal(report.thinkingBlocksDowngraded, 0); + assert.equal(report.thinkingBlocksDropped, 0); + }); + + test("works without report parameter (backward compatible)", () => { + const model = makeModel(); + const messages: Message[] = [ + makeAssistantMsg({ content: [{ type: "text", text: "Hello" }] }), + ]; + // Should not throw + const result = transformMessages(messages, model); + assert.ok(Array.isArray(result)); + }); +}); diff --git a/packages/pi-ai/src/providers/transform-messages.ts b/packages/pi-ai/src/providers/transform-messages.ts index f61f08037..bcfd5234a 100644 --- a/packages/pi-ai/src/providers/transform-messages.ts +++ b/packages/pi-ai/src/providers/transform-messages.ts @@ -1,5 +1,87 @@ import type { Api, AssistantMessage, Message, Model, ToolCall, ToolResultMessage } from "../types.js"; +/** + * Report of context transformations during a cross-provider switch (ADR-005 Phase 3). + * Tracks what was lost or downgraded when replaying conversation history to a different provider. + */ +export interface ProviderSwitchReport { + /** API of the messages being transformed from */ + fromApi: string; + /** API of the target model */ + toApi: string; + /** Number of thinking blocks completely dropped (redacted/encrypted, cross-model) */ + thinkingBlocksDropped: number; + /** Number of thinking blocks downgraded from structured to plain text */ + thinkingBlocksDowngraded: number; + /** Number of tool call IDs that were remapped/normalized */ + toolCallIdsRemapped: number; + /** Number of synthetic tool results inserted for orphaned tool calls */ + syntheticToolResultsInserted: number; + /** Number of thought signatures dropped (Google-specific opaque context) */ + thoughtSignaturesDropped: number; +} + +/** + * Create an empty provider switch report. + */ +export function createEmptyReport(fromApi: string, toApi: string): ProviderSwitchReport { + return { + fromApi, + toApi, + thinkingBlocksDropped: 0, + thinkingBlocksDowngraded: 0, + toolCallIdsRemapped: 0, + syntheticToolResultsInserted: 0, + thoughtSignaturesDropped: 0, + }; +} + +/** + * Check if a provider switch report has any non-zero transformations. + */ +export function hasTransformations(report: ProviderSwitchReport): boolean { + return ( + report.thinkingBlocksDropped > 0 || + report.thinkingBlocksDowngraded > 0 || + report.toolCallIdsRemapped > 0 || + report.syntheticToolResultsInserted > 0 || + report.thoughtSignaturesDropped > 0 + ); +} + +/** + * Create a report, run transformMessages, and log if non-empty. + * Convenience wrapper for provider adapters (ADR-005). + */ +export function transformMessagesWithReport( + messages: Message[], + model: Model, + normalizeToolCallId?: (id: string, model: Model, source: AssistantMessage) => string, + sourceApi?: string, +): Message[] { + const report = createEmptyReport(sourceApi ?? "unknown", model.api); + const result = transformMessages(messages, model, normalizeToolCallId, report); + if (hasTransformations(report)) { + logProviderSwitchReport(report); + } + return result; +} + +/** Log a non-empty ProviderSwitchReport as a debug-level warning. */ +function logProviderSwitchReport(report: ProviderSwitchReport): void { + const parts: string[] = [`Provider switch ${report.fromApi} → ${report.toApi}:`]; + if (report.thinkingBlocksDropped > 0) parts.push(`${report.thinkingBlocksDropped} thinking blocks dropped`); + if (report.thinkingBlocksDowngraded > 0) parts.push(`${report.thinkingBlocksDowngraded} thinking blocks downgraded`); + if (report.toolCallIdsRemapped > 0) parts.push(`${report.toolCallIdsRemapped} tool call IDs remapped`); + if (report.syntheticToolResultsInserted > 0) parts.push(`${report.syntheticToolResultsInserted} synthetic tool results inserted`); + if (report.thoughtSignaturesDropped > 0) parts.push(`${report.thoughtSignaturesDropped} thought signatures dropped`); + // Use process.stderr for debug output — this is observable in verbose/debug modes + // without polluting stdout which may be used for structured output (RPC/MCP). + if (process.env.GSD_VERBOSE === "1" || process.env.PI_VERBOSE === "1") { + process.stderr.write(`[provider-switch] ${parts.join(", ")}\n`); + } +} + /** * Normalize tool call ID for cross-provider compatibility. * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`. @@ -9,6 +91,7 @@ export function transformMessages( messages: Message[], model: Model, normalizeToolCallId?: (id: string, model: Model, source: AssistantMessage) => string, + report?: ProviderSwitchReport, ): Message[] { // Build a map of original tool call IDs to normalized IDs const toolCallIdMap = new Map(); @@ -42,14 +125,20 @@ export function transformMessages( // Redacted thinking is opaque encrypted content, only valid for the same model. // Drop it for cross-model to avoid API errors. if (block.redacted) { + if (!isSameModel && report) report.thinkingBlocksDropped++; return isSameModel ? block : []; } // For same model: keep thinking blocks with signatures (needed for replay) // even if the thinking text is empty (OpenAI encrypted reasoning) if (isSameModel && block.thinkingSignature) return block; // Skip empty thinking blocks, convert others to plain text - if (!block.thinking || block.thinking.trim() === "") return []; + if (!block.thinking || block.thinking.trim() === "") { + if (!isSameModel && report) report.thinkingBlocksDropped++; + return []; + } if (isSameModel) return block; + // Downgrade: structured thinking → plain text + if (report) report.thinkingBlocksDowngraded++; return { type: "text" as const, text: block.thinking, @@ -71,6 +160,7 @@ export function transformMessages( if (!isSameModel && toolCall.thoughtSignature) { normalizedToolCall = { ...toolCall }; delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature; + if (report) report.thoughtSignaturesDropped++; } if (!isSameModel && normalizeToolCallId) { @@ -78,6 +168,7 @@ export function transformMessages( if (normalizedId !== toolCall.id) { toolCallIdMap.set(toolCall.id, normalizedId); normalizedToolCall = { ...normalizedToolCall, id: normalizedId }; + if (report) report.toolCallIdsRemapped++; } } @@ -117,6 +208,7 @@ export function transformMessages( isError: true, timestamp: Date.now(), } as ToolResultMessage); + if (report) report.syntheticToolResultsInserted++; } } pendingToolCalls = []; @@ -157,6 +249,7 @@ export function transformMessages( isError: true, timestamp: Date.now(), } as ToolResultMessage); + if (report) report.syntheticToolResultsInserted++; } } pendingToolCalls = []; diff --git a/packages/pi-ai/src/types.ts b/packages/pi-ai/src/types.ts index f4d63e1de..661b58b57 100644 --- a/packages/pi-ai/src/types.ts +++ b/packages/pi-ai/src/types.ts @@ -13,7 +13,8 @@ export type KnownApi = | "bedrock-converse-stream" | "google-generative-ai" | "google-gemini-cli" - | "google-vertex"; + | "google-vertex" + | "ollama-chat"; export type Api = KnownApi | (string & {}); @@ -43,6 +44,7 @@ export type KnownProvider = | "opencode-go" | "kimi-coding" | "alibaba-coding-plan" + | "ollama" | "ollama-cloud"; export type Provider = KnownProvider | string; @@ -192,7 +194,7 @@ export interface Usage { }; } -export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted"; +export type StopReason = "stop" | "length" | "toolUse" | "pauseTurn" | "error" | "aborted"; export interface UserMessage { role: "user"; @@ -211,9 +213,23 @@ export interface AssistantMessage { errorMessage?: string; /** Server-requested retry delay in milliseconds (from Retry-After or rate limit headers). */ retryAfterMs?: number; + /** Provider inference performance metrics (e.g. tokens/sec from local models). */ + inferenceMetrics?: InferenceMetrics; timestamp: number; // Unix timestamp in milliseconds } +/** Inference performance metrics reported by providers that support it (e.g. Ollama). */ +export interface InferenceMetrics { + /** Tokens generated per second during eval phase. */ + tokensPerSecond: number; + /** Wall-clock duration of the full request in milliseconds. */ + totalDurationMs: number; + /** Duration of the eval (generation) phase in milliseconds. */ + evalDurationMs: number; + /** Duration of the prompt eval phase in milliseconds. */ + promptEvalDurationMs: number; +} + export interface ToolResultMessage { role: "toolResult"; toolCallId: string; @@ -253,7 +269,7 @@ export type AssistantMessageEvent = | { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage; malformedArguments?: boolean } | { type: "server_tool_use"; contentIndex: number; partial: AssistantMessage } | { type: "web_search_result"; contentIndex: number; partial: AssistantMessage } - | { type: "done"; reason: Extract; message: AssistantMessage } + | { type: "done"; reason: Extract; message: AssistantMessage } | { type: "error"; reason: Extract; error: AssistantMessage }; /** @@ -373,4 +389,6 @@ export interface Model { * Read these fields instead of pattern-matching on model IDs or provider names. */ capabilities?: ModelCapabilities; + /** Opaque provider-specific options. Cast to the appropriate type in the provider's stream handler. */ + providerOptions?: Record; } diff --git a/packages/pi-ai/src/utils/event-stream.ts b/packages/pi-ai/src/utils/event-stream.ts index 74947477e..7eb0a0104 100644 --- a/packages/pi-ai/src/utils/event-stream.ts +++ b/packages/pi-ai/src/utils/event-stream.ts @@ -80,3 +80,8 @@ export class AssistantMessageEventStream extends EventStream(partialJson: string | undefined): T { - return nativeParseStreamingJson(partialJson); + if (!partialJson || partialJson.trim() === "") { + return {} as T; + } + + // Fast path: try native streaming parser first + const result = nativeParseStreamingJson(partialJson); + + // XML parameter tags can be trapped inside otherwise valid JSON strings, + // so run repair before trusting the native parse result. + if (hasXmlParameterTags(partialJson)) { + try { + return JSON.parse(repairToolJson(partialJson)) as T; + } catch { + // Fall through to the native parser result on incomplete partials + } + } + + // If the native parser returned a non-empty result, use it. + // Only attempt repair when the result is empty AND the input + // contains YAML bullet patterns (avoids unnecessary work). + if ( + result && + typeof result === "object" && + Object.keys(result as object).length === 0 && + hasYamlBulletLists(partialJson) + ) { + try { + return JSON.parse(repairToolJson(partialJson)) as T; + } catch { + // Repair failed — return the empty object from native parser + } + } + + return result; } diff --git a/packages/pi-ai/src/utils/oauth/anthropic.ts b/packages/pi-ai/src/utils/oauth/anthropic.ts deleted file mode 100644 index 861e26409..000000000 --- a/packages/pi-ai/src/utils/oauth/anthropic.ts +++ /dev/null @@ -1,140 +0,0 @@ -/** - * Anthropic OAuth flow (Claude Pro/Max) - */ - -import { generatePKCE } from "./pkce.js"; -import type { OAuthCredentials, OAuthLoginCallbacks, OAuthProviderInterface } from "./types.js"; - -const decode = (s: string) => atob(s); -const CLIENT_ID = decode("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl"); -const AUTHORIZE_URL = "https://claude.ai/oauth/authorize"; -const TOKEN_URL = "https://platform.claude.com/v1/oauth/token"; -const REDIRECT_URI = "https://platform.claude.com/oauth/code/callback"; -const SCOPES = "org:create_api_key user:profile user:inference"; - -/** - * Login with Anthropic OAuth (device code flow) - * - * @param onAuthUrl - Callback to handle the authorization URL (e.g., open browser) - * @param onPromptCode - Callback to prompt user for the authorization code - */ -export async function loginAnthropic( - onAuthUrl: (url: string) => void, - onPromptCode: () => Promise, -): Promise { - const { verifier, challenge } = await generatePKCE(); - - // Build authorization URL - const authParams = new URLSearchParams({ - code: "true", - client_id: CLIENT_ID, - response_type: "code", - redirect_uri: REDIRECT_URI, - scope: SCOPES, - code_challenge: challenge, - code_challenge_method: "S256", - state: verifier, - }); - - const authUrl = `${AUTHORIZE_URL}?${authParams.toString()}`; - - // Notify caller with URL to open - onAuthUrl(authUrl); - - // Wait for user to paste authorization code (format: code#state) - const authCode = await onPromptCode(); - const splits = authCode.split("#"); - const code = splits[0]; - const state = splits[1]; - - // Exchange code for tokens - const tokenResponse = await fetch(TOKEN_URL, { - method: "POST", - headers: { - "Content-Type": "application/json", - }, - body: JSON.stringify({ - grant_type: "authorization_code", - client_id: CLIENT_ID, - code: code, - state: state, - redirect_uri: REDIRECT_URI, - code_verifier: verifier, - }), - signal: AbortSignal.timeout(30_000), - }); - - if (!tokenResponse.ok) { - const error = await tokenResponse.text(); - throw new Error(`Token exchange failed: ${error}`); - } - - const tokenData = (await tokenResponse.json()) as { - access_token: string; - refresh_token: string; - expires_in: number; - }; - - // Calculate expiry time (current time + expires_in seconds - 5 min buffer) - const expiresAt = Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000; - - // Save credentials - return { - refresh: tokenData.refresh_token, - access: tokenData.access_token, - expires: expiresAt, - }; -} - -/** - * Refresh Anthropic OAuth token - */ -export async function refreshAnthropicToken(refreshToken: string): Promise { - const response = await fetch(TOKEN_URL, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - grant_type: "refresh_token", - client_id: CLIENT_ID, - refresh_token: refreshToken, - }), - signal: AbortSignal.timeout(30_000), - }); - - if (!response.ok) { - const error = await response.text(); - throw new Error(`Anthropic token refresh failed: ${error}`); - } - - const data = (await response.json()) as { - access_token: string; - refresh_token: string; - expires_in: number; - }; - - return { - refresh: data.refresh_token, - access: data.access_token, - expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, - }; -} - -export const anthropicOAuthProvider: OAuthProviderInterface = { - id: "anthropic", - name: "Anthropic (Claude Pro/Max)", - - async login(callbacks: OAuthLoginCallbacks): Promise { - return loginAnthropic( - (url) => callbacks.onAuth({ url }), - () => callbacks.onPrompt({ message: "Paste the authorization code:" }), - ); - }, - - async refreshToken(credentials: OAuthCredentials): Promise { - return refreshAnthropicToken(credentials.refresh); - }, - - getApiKey(credentials: OAuthCredentials): string { - return credentials.access; - }, -}; diff --git a/packages/pi-ai/src/utils/oauth/index.ts b/packages/pi-ai/src/utils/oauth/index.ts index a91decf4a..715b4910c 100644 --- a/packages/pi-ai/src/utils/oauth/index.ts +++ b/packages/pi-ai/src/utils/oauth/index.ts @@ -3,14 +3,14 @@ * * This module handles login, token refresh, and credential storage * for OAuth-based providers: - * - Anthropic (Claude Pro/Max) * - GitHub Copilot * - Google Cloud Code Assist (Gemini CLI) * - Antigravity (Gemini 3, Claude, GPT-OSS via Google Cloud) + * + * Note: Anthropic OAuth was removed per TOS compliance (see docs/user-docs/claude-code-auth-compliance.md). + * Use API keys or the local Claude Code CLI for Anthropic access. */ -// Anthropic -export { anthropicOAuthProvider, loginAnthropic, refreshAnthropicToken } from "./anthropic.js"; // GitHub Copilot export { getGitHubCopilotBaseUrl, @@ -32,7 +32,6 @@ export * from "./types.js"; // Provider Registry // ============================================================================ -import { anthropicOAuthProvider } from "./anthropic.js"; import { githubCopilotOAuthProvider } from "./github-copilot.js"; import { antigravityOAuthProvider } from "./google-antigravity.js"; import { geminiCliOAuthProvider } from "./google-gemini-cli.js"; @@ -40,7 +39,6 @@ import { openaiCodexOAuthProvider } from "./openai-codex.js"; import type { OAuthCredentials, OAuthProviderId, OAuthProviderInterface } from "./types.js"; const BUILT_IN_OAUTH_PROVIDERS: OAuthProviderInterface[] = [ - anthropicOAuthProvider, githubCopilotOAuthProvider, geminiCliOAuthProvider, antigravityOAuthProvider, diff --git a/packages/pi-ai/src/utils/repair-tool-json.ts b/packages/pi-ai/src/utils/repair-tool-json.ts new file mode 100644 index 000000000..27ea7b14c --- /dev/null +++ b/packages/pi-ai/src/utils/repair-tool-json.ts @@ -0,0 +1,220 @@ +/** + * Repair malformed JSON in LLM tool-call arguments. + * + * LLMs sometimes copy YAML template formatting into JSON tool arguments, + * producing patterns like: + * + * "keyDecisions": - Used Web Notification API..., + * "keyFiles": - src-tauri/src/lib.rs — Extended... + * + * instead of valid JSON arrays: + * + * "keyDecisions": ["Used Web Notification API..."], + * "keyFiles": ["src-tauri/src/lib.rs — Extended..."] + * + * This module detects and repairs such patterns before JSON.parse is called. + * + * @see https://github.com/gsd-build/gsd-2/issues/2660 + */ + +/** + * Detect whether a JSON string contains YAML-style bullet-list values + * (i.e. `"key": - item` instead of `"key": ["item"]`). + */ +export function hasYamlBulletLists(json: string): boolean { + // Match: "key": followed by whitespace then a dash-space pattern (YAML bullet) + // The negative lookahead excludes negative numbers (e.g. "key": -1) + return /"\s*:\s*-\s+(?!\d)/.test(json); +} + +/** + * Detect whether a JSON string contains XML parameter tags + * (i.e. `value`). + * + * Some models mix XML tool-call syntax into JSON string values, + * producing hybrid output that fails JSON.parse. + * + * @see https://github.com/gsd-build/gsd-2/issues/3403 + */ +export function hasXmlParameterTags(json: string): boolean { + return /<\/?parameter[\s>]/.test(json); +} + +/** + * Detect whether a JSON string contains truncated numeric values + * (e.g. `"exitCode": -,` or `"durationMs": ,`). + * + * Smaller models sometimes emit incomplete numbers when the value + * is cut off mid-generation. + * + * @see https://github.com/gsd-build/gsd-2/issues/3464 + */ +export function hasTruncatedNumbers(json: string): boolean { + // Match: colon, optional whitespace, then a comma or } without a value + // Or: colon, optional whitespace, bare minus sign followed by comma/} + return /:\s*,/.test(json) || /:\s*-\s*[,}]/.test(json); +} + +type XmlParameterBlock = { + name: string; + value: unknown; +}; + +const xmlParameterBlockPattern = /([\s\S]*?)<\/parameter>/g; + +function parseXmlParameterValue(raw: string): unknown { + const trimmed = raw.trim(); + if (trimmed === "") return ""; + try { + return JSON.parse(trimmed); + } catch { + return trimmed; + } +} + +function extractXmlParameterBlocks(text: string): XmlParameterBlock[] { + const blocks: XmlParameterBlock[] = []; + for (const match of text.matchAll(xmlParameterBlockPattern)) { + blocks.push({ + name: match[1], + value: parseXmlParameterValue(match[2] ?? ""), + }); + } + return blocks; +} + +function trimLeakedXmlTail(fieldName: string, value: string): string { + let cut = value.length; + const parameterIndex = value.indexOf("= 0) cut = Math.min(cut, parameterIndex); + + const closingTagIndex = value.indexOf(``); + if (closingTagIndex >= 0) cut = Math.min(cut, closingTagIndex); + + return value.slice(0, cut).trimEnd(); +} + +/** + * Strip XML `` tags from a JSON string, leaving only the + * text content. This handles the case where the LLM mixes XML + * tool-call format into JSON string values. + */ +function stripXmlParameterTags(json: string): string { + // Remove opening tags: + let cleaned = json.replace(//g, ""); + // Remove closing tags: + cleaned = cleaned.replace(/<\/parameter>/g, ""); + return cleaned; +} + +function promoteXmlParametersToTopLevel(json: string): string { + try { + const parsed = JSON.parse(json) as Record; + if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { + return stripXmlParameterTags(json); + } + + let changed = false; + for (const [fieldName, value] of Object.entries(parsed)) { + if (typeof value !== "string" || !hasXmlParameterTags(value)) continue; + + const blocks = extractXmlParameterBlocks(value); + if (blocks.length === 0) continue; + + parsed[fieldName] = trimLeakedXmlTail(fieldName, value); + for (const block of blocks) { + if (!(block.name in parsed)) { + parsed[block.name] = block.value; + } + } + changed = true; + } + + return changed ? JSON.stringify(parsed) : stripXmlParameterTags(json); + } catch { + return stripXmlParameterTags(json); + } +} + +/** + * Replace truncated numeric values with 0. + * Handles: `"key": ,` → `"key": 0,` and `"key": -,` → `"key": 0,` + */ +function repairTruncatedNumbers(json: string): string { + // Bare comma after colon (missing value entirely) + let repaired = json.replace(/:\s*,/g, ": 0,"); + // Bare minus sign followed by comma or closing brace + repaired = repaired.replace(/:\s*-\s*([,}])/g, ": 0$1"); + return repaired; +} + +/** + * Attempt to repair malformed JSON in LLM tool-call arguments. + * + * Handles three categories of malformation: + * + * 1. **YAML bullet lists** (#2660): `"key": - item1\n - item2` → `"key": ["item1", "item2"]` + * 2. **XML parameter tags** (#3403): `value` → stripped to content + * 3. **Truncated numbers** (#3464): `"exitCode": -,` → `"exitCode": 0,` + * + * Returns the original string unchanged if no patterns are detected + * or if the repair itself would produce invalid JSON. + */ +export function repairToolJson(json: string): string { + let repaired = json; + + // Phase 1: Strip XML parameter tags + if (hasXmlParameterTags(repaired)) { + repaired = promoteXmlParametersToTopLevel(repaired); + } + + // Phase 2: Repair truncated numbers + if (hasTruncatedNumbers(repaired)) { + repaired = repairTruncatedNumbers(repaired); + } + + // Phase 3: Repair YAML bullet lists + if (!hasYamlBulletLists(repaired)) { + return repaired; + } + + // Strategy: find each `"key": - item1\n - item2\n - item3` region and + // wrap items in a JSON array. + // + // We work on the raw string because the JSON is not parseable yet. + // The pattern we target: + // "someKey":\s*- item text (possibly multiline) + // optionally followed by more `- item` lines + // terminated by the next `"key":` or `}` or end of string. + + // Match a key followed by YAML-style bullet list. + // Capture: (1) the key portion including colon, (2) the bullet-list body, + // (3) the separator (comma or empty) before the next key/bracket. + // The bullet list body ends at the next `"key":` or `}` or `]` or end of string. + const keyBulletPattern = + /("(?:[^"\\]|\\.)*"\s*:\s*)(- .+?)(,?\s*)(?="(?:[^"\\]|\\.)*"\s*:|[}\]]|$)/gs; + + repaired = repaired.replace( + keyBulletPattern, + (_match, keyPart: string, bulletBody: string, separator: string) => { + // Split the bullet body into individual items on `- ` boundaries. + // Items may contain embedded newlines for multi-line values. + const items = bulletBody + .split(/\n?\s*- /) + .filter((s) => s.trim().length > 0) + .map((s) => s.replace(/,\s*$/, "").trim()); + + // JSON-encode each item as a string, then wrap in an array. + const jsonArray = "[" + items.map((item) => JSON.stringify(item)).join(", ") + "]"; + + // Re-emit the separator (comma) so the next key is properly delimited + const sep = separator.trim() ? separator : (/^\s*"/.test(separator + "x") ? ", " : ""); + return keyPart + jsonArray + sep; + }, + ); + + // Strip trailing commas before } or ] (common in repaired JSON) + repaired = repaired.replace(/,(\s*[}\]])/g, "$1"); + + return repaired; +} diff --git a/packages/pi-ai/src/utils/tests/json-parse.test.ts b/packages/pi-ai/src/utils/tests/json-parse.test.ts new file mode 100644 index 000000000..1ce50751a --- /dev/null +++ b/packages/pi-ai/src/utils/tests/json-parse.test.ts @@ -0,0 +1,17 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { parseStreamingJson } from "../json-parse.js"; + +describe("parseStreamingJson — XML parameter recovery (#3751)", () => { + test("promotes XML parameters trapped inside valid JSON string values", () => { + const malformed = + '{"narrative":"text.\\nall tests pass\\n[\\"npm test\\"]","oneLiner":"done"}'; + + const parsed = parseStreamingJson>(malformed); + + assert.equal(parsed.narrative, "text."); + assert.equal(parsed.verification, "all tests pass"); + assert.deepEqual(parsed.verificationEvidence, ["npm test"]); + assert.equal(parsed.oneLiner, "done"); + }); +}); diff --git a/packages/pi-ai/src/utils/tests/repair-tool-json.test.ts b/packages/pi-ai/src/utils/tests/repair-tool-json.test.ts new file mode 100644 index 000000000..433f6efc0 --- /dev/null +++ b/packages/pi-ai/src/utils/tests/repair-tool-json.test.ts @@ -0,0 +1,208 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { repairToolJson, hasYamlBulletLists, hasXmlParameterTags, hasTruncatedNumbers } from "../repair-tool-json.js"; + +describe("repairToolJson — YAML bullet list repair (#2660)", () => { + // ── Detection ────────────────────────────────────────────────────────── + + test("hasYamlBulletLists detects YAML-style bullets", () => { + assert.equal( + hasYamlBulletLists('"keyDecisions": - Used Web Notification API'), + true, + ); + }); + + test("hasYamlBulletLists ignores negative numbers", () => { + assert.equal( + hasYamlBulletLists('"offset": -1'), + false, + "negative number should not be detected as YAML bullet", + ); + }); + + test("hasYamlBulletLists returns false for valid JSON", () => { + assert.equal( + hasYamlBulletLists('{"keyDecisions": ["item1", "item2"]}'), + false, + ); + }); + + // ── Single bullet item ──────────────────────────────────────────────── + + test("repairs single YAML bullet to JSON array", () => { + const malformed = '{"keyDecisions": - Used Web Notification API}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.deepEqual(parsed.keyDecisions, ["Used Web Notification API"]); + }); + + // ── Multiple bullet items (newline-separated) ───────────────────────── + + test("repairs multiple YAML bullets separated by newlines", () => { + const malformed = + '{"keyDecisions": - Used Web Notification API\n - Chose Tauri over Electron\n - Adopted SQLite for storage, "title": "M005"}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.deepEqual(parsed.keyDecisions, [ + "Used Web Notification API", + "Chose Tauri over Electron", + "Adopted SQLite for storage", + ]); + assert.equal(parsed.title, "M005"); + }); + + // ── Multiple fields with YAML bullets ───────────────────────────────── + + test("repairs multiple fields each with YAML bullet lists", () => { + const malformed = + '{"keyDecisions": - decision one\n - decision two, "keyFiles": - src/lib.rs — Extended menu\n - src/main.ts — Entry point, "title": "done"}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.deepEqual(parsed.keyDecisions, ["decision one", "decision two"]); + assert.deepEqual(parsed.keyFiles, [ + "src/lib.rs \u2014 Extended menu", + "src/main.ts \u2014 Entry point", + ]); + assert.equal(parsed.title, "done"); + }); + + // ── Exact reproduction from issue #2660 ─────────────────────────────── + + test("repairs the exact malformed JSON from issue #2660", () => { + const malformed = `{"milestoneId": "M005", "title": "Native Desktop Polish", "oneLiner": "summary", "narrative": "details", "successCriteriaResults": "all pass", "definitionOfDoneResults": "all done", "requirementOutcomes": "met", "keyDecisions": - Used Web Notification API (new window.Notification()) instead of Tauri sendNotification wrapper, "keyFiles": - src-tauri/src/lib.rs \u2014 Extended menu builder with notification toggle, "lessonsLearned": - Always test notification permissions before sending, "followUps": "none", "deviations": "none", "verificationPassed": true}`; + + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + + assert.equal(parsed.milestoneId, "M005"); + assert.equal(parsed.title, "Native Desktop Polish"); + assert.ok(Array.isArray(parsed.keyDecisions), "keyDecisions should be an array"); + assert.ok(parsed.keyDecisions[0].includes("Web Notification API")); + assert.ok(Array.isArray(parsed.keyFiles), "keyFiles should be an array"); + assert.ok(parsed.keyFiles[0].includes("src-tauri/src/lib.rs")); + assert.ok(Array.isArray(parsed.lessonsLearned), "lessonsLearned should be an array"); + assert.equal(parsed.verificationPassed, true); + }); + + // ── Passthrough for valid JSON ──────────────────────────────────────── + + test("returns valid JSON unchanged", () => { + const valid = '{"keyDecisions": ["item1", "item2"], "count": -5}'; + const result = repairToolJson(valid); + assert.equal(result, valid, "valid JSON should be returned unchanged"); + }); + + // ── Negative numbers are preserved ──────────────────────────────────── + + test("does not mangle negative numbers", () => { + const valid = '{"offset": -1, "limit": -100}'; + const result = repairToolJson(valid); + assert.equal(result, valid); + }); +}); + +// ═══════════════════════════════════════════════════════════════════════════ +// XML parameter tag repair (#3403) +// ═══════════════════════════════════════════════════════════════════════════ + +describe("repairToolJson — XML parameter tag stripping (#3403)", () => { + test("hasXmlParameterTags detects opening tags", () => { + assert.equal( + hasXmlParameterTags('some text'), + true, + ); + }); + + test("hasXmlParameterTags returns false for clean JSON", () => { + assert.equal( + hasXmlParameterTags('{"narrative": "some text"}'), + false, + ); + }); + + test("strips XML parameter tags from JSON values", () => { + const malformed = '{"sliceId": "S03", "narrative": The slice work}'; + const repaired = repairToolJson(malformed); + // After stripping tags, the content should be parseable or at least tag-free + assert.ok(!repaired.includes(""), "should not contain tags"); + }); + + test("handles mixed XML and JSON content", () => { + const malformed = '{"oneLiner": "done", "verification": all tests pass}'; + const repaired = repairToolJson(malformed); + assert.ok(!repaired.includes(" { + const malformed = + '{"narrative":"text.\\nall tests pass\\n[\\"npm test\\"]","oneLiner":"done"}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + + assert.equal(parsed.narrative, "text."); + assert.equal(parsed.verification, "all tests pass"); + assert.deepEqual(parsed.verificationEvidence, ["npm test"]); + assert.equal(parsed.oneLiner, "done"); + assert.ok(!parsed.narrative.includes(" { + test("hasTruncatedNumbers detects bare comma after colon", () => { + assert.equal(hasTruncatedNumbers('"exitCode": ,'), true); + }); + + test("hasTruncatedNumbers detects bare minus before comma", () => { + assert.equal(hasTruncatedNumbers('"exitCode": -,'), true); + }); + + test("hasTruncatedNumbers detects bare minus before closing brace", () => { + assert.equal(hasTruncatedNumbers('"durationMs": -}'), true); + }); + + test("hasTruncatedNumbers returns false for valid numbers", () => { + assert.equal(hasTruncatedNumbers('"exitCode": 0, "durationMs": 1234'), false); + }); + + test("hasTruncatedNumbers returns false for negative numbers", () => { + assert.equal(hasTruncatedNumbers('"exitCode": -1, "offset": -100'), false); + }); + + test("repairs truncated exitCode with bare comma", () => { + const malformed = '{"command": "npm test", "exitCode": , "verdict": "pass", "durationMs": 500}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.equal(parsed.exitCode, 0); + assert.equal(parsed.durationMs, 500); + }); + + test("repairs truncated exitCode with bare minus", () => { + const malformed = '{"command": "npm test", "exitCode": -, "verdict": "pass", "durationMs": 1234}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.equal(parsed.exitCode, 0); + assert.equal(parsed.verdict, "pass"); + }); + + test("repairs truncated durationMs at end of object", () => { + const malformed = '{"command": "npm test", "exitCode": 0, "verdict": "pass", "durationMs": -}'; + const repaired = repairToolJson(malformed); + const parsed = JSON.parse(repaired); + assert.equal(parsed.durationMs, 0); + assert.equal(parsed.exitCode, 0); + }); + + test("does not mangle valid negative numbers", () => { + const valid = '{"exitCode": -1, "offset": -100}'; + const repaired = repairToolJson(valid); + const parsed = JSON.parse(repaired); + assert.equal(parsed.exitCode, -1); + assert.equal(parsed.offset, -100); + }); +}); diff --git a/packages/pi-coding-agent/package.json b/packages/pi-coding-agent/package.json index 70eb8c1ed..20ebb6757 100644 --- a/packages/pi-coding-agent/package.json +++ b/packages/pi-coding-agent/package.json @@ -1,6 +1,6 @@ { "name": "@gsd/pi-coding-agent", - "version": "2.58.0", + "version": "2.71.0", "description": "Coding agent CLI (vendored from pi-mono)", "type": "module", "piConfig": { diff --git a/packages/pi-coding-agent/src/core/agent-session-model-switch.test.ts b/packages/pi-coding-agent/src/core/agent-session-model-switch.test.ts new file mode 100644 index 000000000..f86dac6ca --- /dev/null +++ b/packages/pi-coding-agent/src/core/agent-session-model-switch.test.ts @@ -0,0 +1,21 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const source = readFileSync(join(process.cwd(), "packages/pi-coding-agent/src/core/agent-session.ts"), "utf-8"); + +test("agent-session: explicit model switches cancel retry before applying new model", () => { + const start = source.indexOf("private async _applyModelChange("); + assert.ok(start >= 0, "missing _applyModelChange"); + const window = source.slice(start, start + 900); + const abortIdx = window.indexOf("this._retryHandler.abortRetry();"); + const setModelIdx = window.indexOf("this.agent.setModel(model);"); + + assert.ok(abortIdx >= 0, "_applyModelChange should cancel any in-flight retry"); + assert.ok(setModelIdx >= 0, "_applyModelChange should set the new model"); + assert.ok( + abortIdx < setModelIdx, + "retry cancellation must happen before applying the new model to prevent stale provider retries", + ); +}); diff --git a/packages/pi-coding-agent/src/core/agent-session-tool-refresh.test.ts b/packages/pi-coding-agent/src/core/agent-session-tool-refresh.test.ts new file mode 100644 index 000000000..f1a14a15b --- /dev/null +++ b/packages/pi-coding-agent/src/core/agent-session-tool-refresh.test.ts @@ -0,0 +1,64 @@ +// GSD-2 — Regression tests for #3616: tool list persistence across newSession() calls +// Copyright (c) 2026 Jeremy McSpadden + +import test, { describe } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const source = readFileSync( + join(process.cwd(), "packages/pi-coding-agent/src/core/agent-session.ts"), + "utf-8", +); + +describe("#3616 — newSession() must restore full tool set", () => { + test("newSession() calls _refreshToolRegistry with includeAllExtensionTools when cwd is unchanged", () => { + // Find the newSession method + const newSessionStart = source.indexOf("async newSession(options?:"); + assert.ok(newSessionStart >= 0, "should find newSession method"); + + // Get the method body (up to the next top-level method) + const methodBody = source.slice(newSessionStart, newSessionStart + 3000); + + // Verify the cwd-changed branch rebuilds tools + assert.ok( + methodBody.includes("if (this._cwd !== previousCwd)"), + "should have cwd-change guard", + ); + + // Verify the else branch exists and refreshes tools with includeAllExtensionTools + const elseIdx = methodBody.indexOf("} else {"); + assert.ok(elseIdx >= 0, "should have else branch for cwd-unchanged case"); + + const elseBranch = methodBody.slice(elseIdx, elseIdx + 800); + assert.ok( + elseBranch.includes("_refreshToolRegistry"), + "else branch should call _refreshToolRegistry", + ); + assert.ok( + elseBranch.includes("includeAllExtensionTools: true"), + "else branch should pass includeAllExtensionTools: true to restore narrowed tools", + ); + }); + + test("newSession() references #3616 in the else-branch comment", () => { + const idx = source.indexOf("#3616"); + assert.ok(idx >= 0, "source should reference issue #3616 for the tool restore fix"); + }); + + test("agent.reset() does not clear _state.tools (tools persist across reset)", () => { + // This is a structural invariant — if reset() starts clearing tools, + // the newSession() refresh becomes the only defense against tool loss. + const agentSource = readFileSync( + join(process.cwd(), "packages/pi-agent-core/src/agent.ts"), + "utf-8", + ); + const resetStart = agentSource.indexOf("reset()"); + assert.ok(resetStart >= 0, "should find reset() method"); + const resetBody = agentSource.slice(resetStart, resetStart + 400); + assert.ok( + !resetBody.includes("tools"), + "reset() should NOT touch _state.tools — tools are managed by agent-session", + ); + }); +}); diff --git a/packages/pi-coding-agent/src/core/agent-session.ts b/packages/pi-coding-agent/src/core/agent-session.ts index fb84b9209..782ecd04e 100644 --- a/packages/pi-coding-agent/src/core/agent-session.ts +++ b/packages/pi-coding-agent/src/core/agent-session.ts @@ -72,6 +72,7 @@ import type { ModelRegistry } from "./model-registry.js"; import { expandPromptTemplate, type PromptTemplate } from "./prompt-templates.js"; import type { ResourceExtensionPaths, ResourceLoader } from "./resource-loader.js"; import { RetryHandler } from "./retry-handler.js"; +import { isImageDimensionError, downsizeConversationImages } from "./image-overflow-recovery.js"; import type { BranchSummaryEntry, SessionManager } from "./session-manager.js"; import { getLatestCompactionEntry } from "./session-manager.js"; import type { SettingsManager } from "./settings-manager.js"; @@ -136,7 +137,8 @@ export type AgentSessionEvent = | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string } | { type: "fallback_provider_switch"; from: string; to: string; reason: string } | { type: "fallback_provider_restored"; provider: string; reason: string } - | { type: "fallback_chain_exhausted"; reason: string }; + | { type: "fallback_chain_exhausted"; reason: string } + | { type: "image_overflow_recovery"; strippedCount: number; imageCount: number }; /** Listener function for agent session events */ export type AgentSessionEventListener = (event: AgentSessionEvent) => void; @@ -164,6 +166,9 @@ export interface AgentSessionConfig { baseToolsOverride?: Record; /** Mutable ref used by Agent to access the current ExtensionRunner */ extensionRunnerRef?: { current?: ExtensionRunner }; + /** Optional: check if the claude-code CLI provider is ready (installed + authed). + * Passed through to RetryHandler for third-party block recovery (#3772). */ + isClaudeCodeReady?: () => boolean; } export interface ExtensionBindings { @@ -322,6 +327,7 @@ export class AgentSession { getSessionId: () => this.sessionId, emit: (event) => this._emit(event), onModelChange: (model) => this.sessionManager.appendModelChange(model.provider, model.id), + isClaudeCodeReady: config.isClaudeCodeReady, }); this._compactionOrchestrator = new CompactionOrchestrator({ @@ -487,6 +493,36 @@ export class AgentSession { if (didRetry) return; // Retry was initiated, don't proceed to compaction } + // Check for image dimension overflow (many-image 400 error). + // When a session accumulates many images, the API rejects requests + // whose images exceed the many-image dimension limit. Strip older + // images from the conversation and auto-retry. (#2874) + if ( + msg.stopReason === "error" && + isImageDimensionError(msg.errorMessage) + ) { + const messages = this.agent.state.messages; + const result = downsizeConversationImages(messages as Message[]); + if (result.processed) { + // Remove the trailing error assistant message, then replace + if (messages.length > 0 && messages[messages.length - 1].role === "assistant") { + this.agent.replaceMessages(messages.slice(0, -1)); + } + + this._emit({ + type: "image_overflow_recovery", + strippedCount: result.strippedCount, + imageCount: result.imageCount, + }); + + // Auto-retry after downsizing + setTimeout(() => { + this.agent.continue().catch(() => {}); + }, 0); + return; + } + } + await this._compactionOrchestrator.checkCompaction(msg); } } @@ -1545,6 +1581,16 @@ export class AgentSession { activeToolNames: this.getActiveToolNames(), includeAllExtensionTools: true, }); + } else { + // Even when cwd hasn't changed, restore the full tool set (#3616). + // Extensions (e.g., discuss flows) may narrow the active tool list + // via setActiveTools() during a session. Without this refresh, the + // narrowed set persists into the next session — causing tools like + // gsd_plan_slice to be missing from auto-mode subagent sessions. + this._refreshToolRegistry({ + activeToolNames: this.getActiveToolNames(), + includeAllExtensionTools: true, + }); } // Run setup callback if provided (e.g., to append initial messages) @@ -1601,6 +1647,10 @@ export class AgentSession { options?: { persist?: boolean }, ): Promise { const previousModel = this.model; + // Explicit model switches must cancel any in-flight retry loop from the + // previous provider/model. Otherwise stale provider backoff errors can + // continue to land after the user or runtime has already switched models. + this._retryHandler.abortRetry(); this.agent.setModel(model); this.sessionManager.appendModelChange(model.provider, model.id); if (options?.persist !== false) { @@ -1986,6 +2036,11 @@ export class AgentSession { const messages = this.agent.state.messages; const last = messages[messages.length - 1]; if (last?.role === "assistant" && (last as AssistantMessage).stopReason === "error") { + // If the error was an image dimension overflow, downsize images + // before retrying so the retry doesn't hit the same error (#2874) + if (isImageDimensionError((last as AssistantMessage).errorMessage)) { + downsizeConversationImages(messages as Message[]); + } this.agent.replaceMessages(messages.slice(0, -1)); this.agent.continue().catch((err) => { runner.emitError({ diff --git a/packages/pi-coding-agent/src/core/auth-storage.test.ts b/packages/pi-coding-agent/src/core/auth-storage.test.ts index 7961edb73..a0d2cab20 100644 --- a/packages/pi-coding-agent/src/core/auth-storage.test.ts +++ b/packages/pi-coding-agent/src/core/auth-storage.test.ts @@ -356,6 +356,59 @@ describe("AuthStorage — oauth credential for non-OAuth provider (#2083)", () = }); }); +// ─── Gemini CLI OAuth token detection ───────────────────────────────────────── + +describe("AuthStorage — Gemini CLI OAuth token detection", () => { + it("rejects Google OAuth access token (ya29. prefix) stored as api_key for google provider", () => { + const storage = inMemory({}); + assert.throws( + () => storage.set("google", makeKey("ya29.a0ARrdaM_fake_oauth_token_from_gemini_cli")), + (err: Error) => { + assert.ok(err.message.includes("OAuth access token"), `Expected message about OAuth token, got: ${err.message}`); + assert.ok( + err.message.includes("GEMINI_API_KEY") || err.message.includes("google-gemini-cli"), + `Expected guidance about GEMINI_API_KEY or google-gemini-cli, got: ${err.message}`, + ); + return true; + }, + ); + }); + + it("rejects Google OAuth access token for google provider via getApiKey when set as env var", async () => { + const storage = inMemory({}); + // Simulate runtime override with OAuth token + storage.setRuntimeApiKey("google", "ya29.c.b0AXv0zTPQ_fake_oauth_token"); + const key = await storage.getApiKey("google"); + // Should return undefined (blocked) or throw + assert.equal(key, undefined, "OAuth token should be blocked for google provider"); + }); + + it("allows legitimate Google API keys (AIza prefix) for google provider", () => { + const storage = inMemory({}); + storage.set("google", makeKey("AIzaSyD_fake_legitimate_api_key_here")); + const creds = storage.getCredentialsForProvider("google"); + assert.equal(creds.length, 1); + }); + + it("allows ya29 tokens for google-gemini-cli provider (OAuth is expected there)", () => { + // google-gemini-cli stores OAuth credentials with type: "oauth", not "api_key" + // But if someone somehow stored an api_key, it shouldn't be blocked for OAuth providers + const storage = inMemory({}); + storage.set("google-gemini-cli", makeKey("ya29.a0ARrdaM_token_for_gemini_cli")); + const creds = storage.getCredentialsForProvider("google-gemini-cli"); + assert.equal(creds.length, 1); + }); + + it("rejects Google OAuth token (ya29. prefix) for openai provider that uses GEMINI_API_KEY indirectly", () => { + // Only google provider should be blocked, not others + const storage = inMemory({}); + // This should NOT throw - other providers can have whatever keys they want + storage.set("openai", makeKey("ya29.some_value")); + const creds = storage.getCredentialsForProvider("openai"); + assert.equal(creds.length, 1); + }); +}); + // ─── getAll truncation ──────────────────────────────────────────────────────── describe("AuthStorage — getAll()", () => { diff --git a/packages/pi-coding-agent/src/core/auth-storage.ts b/packages/pi-coding-agent/src/core/auth-storage.ts index 2791f326d..fb1532252 100644 --- a/packages/pi-coding-agent/src/core/auth-storage.ts +++ b/packages/pi-coding-agent/src/core/auth-storage.ts @@ -34,6 +34,46 @@ export type OAuthCredential = { export type AuthCredential = ApiKeyCredential | OAuthCredential; +// ============================================================================ +// Google OAuth token detection +// ============================================================================ + +/** + * Providers that use Google AI Studio API keys (not OAuth tokens). + * OAuth access tokens (ya29.*) are not valid API keys for these providers. + */ +const GOOGLE_API_KEY_PROVIDERS = new Set(["google"]); + +/** + * Detect if a string is a Google OAuth access token rather than an API key. + * Google OAuth access tokens start with "ya29." — these are issued by + * Google's OAuth2 token endpoint and are not valid as AI Studio API keys. + * + * Users who installed Google's Gemini CLI may have these tokens and + * mistakenly set them as GEMINI_API_KEY. + */ +export function isGoogleOAuthToken(key: string): boolean { + return key.startsWith("ya29."); +} + +/** + * Validate that an API key is not a Google OAuth token being used for + * a provider that requires actual API keys (e.g., Google AI Studio). + * Throws a descriptive error if the key appears to be an OAuth token. + */ +function validateNotGoogleOAuthToken(provider: string, key: string): void { + if (GOOGLE_API_KEY_PROVIDERS.has(provider) && isGoogleOAuthToken(key)) { + throw new Error( + `The provided key for "${provider}" appears to be a Google OAuth access token (ya29.*), ` + + `not a valid API key. Google AI Studio requires an API key starting with "AIza...". ` + + `\n\nIf you're using Google's Gemini CLI, its OAuth tokens are not compatible. ` + + `Either:\n` + + ` 1. Get an API key from https://aistudio.google.com/apikey and set GEMINI_API_KEY\n` + + ` 2. Use '/login google-gemini-cli' to authenticate via Cloud Code Assist`, + ); + } +} + /** * On-disk format: each provider maps to a single credential or an array of credentials. * Single credentials are normalized to arrays at load time for internal use. @@ -360,6 +400,9 @@ export class AuthStorage { */ set(provider: string, credential: AuthCredential): void { if (credential.type === "api_key") { + // Block Google OAuth tokens being stored as API keys for AI Studio providers + validateNotGoogleOAuthToken(provider, credential.key); + const existing = this.getCredentialsForProvider(provider); // Deduplicate: don't add if same key already exists const isDuplicate = existing.some( @@ -762,6 +805,16 @@ export class AuthStorage { // Runtime override takes highest priority const runtimeKey = this.runtimeOverrides.get(providerId); if (runtimeKey) { + // Block Google OAuth tokens used as runtime API key overrides + if (GOOGLE_API_KEY_PROVIDERS.has(providerId) && isGoogleOAuthToken(runtimeKey)) { + this.recordError( + new Error( + `Blocked Google OAuth access token (ya29.*) for provider "${providerId}". ` + + `Use an API key from https://aistudio.google.com/apikey or '/login google-gemini-cli'.`, + ), + ); + return undefined; + } return runtimeKey; } @@ -780,7 +833,19 @@ export class AuthStorage { // Fall back to environment variable const envKey = getEnvApiKey(providerId); - if (envKey) return envKey; + if (envKey) { + // Block Google OAuth tokens from environment variables (e.g., GEMINI_API_KEY=ya29.*) + if (GOOGLE_API_KEY_PROVIDERS.has(providerId) && isGoogleOAuthToken(envKey)) { + this.recordError( + new Error( + `GEMINI_API_KEY contains a Google OAuth access token (ya29.*), not an API key. ` + + `Get an API key from https://aistudio.google.com/apikey or use '/login google-gemini-cli'.`, + ), + ); + return undefined; + } + return envKey; + } // Fall back to custom resolver (e.g., models.json custom providers) return this.fallbackResolver?.(providerId) ?? undefined; diff --git a/packages/pi-coding-agent/src/core/chat-controller-ordering.test.ts b/packages/pi-coding-agent/src/core/chat-controller-ordering.test.ts new file mode 100644 index 000000000..eb7795508 --- /dev/null +++ b/packages/pi-coding-agent/src/core/chat-controller-ordering.test.ts @@ -0,0 +1,468 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { handleAgentEvent } from "../modes/interactive/controllers/chat-controller.js"; + +function makeUsage() { + return { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 0, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }; +} + +function makeAssistant(content: any[]) { + return { + role: "assistant", + content, + api: "anthropic-messages", + provider: "claude-code", + model: "claude-sonnet-4", + usage: makeUsage(), + stopReason: "stop", + timestamp: Date.now(), + }; +} + +function createHost() { + const chatContainer = { + children: [] as any[], + addChild(component: any) { + this.children.push(component); + }, + removeChild(component: any) { + const idx = this.children.indexOf(component); + if (idx !== -1) this.children.splice(idx, 1); + }, + clear() { + this.children = []; + }, + }; + + const pinnedMessageContainer = { + children: [] as any[], + addChild(component: any) { + this.children.push(component); + }, + removeChild(component: any) { + const idx = this.children.indexOf(component); + if (idx !== -1) this.children.splice(idx, 1); + }, + clear() { + this.children = []; + }, + }; + + const host: any = { + isInitialized: true, + init: async () => {}, + defaultEditor: { onEscape: undefined }, + editor: {}, + session: { retryAttempt: 0, abortCompaction: () => {}, abortRetry: () => {} }, + ui: { requestRender: () => {}, terminal: { rows: 50 } }, + footer: { invalidate: () => {} }, + keybindings: {}, + statusContainer: { clear: () => {}, addChild: () => {} }, + chatContainer, + settingsManager: { getTimestampFormat: () => "date-time-iso", getShowImages: () => false }, + pendingTools: new Map(), + toolOutputExpanded: false, + hideThinkingBlock: false, + isBashMode: false, + defaultWorkingMessage: "Working...", + compactionQueuedMessages: [], + editorContainer: {}, + pendingMessagesContainer: { clear: () => {} }, + pinnedMessageContainer, + addMessageToChat: () => {}, + getMarkdownThemeWithSettings: () => ({}), + formatWebSearchResult: () => "", + getRegisteredToolDefinition: () => undefined, + checkShutdownRequested: async () => {}, + rebuildChatFromMessages: () => {}, + flushCompactionQueue: async () => {}, + showStatus: () => {}, + showError: () => {}, + updatePendingMessagesDisplay: () => {}, + updateTerminalTitle: () => {}, + updateEditorBorderColor: () => {}, + }; + + return host; +} + +test("chat-controller keeps tool output ahead of delayed assistant text for external tool streams", async () => { + // ToolExecutionComponent uses the global theme singleton. + // Install a minimal no-op theme implementation for this unit test. + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolId = "mcp-tool-1"; + const toolCall = { + type: "toolCall", + id: toolId, + name: "exec_command", + arguments: { cmd: "echo hi" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + assert.equal(host.streamingComponent, undefined, "assistant component should be deferred at message_start"); + assert.equal(host.chatContainer.children.length, 0, "nothing should render before content arrives"); + + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([toolCall]), + assistantMessageEvent: { + type: "toolcall_end", + contentIndex: 0, + toolCall: { + ...toolCall, + externalResult: { + content: [{ type: "text", text: "tool output" }], + details: {}, + isError: false, + }, + }, + partial: makeAssistant([toolCall]), + }, + } as any, + ); + + assert.equal(host.streamingComponent, undefined, "assistant text container should remain deferred for tool-only updates"); + assert.equal(host.chatContainer.children.length, 1, "tool execution block should render immediately"); + assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent"); + + // Re-assert required host method before the text-bearing update path. + host.getMarkdownThemeWithSettings = () => ({}); + + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([toolCall, { type: "text", text: "done" }]), + assistantMessageEvent: { + type: "text_delta", + contentIndex: 1, + delta: "done", + partial: makeAssistant([toolCall, { type: "text", text: "done" }]), + }, + } as any, + ); + + assert.equal(host.chatContainer.children.length, 2, "assistant content should render after existing tool output"); + assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent"); + assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent"); +}); + +test("chat-controller keeps serverToolUse output ahead of assistant text when external results arrive", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolId = "mcp-secure-1"; + const serverToolUse = { + type: "serverToolUse", + id: toolId, + name: "mcp__gsd-workflow__secure_env_collect", + input: { projectDir: "/tmp/project", keys: [{ key: "SECURE_PASSWORD" }], destination: "dotenv" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([serverToolUse]), + assistantMessageEvent: { + type: "server_tool_use", + contentIndex: 0, + partial: makeAssistant([serverToolUse]), + }, + } as any, + ); + + assert.equal(host.streamingComponent, undefined, "assistant content should stay deferred while only tool content streams"); + assert.equal(host.chatContainer.children.length, 1, "server tool block should render immediately"); + assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent"); + + host.getMarkdownThemeWithSettings = () => ({}); + const resultMessage = makeAssistant([ + { + ...serverToolUse, + externalResult: { + content: [{ type: "text", text: "secure_env_collect was cancelled by user." }], + details: {}, + isError: true, + }, + }, + { type: "text", text: "The secure password collection was cancelled." }, + ]); + + await handleAgentEvent( + host, + { + type: "message_update", + message: resultMessage, + assistantMessageEvent: { + type: "server_tool_use", + contentIndex: 0, + partial: resultMessage, + }, + } as any, + ); + + assert.equal(host.chatContainer.children.length, 2, "assistant text should render after existing server tool output"); + assert.equal(host.chatContainer.children[0]?.constructor?.name, "ToolExecutionComponent"); + assert.equal(host.chatContainer.children[1]?.constructor?.name, "AssistantMessageComponent"); +}); + +test("chat-controller pins latest assistant text above editor when tool calls are present", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolId = "tool-pin-1"; + const toolCall = { + type: "toolCall", + id: toolId, + name: "exec_command", + arguments: { cmd: "echo hi" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + assert.equal(host.pinnedMessageContainer.children.length, 0, "pinned zone should be empty at message_start"); + + // Send a message with text followed by a tool call + host.getMarkdownThemeWithSettings = () => ({}); + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([ + { type: "text", text: "Looking at the files now." }, + toolCall, + ]), + assistantMessageEvent: { + type: "toolcall_end", + contentIndex: 1, + toolCall: { + ...toolCall, + externalResult: { + content: [{ type: "text", text: "file contents" }], + details: {}, + isError: false, + }, + }, + partial: makeAssistant([{ type: "text", text: "Looking at the files now." }, toolCall]), + }, + } as any, + ); + + // Pinned zone should now have a DynamicBorder and a Markdown component + assert.equal(host.pinnedMessageContainer.children.length, 2, "pinned zone should have border + markdown"); + assert.equal(host.pinnedMessageContainer.children[0]?.constructor?.name, "DynamicBorder"); + assert.equal(host.pinnedMessageContainer.children[1]?.constructor?.name, "Markdown"); +}); + +test("chat-controller clears pinned zone when a new assistant message starts", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolCall = { + type: "toolCall", + id: "tool-clear-1", + name: "exec_command", + arguments: { cmd: "echo hi" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + // Populate the pinned zone + host.getMarkdownThemeWithSettings = () => ({}); + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([{ type: "text", text: "Working on it." }, toolCall]), + assistantMessageEvent: { + type: "toolcall_end", + contentIndex: 1, + toolCall: { + ...toolCall, + externalResult: { + content: [{ type: "text", text: "ok" }], + details: {}, + isError: false, + }, + }, + partial: makeAssistant([{ type: "text", text: "Working on it." }, toolCall]), + }, + } as any, + ); + + assert.ok(host.pinnedMessageContainer.children.length > 0, "pinned zone should be populated"); + + // Start a new assistant message — pinned zone should clear + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + assert.equal(host.pinnedMessageContainer.children.length, 0, "pinned zone should clear on new assistant message"); +}); + +test("chat-controller clears pinned zone when the agent turn ends", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolCall = { + type: "toolCall", + id: "tool-clear-on-end-1", + name: "exec_command", + arguments: { cmd: "echo hi" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + host.getMarkdownThemeWithSettings = () => ({}); + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([{ type: "text", text: "Working on it." }, toolCall]), + assistantMessageEvent: { + type: "toolcall_end", + contentIndex: 1, + toolCall: { + ...toolCall, + externalResult: { + content: [{ type: "text", text: "ok" }], + details: {}, + isError: false, + }, + }, + partial: makeAssistant([{ type: "text", text: "Working on it." }, toolCall]), + }, + } as any, + ); + + assert.ok(host.pinnedMessageContainer.children.length > 0, "pinned zone should be populated before agent_end"); + + await handleAgentEvent(host, { type: "agent_end" } as any); + + assert.equal(host.pinnedMessageContainer.children.length, 0, "pinned zone should clear on agent_end"); +}); + +test("chat-controller clears pinned zone when assistant message ends", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + const toolCall = { + type: "toolCall", + id: "tool-msg-end-1", + name: "exec_command", + arguments: { cmd: "echo hi" }, + }; + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + host.getMarkdownThemeWithSettings = () => ({}); + const msgContent = [{ type: "text", text: "Summary after tools." }, toolCall]; + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant(msgContent), + assistantMessageEvent: { + type: "toolcall_end", + contentIndex: 1, + toolCall: { + ...toolCall, + externalResult: { + content: [{ type: "text", text: "ok" }], + details: {}, + isError: false, + }, + }, + partial: makeAssistant(msgContent), + }, + } as any, + ); + + assert.ok(host.pinnedMessageContainer.children.length > 0, "pinned zone should be populated during streaming"); + + // End the assistant message (e.g. before form elicitation) — pinned zone should clear + await handleAgentEvent(host, { type: "message_end", message: makeAssistant(msgContent) } as any); + + assert.equal(host.pinnedMessageContainer.children.length, 0, "pinned zone should clear on message_end to prevent duplicate display"); +}); + +test("chat-controller does not pin when there are no tool calls", async () => { + (globalThis as any)[Symbol.for("@gsd/pi-coding-agent:theme")] = { + fg: (_key: string, text: string) => text, + bg: (_key: string, text: string) => text, + bold: (text: string) => text, + italic: (text: string) => text, + truncate: (text: string) => text, + }; + + const host = createHost(); + + await handleAgentEvent(host, { type: "message_start", message: makeAssistant([]) } as any); + + host.getMarkdownThemeWithSettings = () => ({}); + await handleAgentEvent( + host, + { + type: "message_update", + message: makeAssistant([{ type: "text", text: "Just some text, no tools." }]), + assistantMessageEvent: { + type: "text_delta", + contentIndex: 0, + delta: "Just some text, no tools.", + partial: makeAssistant([{ type: "text", text: "Just some text, no tools." }]), + }, + } as any, + ); + + assert.equal(host.pinnedMessageContainer.children.length, 0, "pinned zone should stay empty without tool calls"); +}); diff --git a/packages/pi-coding-agent/src/core/compaction/compaction.test.ts b/packages/pi-coding-agent/src/core/compaction/compaction.test.ts new file mode 100644 index 000000000..1fb5a2db2 --- /dev/null +++ b/packages/pi-coding-agent/src/core/compaction/compaction.test.ts @@ -0,0 +1,236 @@ +/** + * Tests for chunked compaction fallback when messages exceed model context window. + * Regression test for #2932. + */ + +import assert from "node:assert/strict"; +import { describe, it, mock } from "node:test"; + +import type { AgentMessage } from "@gsd/pi-agent-core"; +import type { Model, AssistantMessage } from "@gsd/pi-ai"; + +import { generateSummary, estimateTokens, chunkMessages } from "./compaction.js"; + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +/** Create a user message with approximately `tokenCount` tokens (chars = tokens * 4). */ +function makeUserMessage(tokenCount: number): AgentMessage { + const text = "x".repeat(tokenCount * 4); + return { role: "user", content: text } as unknown as AgentMessage; +} + +/** Create a mock model with a given context window. */ +function makeModel(contextWindow: number): Model { + return { + id: "test-model", + name: "Test Model", + api: "anthropic-messages", + provider: "anthropic", + baseUrl: "https://api.test", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow, + maxTokens: 4096, + } as Model; +} + +function makeFakeResponse(text: string): AssistantMessage { + return { + content: [{ type: "text", text }], + stopReason: "end_turn", + } as unknown as AssistantMessage; +} + +// --------------------------------------------------------------------------- +// chunkMessages tests +// --------------------------------------------------------------------------- + +describe("chunkMessages", () => { + it("returns a single chunk when messages fit in budget", () => { + const messages: AgentMessage[] = [ + makeUserMessage(1_000), + makeUserMessage(1_000), + ]; + const chunks = chunkMessages(messages, 100_000); + assert.equal(chunks.length, 1); + assert.equal(chunks[0].length, 2); + }); + + it("splits messages into multiple chunks when they exceed budget", () => { + const messages: AgentMessage[] = [ + makeUserMessage(50_000), + makeUserMessage(50_000), + makeUserMessage(50_000), + ]; + // Budget of 80k tokens means each 50k message gets its own chunk + // (or two fit together if budget allows) + const chunks = chunkMessages(messages, 80_000); + assert.ok(chunks.length > 1, `Expected multiple chunks, got ${chunks.length}`); + // All messages should be present across chunks + const totalMessages = chunks.reduce((sum, c) => sum + c.length, 0); + assert.equal(totalMessages, 3); + }); + + it("puts a single oversized message in its own chunk", () => { + const messages: AgentMessage[] = [ + makeUserMessage(200_000), // Way over any reasonable budget + ]; + const chunks = chunkMessages(messages, 80_000); + assert.equal(chunks.length, 1); + assert.equal(chunks[0].length, 1); + }); + + it("preserves message order across chunks", () => { + // Create messages with identifiable sizes + const messages: AgentMessage[] = [ + makeUserMessage(30_000), // ~30k tokens + makeUserMessage(30_000), + makeUserMessage(30_000), + makeUserMessage(30_000), + ]; + const chunks = chunkMessages(messages, 50_000); + // Reconstruct original order + const flat = chunks.flat(); + assert.equal(flat.length, 4); + for (let i = 0; i < flat.length; i++) { + assert.strictEqual(flat[i], messages[i], `Message ${i} should be in order`); + } + }); +}); + +// --------------------------------------------------------------------------- +// generateSummary chunked fallback tests +// --------------------------------------------------------------------------- + +describe("generateSummary — chunked fallback (#2932)", () => { + it("calls _completeFn multiple times when messages exceed model context window", async () => { + // Arrange: 3 messages of ~80k tokens each = ~240k total, model has 200k window + const messages: AgentMessage[] = [ + makeUserMessage(80_000), + makeUserMessage(80_000), + makeUserMessage(80_000), + ]; + const model = makeModel(200_000); + const reserveTokens = 16_384; + + // Verify our test setup: messages really do exceed the model window + let totalTokens = 0; + for (const m of messages) totalTokens += estimateTokens(m); + assert.ok( + totalTokens > model.contextWindow, + `Test setup: ${totalTokens} tokens should exceed ${model.contextWindow} context window`, + ); + + // Track calls + const calls: string[] = []; + const mockComplete = mock.fn(async (_model: any, context: any, _options: any) => { + const userMsg = context.messages?.[0]; + const text = + typeof userMsg?.content === "string" + ? userMsg.content + : userMsg?.content?.[0]?.text ?? ""; + + if (text.includes("")) { + calls.push("update"); + } else { + calls.push("initial"); + } + return makeFakeResponse("Summary of chunk"); + }); + + const summary = await generateSummary( + messages, + model, + reserveTokens, + undefined, // apiKey + undefined, // signal + undefined, // customInstructions + undefined, // previousSummary + mockComplete, // _completeFn override for testing + ); + + // Assert: should have called completeSimple more than once (chunked) + assert.ok( + mockComplete.mock.callCount() > 1, + `Expected multiple calls for chunked summarization, got ${mockComplete.mock.callCount()}`, + ); + + // First call should be an initial summary, subsequent should be updates + assert.equal(calls[0], "initial", "First chunk should use initial summarization prompt"); + for (let i = 1; i < calls.length; i++) { + assert.equal(calls[i], "update", `Chunk ${i + 1} should use update summarization prompt`); + } + + // Should return a non-empty summary + assert.ok(summary.length > 0, "Summary should not be empty"); + }); + + it("uses single-pass when messages fit within model context window", async () => { + const messages: AgentMessage[] = [ + makeUserMessage(10_000), + makeUserMessage(10_000), + ]; + const model = makeModel(200_000); + const reserveTokens = 16_384; + + // Verify test setup + let totalTokens = 0; + for (const m of messages) totalTokens += estimateTokens(m); + assert.ok( + totalTokens < model.contextWindow, + `Test setup: ${totalTokens} tokens should fit in ${model.contextWindow} context window`, + ); + + const mockComplete = mock.fn(async () => makeFakeResponse("Single pass summary")); + + await generateSummary(messages, model, reserveTokens, undefined, undefined, undefined, undefined, mockComplete); + + assert.equal( + mockComplete.mock.callCount(), + 1, + "Should use single-pass summarization when messages fit in context window", + ); + }); + + it("passes previousSummary through chunked summarization", async () => { + const messages: AgentMessage[] = [ + makeUserMessage(80_000), + makeUserMessage(80_000), + makeUserMessage(80_000), + ]; + const model = makeModel(200_000); + const reserveTokens = 16_384; + const previousSummary = "Previous session summary content"; + + const prompts: string[] = []; + const mockComplete = mock.fn(async (_model: any, context: any) => { + const userMsg = context.messages?.[0]; + const text = + typeof userMsg?.content === "string" + ? userMsg.content + : userMsg?.content?.[0]?.text ?? ""; + prompts.push(text); + return makeFakeResponse("Chunk summary"); + }); + + await generateSummary( + messages, + model, + reserveTokens, + undefined, + undefined, + undefined, + previousSummary, + mockComplete, + ); + + // First chunk should include the previousSummary + assert.ok( + prompts[0].includes(previousSummary), + "First chunk should incorporate the previousSummary", + ); + }); +}); diff --git a/packages/pi-coding-agent/src/core/compaction/compaction.ts b/packages/pi-coding-agent/src/core/compaction/compaction.ts index 66cdbcfb3..cd3183277 100644 --- a/packages/pi-coding-agent/src/core/compaction/compaction.ts +++ b/packages/pi-coding-agent/src/core/compaction/compaction.ts @@ -489,9 +489,49 @@ Use this EXACT format: Keep each section concise. Preserve exact file paths, function names, and error messages.`; +/** + * Split messages into chunks where each chunk's estimated token count + * stays within `maxTokensPerChunk`. A single message that exceeds the + * budget is placed alone in its own chunk (never dropped). + */ +export function chunkMessages(messages: AgentMessage[], maxTokensPerChunk: number): AgentMessage[][] { + const chunks: AgentMessage[][] = []; + let currentChunk: AgentMessage[] = []; + let currentTokens = 0; + + for (const msg of messages) { + const msgTokens = estimateTokens(msg); + + if (currentChunk.length > 0 && currentTokens + msgTokens > maxTokensPerChunk) { + // Current chunk is full — start a new one + chunks.push(currentChunk); + currentChunk = [msg]; + currentTokens = msgTokens; + } else { + currentChunk.push(msg); + currentTokens += msgTokens; + } + } + + if (currentChunk.length > 0) { + chunks.push(currentChunk); + } + + return chunks; +} + +/** Type for the completion function, allowing injection for tests. */ +type CompleteFn = typeof completeSimple; + /** * Generate a summary of the conversation using the LLM. * If previousSummary is provided, uses the update prompt to merge. + * + * When the messages exceed the model's context window, automatically + * falls back to chunked summarization: summarize the first chunk, + * then iteratively merge subsequent chunks using the update prompt. + * + * @param _completeFn - Internal override for testing; defaults to completeSimple. */ export async function generateSummary( currentMessages: AgentMessage[], @@ -501,6 +541,59 @@ export async function generateSummary( signal?: AbortSignal, customInstructions?: string, previousSummary?: string, + _completeFn?: CompleteFn, +): Promise { + const complete = _completeFn ?? completeSimple; + + // Estimate total tokens for the messages to summarize + let totalTokens = 0; + for (const msg of currentMessages) { + totalTokens += estimateTokens(msg); + } + + // Overhead for the prompt framing, system prompt, and response budget + const promptOverhead = 4_000; + const maxTokens = Math.floor(0.8 * reserveTokens); + const maxInputTokens = (model.contextWindow || 200_000) - reserveTokens - promptOverhead; + + // If messages fit in the context window, use single-pass summarization + if (totalTokens <= maxInputTokens) { + return singlePassSummary(currentMessages, model, reserveTokens, apiKey, signal, customInstructions, previousSummary, complete); + } + + // Chunked fallback: split messages and iteratively summarize + const chunks = chunkMessages(currentMessages, maxInputTokens); + let runningSummary = previousSummary; + + for (let i = 0; i < chunks.length; i++) { + runningSummary = await singlePassSummary( + chunks[i], + model, + reserveTokens, + apiKey, + signal, + customInstructions, + runningSummary, + complete, + ); + } + + return runningSummary!; +} + +/** + * Single-pass summarization of messages using the LLM. + * If previousSummary is provided, uses the update prompt to merge. + */ +async function singlePassSummary( + currentMessages: AgentMessage[], + model: Model, + reserveTokens: number, + apiKey: string | undefined, + signal?: AbortSignal, + customInstructions?: string, + previousSummary?: string, + complete: CompleteFn = completeSimple, ): Promise { const maxTokens = Math.floor(0.8 * reserveTokens); @@ -526,7 +619,7 @@ export async function generateSummary( ? { maxTokens, signal, apiKey, reasoning: "high" as const } : { maxTokens, signal, apiKey }; - const response = await completeSimple( + const response = await complete( model, { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: createSummarizationMessage(promptText) }, completionOptions, diff --git a/packages/pi-coding-agent/src/core/contextual-tips.test.ts b/packages/pi-coding-agent/src/core/contextual-tips.test.ts new file mode 100644 index 000000000..29341e659 --- /dev/null +++ b/packages/pi-coding-agent/src/core/contextual-tips.test.ts @@ -0,0 +1,259 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { ContextualTips } from "./contextual-tips.js"; + +const baseCtx = { + input: "hello world", + isStreaming: false, + thinkingLevel: "off" as string, + contextPercent: undefined as number | undefined, +}; + +describe("ContextualTips", () => { + describe("shell-command-prefix tip", () => { + it("fires for bare shell commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "ls -la" }); + assert.ok(result); + assert.ok(result.includes("looks like a shell command")); + assert.ok(result.includes("!")); + }); + + it("fires for various known commands", () => { + for (const cmd of ["pwd", "cd src", "cat file.txt", "grep foo bar", "git status", "npm install", "docker ps"]) { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: cmd }); + assert.ok(result, `Expected tip for "${cmd}"`); + assert.ok(result.includes("looks like a shell command")); + } + }); + + it("does not fire for commands already prefixed with !", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "!ls -la" }); + assert.equal(result, null); + }); + + it("does not fire for commands prefixed with !!", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "!!ls -la" }); + assert.equal(result, null); + }); + + it("does not fire for slash commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "/clear" }); + assert.equal(result, null); + }); + + it("does not fire for unknown commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "please help me fix this bug" }); + assert.equal(result, null); + }); + + it("does not fire for very long inputs", () => { + const tips = new ContextualTips(); + const longInput = "ls " + "a".repeat(200); + const result = tips.evaluate({ ...baseCtx, input: longInput }); + assert.equal(result, null); + }); + + it("respects maxShows (2)", () => { + const tips = new ContextualTips(); + tips.evaluate({ ...baseCtx, input: "ls" }); + tips.evaluate({ ...baseCtx, input: "pwd" }); + const third = tips.evaluate({ ...baseCtx, input: "cat foo" }); + assert.equal(third, null); + }); + }); + + describe("large-paste tip", () => { + it("fires for large inputs", () => { + const tips = new ContextualTips(); + const largeInput = "a".repeat(2500); + const result = tips.evaluate({ ...baseCtx, input: largeInput }); + assert.ok(result); + assert.ok(result.includes("Large inputs")); + }); + + it("does not fire for normal-length inputs", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "fix the login bug" }); + assert.equal(result, null); + }); + + it("does not fire for large bash commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "!" + "a".repeat(2500) }); + assert.equal(result, null); + }); + + it("respects maxShows (2)", () => { + const tips = new ContextualTips(); + const large = "x".repeat(3000); + tips.evaluate({ ...baseCtx, input: large }); + tips.evaluate({ ...baseCtx, input: large }); + const third = tips.evaluate({ ...baseCtx, input: large }); + assert.equal(third, null); + }); + }); + + describe("thinking-level-high tip", () => { + it("fires for short inputs with high thinking", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "what is 2+2?", thinkingLevel: "high" }); + assert.ok(result); + assert.ok(result.includes("Thinking is set to high")); + }); + + it("fires for xhigh thinking", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "what time is it?", thinkingLevel: "xhigh" }); + assert.ok(result); + assert.ok(result.includes("Thinking is set to xhigh")); + }); + + it("does not fire for low/medium thinking", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "what is 2+2?", thinkingLevel: "medium" }); + assert.equal(result, null); + }); + + it("does not fire for long inputs", () => { + const tips = new ContextualTips(); + const longInput = "Please help me refactor this entire authentication module to use JWT tokens instead of session cookies. " + + "I need to update the middleware, the login handler, and the user model."; + const result = tips.evaluate({ ...baseCtx, input: longInput, thinkingLevel: "high" }); + assert.equal(result, null); + }); + + it("does not fire for slash commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "/model", thinkingLevel: "high" }); + assert.equal(result, null); + }); + + it("respects maxShows (1)", () => { + const tips = new ContextualTips(); + tips.evaluate({ ...baseCtx, input: "hi", thinkingLevel: "high" }); + const second = tips.evaluate({ ...baseCtx, input: "hello", thinkingLevel: "high" }); + assert.equal(second, null); + }); + }); + + describe("double-bang-reminder tip", () => { + it("fires after 3+ included bash commands", () => { + const tips = new ContextualTips(); + tips.recordBashIncluded(); + tips.recordBashIncluded(); + tips.recordBashIncluded(); + const result = tips.evaluate({ ...baseCtx, input: "!ls" }); + assert.ok(result); + assert.ok(result.includes("!!")); + }); + + it("does not fire with fewer than 3 included commands", () => { + const tips = new ContextualTips(); + tips.recordBashIncluded(); + tips.recordBashIncluded(); + const result = tips.evaluate({ ...baseCtx, input: "!ls" }); + assert.equal(result, null); + }); + + it("does not fire for !! commands", () => { + const tips = new ContextualTips(); + tips.recordBashIncluded(); + tips.recordBashIncluded(); + tips.recordBashIncluded(); + const result = tips.evaluate({ ...baseCtx, input: "!!ls" }); + assert.equal(result, null); + }); + + it("respects maxShows (2)", () => { + const tips = new ContextualTips(); + for (let i = 0; i < 5; i++) tips.recordBashIncluded(); + tips.evaluate({ ...baseCtx, input: "!ls" }); + tips.evaluate({ ...baseCtx, input: "!pwd" }); + const third = tips.evaluate({ ...baseCtx, input: "!cat foo" }); + assert.equal(third, null); + }); + }); + + describe("compaction-nudge tip", () => { + it("fires when context is >= 70%", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "fix the bug", contextPercent: 75 }); + assert.ok(result); + assert.ok(result.includes("/compact")); + }); + + it("does not fire when context is < 70%", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "fix the bug", contextPercent: 50 }); + assert.equal(result, null); + }); + + it("does not fire when contextPercent is undefined", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "fix the bug", contextPercent: undefined }); + assert.equal(result, null); + }); + + it("does not fire for slash commands", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "/model", contextPercent: 90 }); + assert.equal(result, null); + }); + + it("respects maxShows (1)", () => { + const tips = new ContextualTips(); + tips.evaluate({ ...baseCtx, input: "hello", contextPercent: 80 }); + const second = tips.evaluate({ ...baseCtx, input: "world", contextPercent: 85 }); + assert.equal(second, null); + }); + }); + + describe("reset", () => { + it("resets all show counters", () => { + const tips = new ContextualTips(); + // Exhaust shell-command-prefix tip + tips.evaluate({ ...baseCtx, input: "ls" }); + tips.evaluate({ ...baseCtx, input: "pwd" }); + assert.equal(tips.evaluate({ ...baseCtx, input: "cat foo" }), null); + + tips.reset(); + + // Should fire again after reset + const result = tips.evaluate({ ...baseCtx, input: "ls" }); + assert.ok(result); + assert.ok(result.includes("looks like a shell command")); + }); + + it("resets bash included count", () => { + const tips = new ContextualTips(); + for (let i = 0; i < 5; i++) tips.recordBashIncluded(); + assert.equal(tips.bashIncludedCount, 5); + + tips.reset(); + assert.equal(tips.bashIncludedCount, 0); + }); + }); + + describe("priority — first match wins", () => { + it("shell-command-prefix takes priority over compaction nudge", () => { + const tips = new ContextualTips(); + const result = tips.evaluate({ ...baseCtx, input: "ls", contextPercent: 80 }); + assert.ok(result); + assert.ok(result.includes("looks like a shell command")); + }); + + it("large-paste takes priority over compaction nudge", () => { + const tips = new ContextualTips(); + const largeInput = "x".repeat(3000); + const result = tips.evaluate({ ...baseCtx, input: largeInput, contextPercent: 80 }); + assert.ok(result); + assert.ok(result.includes("Large inputs")); + }); + }); +}); diff --git a/packages/pi-coding-agent/src/core/contextual-tips.ts b/packages/pi-coding-agent/src/core/contextual-tips.ts new file mode 100644 index 000000000..d3ac27ec6 --- /dev/null +++ b/packages/pi-coding-agent/src/core/contextual-tips.ts @@ -0,0 +1,232 @@ +/** + * Contextual tips system — shows non-intrusive, session-scoped hints + * when user behavior suggests they'd benefit from knowing a feature. + * + * Each tip fires at most `maxShows` times per session. Tips are + * evaluated in order; the first match wins per input event. + */ + +// ─── Tip definitions ───────────────────────────────────────────────────────── + +export interface TipContext { + /** The raw input text the user submitted */ + input: string; + /** Whether the agent is currently streaming */ + isStreaming: boolean; + /** Current thinking level (e.g. "off", "low", "high", "xhigh") */ + thinkingLevel?: string; + /** Number of `!` (included) bash commands run this session */ + bashIncludedCount: number; + /** Approximate context usage percentage (0–100), if known */ + contextPercent?: number; +} + +export interface Tip { + id: string; + /** Maximum times this tip is shown per session */ + maxShows: number; + /** Returns the tip message if the tip should fire, or null to skip */ + evaluate: (ctx: TipContext) => string | null; +} + +// Shell commands that obviously run locally and don't need the LLM. +// Intentionally conservative — these are unambiguous filesystem/info commands. +const LOCAL_SHELL_COMMANDS = new Set([ + "ls", + "ll", + "la", + "pwd", + "cd", + "dir", + "cat", + "head", + "tail", + "wc", + "file", + "which", + "whoami", + "echo", + "date", + "tree", + "find", + "grep", + "rg", + "clear", + "env", + "df", + "du", + "uname", + "hostname", + "mkdir", + "rm", + "cp", + "mv", + "touch", + "chmod", + "less", + "more", + "sort", + "uniq", + "sed", + "awk", + "curl", + "wget", + "tar", + "zip", + "unzip", + "git", + "docker", + "npm", + "npx", + "yarn", + "pnpm", + "node", + "python", + "python3", + "pip", + "pip3", + "make", + "cargo", + "go", + "ruby", + "brew", +]); + +/** + * Extract the first token from input, ignoring leading whitespace. + * Returns lowercase for case-insensitive matching. + */ +function firstToken(input: string): string { + const trimmed = input.trimStart(); + const spaceIdx = trimmed.search(/\s/); + const token = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx); + return token.toLowerCase(); +} + +/** + * Check if input looks like a bare shell command (no !, //, or slash prefix). + */ +function looksLikeShellCommand(input: string): boolean { + const trimmed = input.trimStart(); + // Already prefixed — user knows what they're doing + if (trimmed.startsWith("!") || trimmed.startsWith("/")) return false; + // Multi-line or very long inputs are probably prompts + if (trimmed.includes("\n") || trimmed.length > 120) return false; + return LOCAL_SHELL_COMMANDS.has(firstToken(trimmed)); +} + +const TIPS: Tip[] = [ + // 1. Shell command reminder + { + id: "shell-command-prefix", + maxShows: 2, + evaluate(ctx) { + if (!looksLikeShellCommand(ctx.input)) return null; + const cmd = firstToken(ctx.input); + return `Tip: "${cmd}" looks like a shell command. Prefix with ! to run locally, or !! to run without using tokens.`; + }, + }, + + // 2. Large paste warning + { + id: "large-paste", + maxShows: 2, + evaluate(ctx) { + if (ctx.input.length < 2000) return null; + // Slash commands and bash prefixes are intentional + if (ctx.input.trimStart().startsWith("/") || ctx.input.trimStart().startsWith("!")) return null; + return "Tip: Large inputs consume many tokens. Consider saving to a file and asking the agent to read it."; + }, + }, + + // 3. Thinking level awareness + { + id: "thinking-level-high", + maxShows: 1, + evaluate(ctx) { + const level = ctx.thinkingLevel?.toLowerCase(); + if (level !== "high" && level !== "xhigh") return null; + // Only fire for short, simple-looking inputs (likely simple questions) + const trimmed = ctx.input.trim(); + if (trimmed.length > 80 || trimmed.includes("\n")) return null; + // Don't fire on slash or bash commands + if (trimmed.startsWith("/") || trimmed.startsWith("!")) return null; + return `Tip: Thinking is set to ${level}. Use Ctrl+T to lower it for simple questions — saves tokens.`; + }, + }, + + // 4. Double-bang reminder + { + id: "double-bang-reminder", + maxShows: 2, + evaluate(ctx) { + // Fire after user has run 3+ included (!) bash commands + if (ctx.bashIncludedCount < 3) return null; + // Only trigger on a ! command (not !!) + const trimmed = ctx.input.trimStart(); + if (!trimmed.startsWith("!") || trimmed.startsWith("!!")) return null; + return "Tip: Use !! instead of ! to keep command output out of agent context and save tokens."; + }, + }, + + // 5. Compaction nudge + { + id: "compaction-nudge", + maxShows: 1, + evaluate(ctx) { + if (ctx.contextPercent === undefined || ctx.contextPercent < 70) return null; + // Don't nag on slash/bash + const trimmed = ctx.input.trimStart(); + if (trimmed.startsWith("/") || trimmed.startsWith("!")) return null; + return "Tip: Context is getting full. Use /compact to summarize the conversation and free up space."; + }, + }, +]; + +// ─── Session-scoped tracker ────────────────────────────────────────────────── + +export class ContextualTips { + /** Map of tip ID → number of times shown this session */ + private showCounts = new Map(); + /** Track ! bash commands for double-bang reminder */ + private _bashIncludedCount = 0; + + /** Increment the bash-included counter. Call when user runs ! (not !!) command. */ + recordBashIncluded(): void { + this._bashIncludedCount++; + } + + get bashIncludedCount(): number { + return this._bashIncludedCount; + } + + /** + * Evaluate all tips against the current input context. + * Returns the first matching tip message, or null if none apply. + */ + evaluate(ctx: Omit): string | null { + const fullCtx: TipContext = { + ...ctx, + bashIncludedCount: this._bashIncludedCount, + }; + + for (const tip of TIPS) { + const shown = this.showCounts.get(tip.id) ?? 0; + if (shown >= tip.maxShows) continue; + + const message = tip.evaluate(fullCtx); + if (message) { + this.showCounts.set(tip.id, shown + 1); + return message; + } + } + + return null; + } + + /** Reset all counters (e.g. on new session). */ + reset(): void { + this.showCounts.clear(); + this._bashIncludedCount = 0; + } +} diff --git a/packages/pi-coding-agent/src/core/exec.ts b/packages/pi-coding-agent/src/core/exec.ts index b7dd046c4..9d12e8c23 100644 --- a/packages/pi-coding-agent/src/core/exec.ts +++ b/packages/pi-coding-agent/src/core/exec.ts @@ -39,7 +39,9 @@ export async function execCommand( return new Promise((resolve) => { const proc = spawn(command, args, { cwd, - shell: false, + // On Windows, npm/npx/tsc etc. are .cmd scripts that require shell + // resolution. Without this, spawn fails with ENOENT or EINVAL (#2854). + shell: process.platform === "win32", stdio: ["ignore", "pipe", "pipe"], }); diff --git a/packages/pi-coding-agent/src/core/extensions/extension-manifest.test.ts b/packages/pi-coding-agent/src/core/extensions/extension-manifest.test.ts new file mode 100644 index 000000000..3796ab071 --- /dev/null +++ b/packages/pi-coding-agent/src/core/extensions/extension-manifest.test.ts @@ -0,0 +1,77 @@ +// GSD-2 — Extension Manifest Tests +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { readManifest, readManifestFromEntryPath } from "./extension-manifest.js"; + +describe("readManifest", () => { + it("returns null for missing directory", () => { + assert.equal(readManifest("/nonexistent/path"), null); + }); + + it("returns null for directory without manifest", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + assert.equal(readManifest(dir), null); + }); + + it("returns null for invalid JSON", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + writeFileSync(join(dir, "extension-manifest.json"), "not json{{{", "utf-8"); + assert.equal(readManifest(dir), null); + }); + + it("returns null for manifest missing required fields", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + writeFileSync( + join(dir, "extension-manifest.json"), + JSON.stringify({ id: "test", name: "test" }), + ); + assert.equal(readManifest(dir), null); + }); + + it("returns valid manifest", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + const manifest = { + id: "test-ext", + name: "Test Extension", + version: "1.0.0", + tier: "bundled", + requires: { platform: ">=2.29.0" }, + }; + writeFileSync(join(dir, "extension-manifest.json"), JSON.stringify(manifest)); + const result = readManifest(dir); + assert.equal(result?.id, "test-ext"); + assert.equal(result?.tier, "bundled"); + }); +}); + +describe("readManifestFromEntryPath", () => { + it("reads manifest from parent of entry path", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + const extDir = join(dir, "my-ext"); + mkdirSync(extDir); + writeFileSync( + join(extDir, "extension-manifest.json"), + JSON.stringify({ + id: "my-ext", + name: "My Extension", + version: "1.0.0", + tier: "community", + }), + ); + writeFileSync(join(extDir, "index.ts"), ""); + + const result = readManifestFromEntryPath(join(extDir, "index.ts")); + assert.equal(result?.id, "my-ext"); + assert.equal(result?.tier, "community"); + }); + + it("returns null when entry path parent has no manifest", () => { + const dir = mkdtempSync(join(tmpdir(), "ext-manifest-")); + assert.equal(readManifestFromEntryPath(join(dir, "index.ts")), null); + }); +}); diff --git a/packages/pi-coding-agent/src/core/extensions/extension-manifest.ts b/packages/pi-coding-agent/src/core/extensions/extension-manifest.ts new file mode 100644 index 000000000..673f5a410 --- /dev/null +++ b/packages/pi-coding-agent/src/core/extensions/extension-manifest.ts @@ -0,0 +1,62 @@ +// GSD-2 — Extension Manifest: Types and reading for extension-manifest.json +// Copyright (c) 2026 Jeremy McSpadden + +import { existsSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface ExtensionManifest { + id: string; + name: string; + version: string; + description: string; + tier: "core" | "bundled" | "community"; + requires: { platform: string }; + provides?: { + tools?: string[]; + commands?: string[]; + hooks?: string[]; + shortcuts?: string[]; + }; + dependencies?: { + extensions?: string[]; + runtime?: string[]; + }; +} + +// ─── Validation ───────────────────────────────────────────────────────────── + +function isManifest(data: unknown): data is ExtensionManifest { + if (typeof data !== "object" || data === null) return false; + const obj = data as Record; + return ( + typeof obj.id === "string" && + typeof obj.name === "string" && + typeof obj.version === "string" && + typeof obj.tier === "string" + ); +} + +// ─── Reading ──────────────────────────────────────────────────────────────── + +/** Read extension-manifest.json from a directory. Returns null if missing or invalid. */ +export function readManifest(extensionDir: string): ExtensionManifest | null { + const manifestPath = join(extensionDir, "extension-manifest.json"); + if (!existsSync(manifestPath)) return null; + try { + const raw = JSON.parse(readFileSync(manifestPath, "utf-8")); + return isManifest(raw) ? raw : null; + } catch { + return null; + } +} + +/** + * Given an entry path (e.g. `.../extensions/browser-tools/index.ts`), + * resolve the parent directory and read its manifest. + */ +export function readManifestFromEntryPath(entryPath: string): ExtensionManifest | null { + const dir = dirname(entryPath); + return readManifest(dir); +} diff --git a/packages/pi-coding-agent/src/core/extensions/extension-sort.test.ts b/packages/pi-coding-agent/src/core/extensions/extension-sort.test.ts new file mode 100644 index 000000000..30a4b667e --- /dev/null +++ b/packages/pi-coding-agent/src/core/extensions/extension-sort.test.ts @@ -0,0 +1,134 @@ +// GSD-2 — Extension Sort Tests +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { sortExtensionPaths } from "./extension-sort.js"; + +function createExtDir(base: string, id: string, deps?: string[]): string { + const dir = join(base, id); + mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, "extension-manifest.json"), + JSON.stringify({ + id, + name: id, + version: "1.0.0", + tier: "bundled", + requires: { platform: ">=2.29.0" }, + ...(deps ? { dependencies: { extensions: deps } } : {}), + }), + ); + writeFileSync(join(dir, "index.ts"), `export default function() {}`); + return join(dir, "index.ts"); +} + +describe("sortExtensionPaths", () => { + it("returns empty for empty input", () => { + const result = sortExtensionPaths([]); + assert.deepEqual(result.sortedPaths, []); + assert.deepEqual(result.warnings, []); + }); + + it("sorts independent extensions alphabetically", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathC = createExtDir(base, "charlie"); + const pathA = createExtDir(base, "alpha"); + const pathB = createExtDir(base, "bravo"); + + const result = sortExtensionPaths([pathC, pathA, pathB]); + assert.deepEqual(result.sortedPaths, [pathA, pathB, pathC]); + assert.equal(result.warnings.length, 0); + }); + + it("sorts dependencies before dependents", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathBase = createExtDir(base, "base-ext"); + const pathDependent = createExtDir(base, "dependent-ext", ["base-ext"]); + + // Pass dependent first — sort should reorder + const result = sortExtensionPaths([pathDependent, pathBase]); + assert.deepEqual(result.sortedPaths, [pathBase, pathDependent]); + assert.equal(result.warnings.length, 0); + }); + + it("handles deep dependency chains", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathA = createExtDir(base, "a"); + const pathB = createExtDir(base, "b", ["a"]); + const pathC = createExtDir(base, "c", ["b"]); + + const result = sortExtensionPaths([pathC, pathB, pathA]); + assert.deepEqual(result.sortedPaths, [pathA, pathB, pathC]); + assert.equal(result.warnings.length, 0); + }); + + it("warns about missing dependencies but still loads", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathExt = createExtDir(base, "my-ext", ["nonexistent"]); + + const result = sortExtensionPaths([pathExt]); + assert.equal(result.sortedPaths.length, 1); + assert.equal(result.sortedPaths[0], pathExt); + assert.equal(result.warnings.length, 1); + assert.match(result.warnings[0].message, /nonexistent.*not installed/); + }); + + it("warns about cycles but still loads both", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathA = createExtDir(base, "cycle-a", ["cycle-b"]); + const pathB = createExtDir(base, "cycle-b", ["cycle-a"]); + + const result = sortExtensionPaths([pathA, pathB]); + assert.equal(result.sortedPaths.length, 2); + assert.ok(result.warnings.length > 0); + assert.ok(result.warnings.some((w) => w.message.includes("cycle"))); + }); + + it("silently ignores self-dependencies", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const pathExt = createExtDir(base, "self-dep", ["self-dep"]); + + const result = sortExtensionPaths([pathExt]); + assert.deepEqual(result.sortedPaths, [pathExt]); + assert.equal(result.warnings.length, 0); + }); + + it("prepends extensions without manifests", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const noManifestDir = join(base, "no-manifest"); + mkdirSync(noManifestDir, { recursive: true }); + writeFileSync(join(noManifestDir, "index.ts"), `export default function() {}`); + const noManifestPath = join(noManifestDir, "index.ts"); + + const pathWithManifest = createExtDir(base, "with-manifest"); + + const result = sortExtensionPaths([pathWithManifest, noManifestPath]); + assert.equal(result.sortedPaths[0], noManifestPath); + assert.equal(result.sortedPaths[1], pathWithManifest); + }); + + it("handles non-array dependencies gracefully", () => { + const base = mkdtempSync(join(tmpdir(), "ext-sort-")); + const dir = join(base, "bad-deps"); + mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, "extension-manifest.json"), + JSON.stringify({ + id: "bad-deps", + name: "bad-deps", + version: "1.0.0", + tier: "bundled", + dependencies: { extensions: "not-an-array" }, + }), + ); + writeFileSync(join(dir, "index.ts"), `export default function() {}`); + + const result = sortExtensionPaths([join(dir, "index.ts")]); + assert.equal(result.sortedPaths.length, 1); + assert.equal(result.warnings.length, 0); + }); +}); diff --git a/packages/pi-coding-agent/src/core/extensions/extension-sort.ts b/packages/pi-coding-agent/src/core/extensions/extension-sort.ts new file mode 100644 index 000000000..07a3e67d6 --- /dev/null +++ b/packages/pi-coding-agent/src/core/extensions/extension-sort.ts @@ -0,0 +1,137 @@ +// GSD-2 — Extension Sort: Topological dependency ordering +// Copyright (c) 2026 Jeremy McSpadden + +import { readManifestFromEntryPath } from "./extension-manifest.js"; + +export interface SortWarning { + declaringId: string; + missingId: string; + message: string; +} + +export interface SortResult { + sortedPaths: string[]; + warnings: SortWarning[]; +} + +/** + * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm. + * + * - Extensions without manifests are prepended in input order. + * - Missing dependencies produce a structured warning but do not block loading. + * - Cycles produce warnings; cycle participants are appended alphabetically. + * - Self-dependencies are silently ignored. + */ +export function sortExtensionPaths(paths: string[]): SortResult { + const warnings: SortWarning[] = []; + const pathsWithoutId: string[] = []; + const idToPath = new Map(); + + // Step 1: Build ID map + for (const p of paths) { + const manifest = readManifestFromEntryPath(p); + if (!manifest) { + pathsWithoutId.push(p); + } else { + idToPath.set(manifest.id, p); + } + } + + // Step 2: Build graph — inDegree and dependents adjacency + const inDegree = new Map(); + const dependents = new Map(); // dep → [ids that depend on dep] + + for (const id of idToPath.keys()) { + if (!inDegree.has(id)) inDegree.set(id, 0); + if (!dependents.has(id)) dependents.set(id, []); + } + + for (const [id, entryPath] of idToPath) { + const manifest = readManifestFromEntryPath(entryPath); + const rawDeps = manifest?.dependencies?.extensions ?? []; + const deps = Array.isArray(rawDeps) ? rawDeps : []; + + for (const depId of deps) { + // Silently ignore self-deps + if (depId === id) continue; + + if (!idToPath.has(depId)) { + // Missing dependency — warn and skip edge + warnings.push({ + declaringId: id, + missingId: depId, + message: `Extension '${id}' declares dependency '${depId}' which is not installed — loading anyway`, + }); + continue; + } + + // Valid edge: id depends on depId → increment inDegree[id], add id to dependents[depId] + inDegree.set(id, (inDegree.get(id) ?? 0) + 1); + const depDependents = dependents.get(depId) ?? []; + depDependents.push(id); + dependents.set(depId, depDependents); + } + } + + // Step 3: Kahn's algorithm — start with nodes that have inDegree 0 + const sorted: string[] = []; + // Ready queue: IDs with inDegree 0, maintained in alphabetical order + const ready: string[] = [...idToPath.keys()] + .filter((id) => inDegree.get(id) === 0) + .sort(); + + while (ready.length > 0) { + const id = ready.shift()!; + sorted.push(idToPath.get(id)!); + + const deps = dependents.get(id) ?? []; + for (const depId of deps) { + const newDegree = (inDegree.get(depId) ?? 0) - 1; + inDegree.set(depId, newDegree); + if (newDegree === 0) { + // Insert into ready queue maintaining alphabetical order + const insertIdx = ready.findIndex((r) => r > depId); + if (insertIdx === -1) { + ready.push(depId); + } else { + ready.splice(insertIdx, 0, depId); + } + } + } + } + + // Step 4: Cycle handling — any remaining IDs with inDegree > 0 + const cycleIds = [...idToPath.keys()] + .filter((id) => (inDegree.get(id) ?? 0) > 0) + .sort(); + + if (cycleIds.length > 0) { + const cycleSet = new Set(cycleIds); + + for (const id of cycleIds) { + const entryPath = idToPath.get(id)!; + const manifest = readManifestFromEntryPath(entryPath); + const rawDeps = manifest?.dependencies?.extensions ?? []; + const deps = Array.isArray(rawDeps) ? rawDeps : []; + + for (const depId of deps) { + if (depId === id) continue; + if (!cycleSet.has(depId)) continue; + + // Both id and depId are in cycle — emit warning + warnings.push({ + declaringId: id, + missingId: depId, + message: `Extension '${id}' and '${depId}' form a dependency cycle — loading both anyway (alphabetical order)`, + }); + } + + sorted.push(entryPath); + } + } + + return { + sortedPaths: [...pathsWithoutId, ...sorted], + warnings, + }; +} diff --git a/packages/pi-coding-agent/src/core/extensions/index.ts b/packages/pi-coding-agent/src/core/extensions/index.ts index 1ef9b82a7..0438d364b 100644 --- a/packages/pi-coding-agent/src/core/extensions/index.ts +++ b/packages/pi-coding-agent/src/core/extensions/index.ts @@ -2,6 +2,10 @@ * Extension system for lifecycle events and custom tools. */ +export type { ExtensionManifest } from "./extension-manifest.js"; +export { readManifest, readManifestFromEntryPath } from "./extension-manifest.js"; +export type { SortResult, SortWarning } from "./extension-sort.js"; +export { sortExtensionPaths } from "./extension-sort.js"; export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from "../slash-commands.js"; export { createExtensionRuntime, @@ -39,6 +43,9 @@ export type { BeforeProviderRequestEventResult, // Context CompactOptions, + // Events - Adjust Tool Set (ADR-005) + AdjustToolSetEvent, + AdjustToolSetResult, // Events - Agent ContextEvent, // Event Results @@ -131,6 +138,7 @@ export type { ToolCallEvent, ToolCallEventResult, // Tools + ToolCompatibility, ToolDefinition, // Events - Tool Execution ToolExecutionEndEvent, diff --git a/packages/pi-coding-agent/src/core/extensions/loader.test.ts b/packages/pi-coding-agent/src/core/extensions/loader.test.ts index 65691e949..da547e525 100644 --- a/packages/pi-coding-agent/src/core/extensions/loader.test.ts +++ b/packages/pi-coding-agent/src/core/extensions/loader.test.ts @@ -4,7 +4,7 @@ import * as fs from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; import { isProjectTrusted, trustProject, getUntrustedExtensionPaths } from "./project-trust.js"; -import { containsTypeScriptSyntax, loadExtensions } from "./loader.js"; +import { containsTypeScriptSyntax, loadExtensions, resetExtensionLoaderCache } from "./loader.js"; // ─── helpers ────────────────────────────────────────────────────────────────── @@ -235,3 +235,41 @@ describe("loadExtensions", () => { ); }); }); + +// ─── resetExtensionLoaderCache ─────────────────────────────────────────────── + +describe("resetExtensionLoaderCache", () => { + let tmpDir: string; + + beforeEach(() => { + tmpDir = makeTempDir(); + // Always start with a clean cache so tests are independent + resetExtensionLoaderCache(); + }); + + afterEach(() => { + resetExtensionLoaderCache(); + cleanDir(tmpDir); + }); + + it("clears the jiti singleton so a fresh instance is created on next load", async () => { + // Write a minimal valid extension that returns a name + const extPath = path.join(tmpDir, "cache-ext.ts"); + fs.writeFileSync( + extPath, + `export default function activate(api: any) { return { name: "cache-ext" }; }\n`, + ); + + // First load — creates the jiti singleton and caches the module + const result1 = await loadExtensions([extPath], tmpDir); + assert.equal(result1.extensions.length, 1, "first load should succeed"); + + // Reset the cache — nulls the singleton + resetExtensionLoaderCache(); + + // Second load — should create a new jiti instance (not reuse the old one) + // and still successfully load the extension + const result2 = await loadExtensions([extPath], tmpDir); + assert.equal(result2.extensions.length, 1, "load after reset should succeed with fresh jiti"); + }); +}); diff --git a/packages/pi-coding-agent/src/core/extensions/loader.ts b/packages/pi-coding-agent/src/core/extensions/loader.ts index 24a4385b5..016f05448 100644 --- a/packages/pi-coding-agent/src/core/extensions/loader.ts +++ b/packages/pi-coding-agent/src/core/extensions/loader.ts @@ -38,6 +38,7 @@ import type { ExecOptions } from "../exec.js"; import { execCommand } from "../exec.js"; import { getUntrustedExtensionPaths } from "./project-trust.js"; export { isProjectTrusted, trustProject, getUntrustedExtensionPaths } from "./project-trust.js"; +import { registerToolCompatibility } from "../tools/tool-compatibility-registry.js"; import type { Extension, ExtensionAPI, @@ -428,6 +429,9 @@ export function createExtensionRuntime(): ExtensionRuntime { unregisterProvider: (name) => { runtime.pendingProviderRegistrations = runtime.pendingProviderRegistrations.filter((r) => r.name !== name); }, + // Stubs replaced by ExtensionRunner at construction time via bindEmitMethods(). + emitBeforeModelSelect: async () => undefined, + emitAdjustToolSet: async () => undefined, }; return runtime; @@ -457,6 +461,10 @@ function createExtensionAPI( definition: tool, extensionPath: extension.path, }); + // ADR-005: auto-register tool compatibility metadata + if (tool.compatibility) { + registerToolCompatibility(tool.name, tool.compatibility); + } runtime.refreshTools(); }, @@ -579,6 +587,14 @@ function createExtensionAPI( runtime.unregisterProvider(name); }, + async emitBeforeModelSelect(event: Omit): Promise { + return runtime.emitBeforeModelSelect(event); + }, + + async emitAdjustToolSet(event: Omit): Promise { + return runtime.emitAdjustToolSet(event); + }, + events: eventBus, } as ExtensionAPI; @@ -618,6 +634,39 @@ export function containsTypeScriptSyntax(source: string): boolean { return TS_SYNTAX_PATTERNS.some((pattern) => pattern.test(source)); } +/** + * Shared jiti instance for loading extension modules. + * + * Before this fix (#2108), each extension created a NEW jiti instance with + * `moduleCache: false`, causing shared dependencies (e.g. @gsd/pi-agent-core) + * to be recompiled for every extension — turning a ~3s parallel load into a + * ~15-30s serial compilation bottleneck. + * + * Using a single shared instance with `moduleCache: true` means shared modules + * are compiled once and reused across all extensions. + */ +let _extensionLoaderJiti: ReturnType | null = null; + +/** + * Reset the shared jiti singleton so the next call to getExtensionLoaderJiti() + * creates a fresh instance. This prevents memory leaks in long-running daemon + * processes (every loaded module stays cached forever) and ensures stale modules + * are not returned when extension source changes on disk. + */ +export function resetExtensionLoaderCache(): void { + _extensionLoaderJiti = null; +} + +function getExtensionLoaderJiti() { + if (!_extensionLoaderJiti) { + _extensionLoaderJiti = createJiti(import.meta.url, { + moduleCache: true, + ...getJitiOptions(), + }); + } + return _extensionLoaderJiti; +} + async function loadExtensionModule(extensionPath: string) { // Pre-compiled extension loading: if the source is .ts and a sibling .js // file exists with matching or newer mtime, use native import() to skip @@ -637,10 +686,7 @@ async function loadExtensionModule(extensionPath: string) { } } - const jiti = createJiti(import.meta.url, { - moduleCache: false, - ...getJitiOptions(), - }); + const jiti = getExtensionLoaderJiti(); const module = await jiti.import(extensionPath, { default: true }); const factory = module as ExtensionFactory; @@ -941,6 +987,11 @@ function discoverExtensionsInDir(dir: string): string[] { /** * Discover and load extensions from standard locations. + * + * @deprecated Use DefaultResourceLoader.reload() instead — this function is + * not called in the GSD loading flow. Extension discovery happens through + * DefaultPackageManager.resolve() → addAutoDiscoveredResources(). Kept for + * backwards compatibility with direct pi-coding-agent consumers. */ export async function discoverAndLoadExtensions( configuredPaths: string[], diff --git a/packages/pi-coding-agent/src/core/extensions/provider-registration.test.ts b/packages/pi-coding-agent/src/core/extensions/provider-registration.test.ts new file mode 100644 index 000000000..2679feae6 --- /dev/null +++ b/packages/pi-coding-agent/src/core/extensions/provider-registration.test.ts @@ -0,0 +1,81 @@ +// GSD2 — Regression test: pendingProviderRegistrations must be flushed exactly once (#3576) +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +/** + * This test validates that the provider preflush pattern in sdk.ts clears + * pendingProviderRegistrations after iterating, so bindCore() doesn't + * re-register the same providers. + * + * The bug: createAgentSession() iterated pendingProviderRegistrations but + * did not clear the array. Later, bindCore() replayed and registered the + * same providers again, stacking wrappers. + */ + +interface ProviderEntry { + name: string; + config: Record; +} + +interface MockRuntime { + pendingProviderRegistrations: ProviderEntry[]; +} + +describe("provider registration preflush", () => { + it("clears pending registrations after preflush so bindCore does not replay", () => { + const registered: string[] = []; + const runtime: MockRuntime = { + pendingProviderRegistrations: [ + { name: "ollama", config: { type: "ollama" } }, + { name: "custom-provider", config: { type: "custom" } }, + ], + }; + + // Simulate sdk.ts preflush (lines 220-223) + for (const { name } of runtime.pendingProviderRegistrations) { + registered.push(name); + } + // The fix: clear after preflush + runtime.pendingProviderRegistrations = []; + + // Simulate bindCore() flush (runner.ts lines 268-271) + for (const { name } of runtime.pendingProviderRegistrations) { + registered.push(name); + } + runtime.pendingProviderRegistrations = []; + + assert.deepEqual( + registered, + ["ollama", "custom-provider"], + "each provider should be registered exactly once", + ); + }); + + it("without the fix, providers are registered twice", () => { + const registered: string[] = []; + const runtime: MockRuntime = { + pendingProviderRegistrations: [ + { name: "ollama", config: { type: "ollama" } }, + ], + }; + + // Old behavior: preflush without clearing + for (const { name } of runtime.pendingProviderRegistrations) { + registered.push(name); + } + // NOT clearing — simulating the old bug + + // bindCore() replays the same queue + for (const { name } of runtime.pendingProviderRegistrations) { + registered.push(name); + } + + assert.deepEqual( + registered, + ["ollama", "ollama"], + "without clearing, providers are registered twice (demonstrating the bug)", + ); + }); +}); diff --git a/packages/pi-coding-agent/src/core/extensions/runner.ts b/packages/pi-coding-agent/src/core/extensions/runner.ts index da06f0f13..0b0f6114b 100644 --- a/packages/pi-coding-agent/src/core/extensions/runner.ts +++ b/packages/pi-coding-agent/src/core/extensions/runner.ts @@ -11,8 +11,12 @@ import type { KeyAction, KeybindingsConfig } from "../keybindings.js"; import type { ModelRegistry } from "../model-registry.js"; import type { SessionManager } from "../session-manager.js"; import type { + AdjustToolSetEvent, + AdjustToolSetResult, BeforeAgentStartEvent, BeforeAgentStartEventResult, + BeforeModelSelectEvent, + BeforeModelSelectResult, BeforeProviderRequestEvent, CompactOptions, ContextEvent, @@ -230,6 +234,9 @@ export class ExtensionRunner { this.cwd = cwd; this.sessionManager = sessionManager; this.modelRegistry = modelRegistry; + // Bind emit methods into the shared runtime so createExtensionAPI can delegate to them. + this.runtime.emitBeforeModelSelect = (event) => this.emitBeforeModelSelect(event); + this.runtime.emitAdjustToolSet = (event) => this.emitAdjustToolSet(event); } bindCore(actions: ExtensionActions, contextActions: ExtensionContextActions): void { @@ -694,6 +701,36 @@ export class ExtensionRunner { return currentPayload; } + async emitBeforeModelSelect(event: Omit): Promise { + let result: BeforeModelSelectResult | undefined; + await this.invokeHandlers("before_model_select", () => ({ + type: "before_model_select" as const, + ...event, + } satisfies BeforeModelSelectEvent), (handlerResult) => { + if (handlerResult) { + result = handlerResult as BeforeModelSelectResult; + return { done: true }; // first override wins + } + return { done: false }; + }); + return result; + } + + async emitAdjustToolSet(event: Omit): Promise { + let result: AdjustToolSetResult | undefined; + await this.invokeHandlers("adjust_tool_set", () => ({ + type: "adjust_tool_set" as const, + ...event, + } satisfies AdjustToolSetEvent), (handlerResult) => { + if (handlerResult) { + result = handlerResult as AdjustToolSetResult; + return { done: true }; // first override wins + } + return { done: false }; + }); + return result; + } + async emitBeforeAgentStart( prompt: string, images: ImageContent[] | undefined, diff --git a/packages/pi-coding-agent/src/core/extensions/types.ts b/packages/pi-coding-agent/src/core/extensions/types.ts index 8b6ff6ff1..5fea6389a 100644 --- a/packages/pi-coding-agent/src/core/extensions/types.ts +++ b/packages/pi-coding-agent/src/core/extensions/types.ts @@ -88,6 +88,8 @@ export interface ExtensionUIDialogOptions { timeout?: number; /** When true, the user can select multiple options. The return type becomes `string[]`. */ allowMultiple?: boolean; + /** When true, text input dialogs should hide typed characters if supported by the client surface. */ + secure?: boolean; } /** Placement for extension widgets. */ @@ -331,6 +333,19 @@ export interface ToolRenderResultOptions { isPartial: boolean; } +/** + * Tool compatibility metadata for provider-aware tool filtering (ADR-005 Phase 2). + * Tools without compatibility metadata are assumed universally compatible. + */ +export interface ToolCompatibility { + /** Tool produces image content in results (filtered for providers without imageToolResults) */ + producesImages?: boolean; + /** Tool requires schema features that some providers don't support (e.g., ["patternProperties"]) */ + schemaFeatures?: string[]; + /** Tool is effective only with models above a minimum capability threshold */ + minCapabilityTier?: "light" | "standard" | "heavy"; +} + /** * Tool definition for registerTool(). */ @@ -347,6 +362,8 @@ export interface ToolDefinition; + eligibleModels: string[]; + phaseConfig?: { primary: string; fallbacks: string[] }; +} + +/** Result from before_model_select event handler. Return { modelId } to override selection. */ +export interface BeforeModelSelectResult { + modelId: string; +} + +/** + * Fired after model selection to allow extensions to adjust the active tool set (ADR-005 Phase 4). + * Extensions can add, remove, or reorder tools based on the selected model's provider capabilities. + */ +export interface AdjustToolSetEvent { + type: "adjust_tool_set"; + /** The selected model's API type */ + selectedModelApi: string; + /** The selected model's provider */ + selectedModelProvider: string; + /** The selected model ID */ + selectedModelId: string; + /** Current active tool names */ + activeToolNames: string[]; + /** Tools already filtered by provider compatibility */ + filteredTools: string[]; +} + +/** Result from adjust_tool_set event handler. Return { toolNames } to override tool set. */ +export interface AdjustToolSetResult { + /** Replacement tool names. If omitted, the default filtering is used. */ + toolNames?: string[]; +} + // ============================================================================ // User Bash Events // ============================================================================ @@ -1052,6 +1109,18 @@ export interface ExtensionAPI { on(event: "tool_result", handler: ExtensionHandler): void; on(event: "user_bash", handler: ExtensionHandler): void; on(event: "input", handler: ExtensionHandler): void; + on(event: "before_model_select", handler: ExtensionHandler): void; + on(event: "adjust_tool_set", handler: ExtensionHandler): void; + + // ========================================================================= + // Event Emission (for host extensions that orchestrate model selection) + // ========================================================================= + + /** Emit before_model_select event. Returns override model ID or undefined. */ + emitBeforeModelSelect(event: Omit): Promise; + + /** Emit adjust_tool_set event (ADR-005). Returns override tool names or undefined. */ + emitAdjustToolSet(event: Omit): Promise; // ========================================================================= // Tool Registration @@ -1317,6 +1386,8 @@ export interface ProviderModelConfig { headers?: Record; /** OpenAI compatibility settings. */ compat?: Model["compat"]; + /** Opaque provider-specific options (e.g. Ollama keep_alive, num_gpu). */ + providerOptions?: Record; } /** Extension factory function type. Supports both sync and async initialization. */ @@ -1367,6 +1438,10 @@ export interface ExtensionRuntimeState { */ registerProvider: (name: string, config: ProviderConfig) => void; unregisterProvider: (name: string) => void; + /** Emit before_model_select event to all registered handlers. Bound by ExtensionRunner. */ + emitBeforeModelSelect: (event: Omit) => Promise; + /** Emit adjust_tool_set event to all registered handlers. Bound by ExtensionRunner (ADR-005). */ + emitAdjustToolSet: (event: Omit) => Promise; } /** diff --git a/packages/pi-coding-agent/src/core/image-overflow-recovery.test.ts b/packages/pi-coding-agent/src/core/image-overflow-recovery.test.ts new file mode 100644 index 000000000..de075c280 --- /dev/null +++ b/packages/pi-coding-agent/src/core/image-overflow-recovery.test.ts @@ -0,0 +1,228 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { + isImageDimensionError, + MANY_IMAGE_MAX_DIMENSION, + downsizeConversationImages, +} from "./image-overflow-recovery.js"; +import type { Message } from "@gsd/pi-ai"; + +// ─── isImageDimensionError ──────────────────────────────────────────────────── + +describe("isImageDimensionError", () => { + it("returns true for Anthropic many-image dimension error", () => { + const errorMessage = + 'Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.125.content.38.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}'; + assert.equal(isImageDimensionError(errorMessage), true); + }); + + it("returns true for bare dimension exceed message", () => { + const errorMessage = + "image dimensions exceed max allowed size for many-image requests: 2000 pixels"; + assert.equal(isImageDimensionError(errorMessage), true); + }); + + it("returns false for unrelated 400 error", () => { + const errorMessage = + 'Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: 4096 > 2048"}}'; + assert.equal(isImageDimensionError(errorMessage), false); + }); + + it("returns false for rate limit error", () => { + assert.equal(isImageDimensionError("429 rate limit exceeded"), false); + }); + + it("returns false for empty string", () => { + assert.equal(isImageDimensionError(""), false); + }); + + it("returns false for undefined", () => { + assert.equal(isImageDimensionError(undefined), false); + }); +}); + +// ─── MANY_IMAGE_MAX_DIMENSION ───────────────────────────────────────────────── + +describe("MANY_IMAGE_MAX_DIMENSION", () => { + it("is less than 2000 (the API-enforced limit)", () => { + assert.ok(MANY_IMAGE_MAX_DIMENSION < 2000); + }); + + it("is a positive integer", () => { + assert.ok(MANY_IMAGE_MAX_DIMENSION > 0); + assert.equal(MANY_IMAGE_MAX_DIMENSION, Math.floor(MANY_IMAGE_MAX_DIMENSION)); + }); +}); + +// ─── helpers ────────────────────────────────────────────────────────────────── + +function makeUserMsg(content: Message["content"] & any): Message { + return { role: "user", content, timestamp: Date.now() } as Message; +} + +function makeAssistantMsg(text: string): Message { + return { + role: "assistant", + content: [{ type: "text", text }], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-opus-4-6", + usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, + stopReason: "stop", + timestamp: Date.now(), + } as Message; +} + +function makeToolResultMsg(images: number): Message { + const content: any[] = []; + for (let i = 0; i < images; i++) { + content.push({ type: "image", data: `img${i}`, mimeType: "image/png" }); + } + return { + role: "toolResult", + toolCallId: `tc${Math.random()}`, + toolName: "screenshot", + content, + isError: false, + timestamp: Date.now(), + } as Message; +} + +// ─── downsizeConversationImages ─────────────────────────────────────────────── + +describe("downsizeConversationImages", () => { + it("counts images in user and toolResult messages", () => { + const messages: Message[] = [ + makeUserMsg([ + { type: "image", data: "img1", mimeType: "image/png" }, + { type: "image", data: "img2", mimeType: "image/png" }, + ]), + makeAssistantMsg("I see them"), + makeToolResultMsg(1), + ]; + + const result = downsizeConversationImages(messages); + assert.equal(result.imageCount, 3); + }); + + it("returns processed=false when no images present", () => { + const messages: Message[] = [ + makeUserMsg("just text"), + makeAssistantMsg("reply"), + ]; + + const result = downsizeConversationImages(messages); + assert.equal(result.imageCount, 0); + assert.equal(result.processed, false); + }); + + it("returns processed=false when image count <= RECENT_IMAGES_TO_KEEP", () => { + const messages: Message[] = [ + makeUserMsg([ + { type: "image", data: "img1", mimeType: "image/png" }, + ]), + makeAssistantMsg("got it"), + ]; + + const result = downsizeConversationImages(messages); + assert.equal(result.imageCount, 1); + assert.equal(result.processed, false); + }); + + it("strips older images when many images present, preserves recent ones", () => { + const messages: Message[] = []; + for (let i = 0; i < 25; i++) { + messages.push( + makeUserMsg([ + { type: "text", text: `message ${i}` }, + { type: "image", data: `img${i}`, mimeType: "image/png" }, + ]), + ); + messages.push(makeAssistantMsg(`reply ${i}`)); + } + + const result = downsizeConversationImages(messages); + assert.ok(result.processed); + assert.equal(result.imageCount, 25); + assert.equal(result.strippedCount, 20); // 25 - 5 recent + + // Count remaining images + let remainingImages = 0; + for (const msg of messages) { + if (msg.role === "assistant") continue; + if (typeof msg.content === "string") continue; + const arr = msg.content as any[]; + for (const block of arr) { + if (block.type === "image") remainingImages++; + } + } + assert.equal(remainingImages, 5, "Should keep exactly 5 most recent images"); + + // The 5 most recent user messages (indices 40,42,44,46,48) should have images + for (let i = 20; i < 25; i++) { + const userMsg = messages[i * 2]; // user messages at even indices + const arr = userMsg.content as any[]; + const hasImage = arr.some((c: any) => c.type === "image"); + assert.ok(hasImage, `Recent message ${i} should retain its image`); + } + }); + + it("adds text placeholder when stripping an image", () => { + const messages: Message[] = []; + for (let i = 0; i < 10; i++) { + messages.push( + makeUserMsg([ + { type: "image", data: `img${i}`, mimeType: "image/jpeg" }, + ]), + ); + messages.push(makeAssistantMsg(`reply ${i}`)); + } + + downsizeConversationImages(messages); + + // First message's image should have been replaced with text + const firstMsg = messages[0]; + const arr = firstMsg.content as any[]; + const placeholder = arr.find( + (c: any) => c.type === "text" && c.text.includes("[image removed"), + ); + assert.ok(placeholder, "Stripped image should be replaced with text placeholder"); + assert.ok( + placeholder.text.includes("image/jpeg"), + "Placeholder should mention original mime type", + ); + }); + + it("handles toolResult messages with images", () => { + const messages: Message[] = []; + for (let i = 0; i < 10; i++) { + messages.push(makeToolResultMsg(1)); + messages.push(makeAssistantMsg(`reply ${i}`)); + } + + const result = downsizeConversationImages(messages); + assert.equal(result.imageCount, 10); + assert.equal(result.strippedCount, 5); + assert.ok(result.processed); + }); + + it("handles mixed user and toolResult images", () => { + const messages: Message[] = []; + for (let i = 0; i < 8; i++) { + messages.push( + makeUserMsg([ + { type: "text", text: `check ${i}` }, + { type: "image", data: `uimg${i}`, mimeType: "image/png" }, + ]), + ); + messages.push(makeAssistantMsg(`processing ${i}`)); + messages.push(makeToolResultMsg(1)); + messages.push(makeAssistantMsg(`done ${i}`)); + } + + const result = downsizeConversationImages(messages); + // 8 user images + 8 tool result images = 16 total + assert.equal(result.imageCount, 16); + assert.equal(result.strippedCount, 11); // 16 - 5 recent + }); +}); diff --git a/packages/pi-coding-agent/src/core/image-overflow-recovery.ts b/packages/pi-coding-agent/src/core/image-overflow-recovery.ts new file mode 100644 index 000000000..3573514e4 --- /dev/null +++ b/packages/pi-coding-agent/src/core/image-overflow-recovery.ts @@ -0,0 +1,118 @@ +/** + * Image overflow recovery for many-image sessions. + * + * When a conversation accumulates many images (screenshots, file reads, etc.), + * the Anthropic API enforces a stricter per-image dimension limit (2000px) for + * "many-image requests." This module detects the resulting 400 error and + * recovers by stripping older images from the conversation history, preserving + * the most recent ones to maintain session continuity. + * + * @see https://github.com/gsd-build/gsd-2/issues/2874 + */ + +import type { Message, ImageContent, TextContent } from "@gsd/pi-ai"; + +/** + * Maximum image dimension (px) that the Anthropic API allows in many-image + * requests. Images at or above this size in a large conversation will be + * rejected with a 400 error. We use 1568 as the safe ceiling (Anthropic's + * recommended max for multi-image requests). + */ +export const MANY_IMAGE_MAX_DIMENSION = 1568; + +/** + * Number of recent images to preserve when stripping old images. + * Keeps the most recent screenshots/images so the model retains visual context + * for the current task. + */ +const RECENT_IMAGES_TO_KEEP = 5; + +/** + * Regex matching the Anthropic API error for oversized images in many-image requests. + */ +const IMAGE_DIMENSION_ERROR_RE = + /image.dimensions?.exceed.*max.*allowed.*size.*many.image/i; + +/** + * Detect whether an error message is the Anthropic "image dimensions exceed max + * allowed size for many-image requests" 400 error. + */ +export function isImageDimensionError(errorMessage: string | undefined | null): boolean { + if (!errorMessage) return false; + return IMAGE_DIMENSION_ERROR_RE.test(errorMessage); +} + +export interface DownsizeResult { + /** Total number of images found in the conversation */ + imageCount: number; + /** Whether any images were stripped */ + processed: boolean; + /** Number of images that were stripped */ + strippedCount: number; +} + +/** + * Strip older images from conversation messages to recover from many-image + * dimension errors. Preserves the N most recent images and replaces older ones + * with a text placeholder. + * + * Mutates messages in place (same pattern as replaceMessages/compaction). + * + * Accepts Message[] (the LLM message union) so it works with both + * agent.state.messages and session entries. + */ +export function downsizeConversationImages(messages: Message[]): DownsizeResult { + // First pass: collect all image locations (message index + content index) + const imageLocations: Array<{ msgIdx: number; contentIdx: number }> = []; + + for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) { + const msg = messages[msgIdx]; + if (msg.role === "assistant") continue; + + // UserMessage can have string content; ToolResultMessage always has array + if (msg.role === "user" && typeof msg.content === "string") continue; + + const contentArr = msg.content as (TextContent | ImageContent)[]; + if (!Array.isArray(contentArr)) continue; + + for (let contentIdx = 0; contentIdx < contentArr.length; contentIdx++) { + if (contentArr[contentIdx].type === "image") { + imageLocations.push({ msgIdx, contentIdx }); + } + } + } + + const imageCount = imageLocations.length; + if (imageCount === 0) { + return { imageCount: 0, processed: false, strippedCount: 0 }; + } + + // Determine which images to strip (all except the N most recent) + const stripCount = Math.max(0, imageCount - RECENT_IMAGES_TO_KEEP); + if (stripCount === 0) { + return { imageCount, processed: false, strippedCount: 0 }; + } + + const toStrip = imageLocations.slice(0, stripCount); + + // Second pass: replace stripped images with text placeholder. + // Process in reverse order to maintain content indices. + for (let i = toStrip.length - 1; i >= 0; i--) { + const { msgIdx, contentIdx } = toStrip[i]; + const msg = messages[msgIdx]; + if (msg.role === "assistant") continue; + if (msg.role === "user" && typeof msg.content === "string") continue; + + const contentArr = msg.content as (TextContent | ImageContent)[]; + const imageBlock = contentArr[contentIdx] as ImageContent; + const mimeType = imageBlock.mimeType || "image/unknown"; + + // Replace the image block with a text placeholder + (contentArr as any[])[contentIdx] = { + type: "text", + text: `[image removed to reduce context size — was ${mimeType}]`, + } as TextContent; + } + + return { imageCount, processed: true, strippedCount: stripCount }; +} diff --git a/packages/pi-coding-agent/src/core/index.ts b/packages/pi-coding-agent/src/core/index.ts index 10c6f1753..02af1c6dd 100644 --- a/packages/pi-coding-agent/src/core/index.ts +++ b/packages/pi-coding-agent/src/core/index.ts @@ -29,6 +29,7 @@ export { type ExecResult, type Extension, type ExtensionAPI, + type ExtensionManifest, type ExtensionCommandContext, type ExtensionContext, type ExtensionError, @@ -53,6 +54,11 @@ export { type SessionSwitchEvent, type SessionTreeEvent, type ToolCallEvent, + readManifest, + readManifestFromEntryPath, + type SortResult, + type SortWarning, + sortExtensionPaths, type ToolDefinition, type ToolRenderResultOptions, type ToolResultEvent, @@ -60,3 +66,5 @@ export { type TurnStartEvent, wrapToolsWithExtensions, } from "./extensions/index.js"; + +export { ContextualTips, type TipContext } from "./contextual-tips.js"; diff --git a/packages/pi-coding-agent/src/core/lsp/config.ts b/packages/pi-coding-agent/src/core/lsp/config.ts index cc104be21..29401a363 100644 --- a/packages/pi-coding-agent/src/core/lsp/config.ts +++ b/packages/pi-coding-agent/src/core/lsp/config.ts @@ -12,6 +12,11 @@ import type { ServerConfig } from "./types.js"; const require = createRequire(import.meta.url); const DEFAULTS = require("./defaults.json") as Record>; +/** Map legacy server keys to their current names so user overrides still merge. */ +const LEGACY_ALIASES: Record = { + "kotlin-language-server": "kotlin-lsp", +}; + export interface LspConfig { servers: Record; /** Idle timeout in milliseconds. If set, LSP clients will be shutdown after this period of inactivity. Disabled by default. */ @@ -109,7 +114,8 @@ function mergeServers( overrides: Record>, ): Record { const merged: Record = { ...base }; - for (const [name, config] of Object.entries(overrides)) { + for (const [rawName, config] of Object.entries(overrides)) { + const name = LEGACY_ALIASES[rawName] ?? rawName; if (merged[name]) { const candidate = { ...merged[name], ...config }; const normalized = normalizeServerConfig(name, candidate); @@ -166,16 +172,49 @@ export function hasRootMarkers(cwd: string, markers: string[]): boolean { // Local Binary Resolution // ============================================================================= -const LOCAL_BIN_PATHS: Array<{ markers: string[]; binDir: string }> = [ - { markers: ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"], binDir: "node_modules/.bin" }, - { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDir: ".venv/bin" }, - { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDir: "venv/bin" }, - { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDir: ".env/bin" }, - { markers: ["Gemfile", "Gemfile.lock"], binDir: "vendor/bundle/bin" }, - { markers: ["Gemfile", "Gemfile.lock"], binDir: "bin" }, - { markers: ["go.mod", "go.sum"], binDir: "bin" }, +const LOCAL_BIN_PATHS: Array<{ markers: string[]; binDirs: string[] }> = [ + { markers: ["package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"], binDirs: ["node_modules/.bin"] }, + { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDirs: [".venv/bin", ".venv/Scripts"] }, + { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDirs: ["venv/bin", "venv/Scripts"] }, + { markers: ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"], binDirs: [".env/bin", ".env/Scripts"] }, + { markers: ["Gemfile", "Gemfile.lock"], binDirs: ["vendor/bundle/bin"] }, + { markers: ["Gemfile", "Gemfile.lock"], binDirs: ["bin"] }, + { markers: ["go.mod", "go.sum"], binDirs: ["bin"] }, ]; +function getWindowsBinaryCandidates(command: string): string[] { + const ext = path.extname(command).toLowerCase(); + if (ext) { + return [command]; + } + + return [ + command, + `${command}.cmd`, + `${command}.bat`, + `${command}.exe`, + ]; +} + +export function resolveLocalBinaryPath(command: string, cwd: string, isWindows: boolean): string | null { + for (const { markers, binDirs } of LOCAL_BIN_PATHS) { + if (!hasRootMarkers(cwd, markers)) continue; + + for (const binDir of binDirs) { + const basePath = path.join(cwd, binDir, command); + const candidates = isWindows ? getWindowsBinaryCandidates(basePath) : [basePath]; + + for (const candidate of candidates) { + if (fs.existsSync(candidate)) { + return candidate; + } + } + } + } + + return null; +} + export function which(command: string): string | null { // On Windows, prefer `where.exe` over `which` — MSYS/Git Bash's `which` // returns POSIX paths (/c/Users/...) that Node's spawn() can't execute. @@ -190,15 +229,8 @@ export function which(command: string): string | null { } export function resolveCommand(command: string, cwd: string): string | null { - for (const { markers, binDir } of LOCAL_BIN_PATHS) { - if (hasRootMarkers(cwd, markers)) { - const localPath = path.join(cwd, binDir, command); - if (fs.existsSync(localPath)) { - return localPath; - } - } - } - + const localPath = resolveLocalBinaryPath(command, cwd, process.platform === "win32"); + if (localPath) return localPath; return which(command); } diff --git a/packages/pi-coding-agent/src/core/lsp/defaults.json b/packages/pi-coding-agent/src/core/lsp/defaults.json index dbea73b6c..6bc16ba82 100644 --- a/packages/pi-coding-agent/src/core/lsp/defaults.json +++ b/packages/pi-coding-agent/src/core/lsp/defaults.json @@ -189,8 +189,8 @@ "fileTypes": [".java"], "rootMarkers": ["pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", ".project"] }, - "kotlin-language-server": { - "command": "kotlin-language-server", + "kotlin-lsp": { + "command": "kotlin-lsp", "args": [], "fileTypes": [".kt", ".kts"], "rootMarkers": ["build.gradle", "build.gradle.kts", "pom.xml", "settings.gradle", "settings.gradle.kts"] diff --git a/packages/pi-coding-agent/src/core/lsp/index.ts b/packages/pi-coding-agent/src/core/lsp/index.ts index 61237e7eb..bd2718634 100644 --- a/packages/pi-coding-agent/src/core/lsp/index.ts +++ b/packages/pi-coding-agent/src/core/lsp/index.ts @@ -340,6 +340,9 @@ async function runWorkspaceDiagnostics( const proc = spawn(cmd, cmdArgs, { cwd, stdio: ["ignore", "pipe", "pipe"], + // On Windows, project-type commands (tsc, cargo, etc.) may be .cmd + // wrappers that need shell resolution to avoid ENOENT/EINVAL (#2854). + shell: process.platform === "win32", }); const abortHandler = () => { proc.kill(); diff --git a/packages/pi-coding-agent/src/core/lsp/lsp-legacy-alias.test.ts b/packages/pi-coding-agent/src/core/lsp/lsp-legacy-alias.test.ts new file mode 100644 index 000000000..c1d4d99ec --- /dev/null +++ b/packages/pi-coding-agent/src/core/lsp/lsp-legacy-alias.test.ts @@ -0,0 +1,70 @@ +// GSD2 — Regression test for LSP legacy server key aliases +// Copyright (c) 2026 Jeremy McSpadden + +/** + * When a default server key is renamed (e.g., kotlin-language-server → kotlin-lsp), + * user overrides referencing the old key must still merge correctly via LEGACY_ALIASES. + * + * This test exercises the merge path through loadConfig() with a temp project + * containing an lsp.json that uses the legacy key. + */ + +import { describe, it, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import * as os from "node:os"; +import { loadConfig } from "./config.js"; + +describe("LSP legacy server key aliases", () => { + let tmpDir: string; + + beforeEach(() => { + tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lsp-alias-test-")); + }); + + afterEach(() => { + fs.rmSync(tmpDir, { recursive: true, force: true }); + }); + + it("merges user override with legacy key 'kotlin-language-server' into 'kotlin-lsp'", () => { + // Write an lsp.json that uses the old key name with a command that exists (node) + // so resolveCommand doesn't filter it out. + const overrideConfig = { + servers: { + "kotlin-language-server": { + command: "node", + }, + }, + }; + fs.writeFileSync( + path.join(tmpDir, "lsp.json"), + JSON.stringify(overrideConfig), + ); + + // Also add root markers so the server is detected + fs.writeFileSync(path.join(tmpDir, "build.gradle.kts"), ""); + + const config = loadConfig(tmpDir); + + // The merged config should have kotlin-lsp (new key) with the user's command override + const kotlinServer = config.servers["kotlin-lsp"]; + assert.ok(kotlinServer, "kotlin-lsp should exist in merged config"); + assert.equal( + kotlinServer.command, + "node", + "command should be overridden from user config via legacy alias", + ); + assert.ok( + kotlinServer.fileTypes.includes(".kt"), + "fileTypes should be inherited from defaults", + ); + + // The old key should NOT appear as a separate entry + assert.equal( + config.servers["kotlin-language-server"], + undefined, + "legacy key should not appear as separate server", + ); + }); +}); diff --git a/packages/pi-coding-agent/src/core/lsp/lspmux.ts b/packages/pi-coding-agent/src/core/lsp/lspmux.ts index 05ef13b38..6e01d7807 100644 --- a/packages/pi-coding-agent/src/core/lsp/lspmux.ts +++ b/packages/pi-coding-agent/src/core/lsp/lspmux.ts @@ -90,6 +90,9 @@ async function checkServerRunning(binaryPath: string): Promise { try { const proc = spawn(binaryPath, ["status"], { stdio: ["ignore", "pipe", "pipe"], + // On Windows, the binary may be a .cmd wrapper requiring shell + // resolution to avoid ENOENT/EINVAL (#2854). + shell: process.platform === "win32", }); const exited = await Promise.race([ diff --git a/packages/pi-coding-agent/src/core/messages.test.ts b/packages/pi-coding-agent/src/core/messages.test.ts new file mode 100644 index 000000000..6741da93c --- /dev/null +++ b/packages/pi-coding-agent/src/core/messages.test.ts @@ -0,0 +1,114 @@ +/** + * messages.test.ts — Tests for convertToLlm custom message handling. + * + * Reproduction test for #3026: background job completion notifications + * delivered as custom messages must be clearly distinguishable from + * user-typed input when converted to LLM messages. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { convertToLlm, type CustomMessage } from "./messages.js"; + +/** Extract the first content block from a message, asserting array content. */ +function firstTextBlock(msg: ReturnType[number]) { + const { content } = msg; + assert.ok(Array.isArray(content), "Expected content to be an array"); + const block = content[0]; + assert.ok(typeof block === "object" && block !== null, "Expected first block to be an object"); + return block; +} + +test("convertToLlm wraps custom messages with system notification prefix", () => { + const customMsg: CustomMessage = { + role: "custom", + customType: "async_job_result", + content: "**Background job done: bg_abc123** (sleep 2, 2.1s)\n\ndone", + display: true, + timestamp: Date.now(), + }; + + const result = convertToLlm([customMsg]); + assert.equal(result.length, 1); + assert.equal(result[0].role, "user"); + + // The content must include a system notification wrapper so the LLM + // does not confuse it with user input (#3026). + const text = firstTextBlock(result[0]); + assert.equal(text.type, "text"); + assert.ok( + "text" in text && text.text.includes("[system notification"), + "Custom message should be wrapped with system notification marker", + ); +}); + +test("convertToLlm wraps custom messages with array content", () => { + const customMsg: CustomMessage = { + role: "custom", + customType: "bg-shell-status", + content: [{ type: "text", text: "Background processes:\n ✓ bg1 dev-server :3000" }], + display: false, + timestamp: Date.now(), + }; + + const result = convertToLlm([customMsg]); + assert.equal(result.length, 1); + assert.equal(result[0].role, "user"); + + const text = firstTextBlock(result[0]); + assert.equal(text.type, "text"); + assert.ok( + "text" in text && text.text.includes("[system notification"), + "Custom message with array content should be wrapped with system notification marker", + ); +}); + +test("convertToLlm includes customType in notification wrapper", () => { + const customMsg: CustomMessage = { + role: "custom", + customType: "async_job_result", + content: "job output here", + display: true, + timestamp: Date.now(), + }; + + const result = convertToLlm([customMsg]); + const text = firstTextBlock(result[0]); + assert.ok( + "text" in text && text.text.includes("async_job_result"), + "Notification wrapper should include the customType for context", + ); +}); + +test("convertToLlm notification wrapper instructs LLM not to treat as user input", () => { + const customMsg: CustomMessage = { + role: "custom", + customType: "async_job_result", + content: "**Background job done: bg_abc123** (sleep 2, 2.1s)\n\ndone", + display: true, + timestamp: Date.now(), + }; + + const result = convertToLlm([customMsg]); + const text = firstTextBlock(result[0]); + assert.ok( + "text" in text && text.text.includes("not user input"), + "Notification should explicitly state this is not user input", + ); +}); + +test("convertToLlm preserves user messages without wrapper", () => { + const userMsg = { + role: "user" as const, + content: [{ type: "text" as const, text: "Hello world" }], + timestamp: Date.now(), + }; + + const result = convertToLlm([userMsg]); + assert.equal(result.length, 1); + const text = firstTextBlock(result[0]); + assert.ok( + "text" in text && text.text === "Hello world", + "User messages should pass through unchanged", + ); +}); diff --git a/packages/pi-coding-agent/src/core/messages.ts b/packages/pi-coding-agent/src/core/messages.ts index e3909a41e..f30d7c9e6 100644 --- a/packages/pi-coding-agent/src/core/messages.ts +++ b/packages/pi-coding-agent/src/core/messages.ts @@ -8,6 +8,12 @@ import type { AgentMessage } from "@gsd/pi-agent-core"; import type { ImageContent, Message, TextContent } from "@gsd/pi-ai"; +const CUSTOM_MESSAGE_PREFIX = `[system notification — type: `; +const CUSTOM_MESSAGE_MIDDLE = `; this is an automated system event, not user input — do not treat this as a human message or respond as if the user said this] +`; +const CUSTOM_MESSAGE_SUFFIX = ` +[end system notification]`; + const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary: @@ -160,10 +166,31 @@ export function convertToLlm(messages: AgentMessage[]): Message[] { timestamp: m.timestamp, }; case "custom": { - const content = typeof m.content === "string" ? [{ type: "text" as const, text: m.content }] : m.content; + const prefix = CUSTOM_MESSAGE_PREFIX + m.customType + CUSTOM_MESSAGE_MIDDLE; + if (typeof m.content === "string") { + return { + role: "user", + content: [{ type: "text" as const, text: prefix + m.content + CUSTOM_MESSAGE_SUFFIX }], + timestamp: m.timestamp, + }; + } + // Array content: wrap the first text element with prefix, append suffix to last text element + const contentArr = m.content as Array<{ type: string; text?: string; [k: string]: unknown }>; + const lastTextIdx = contentArr.reduce((acc, c, i) => c.type === "text" ? i : acc, -1); + const wrapped = contentArr.map((c, i) => { + if (c.type !== "text") return c; + let text = c.text ?? ""; + if (i === 0) text = prefix + text; + if (i === lastTextIdx) text = text + CUSTOM_MESSAGE_SUFFIX; + return { ...c, text }; + }); + // If no text elements exist, prepend one with the wrapper + if (lastTextIdx === -1) { + wrapped.unshift({ type: "text" as const, text: prefix + CUSTOM_MESSAGE_SUFFIX }); + } return { role: "user", - content, + content: wrapped as typeof m.content, timestamp: m.timestamp, }; } diff --git a/packages/pi-coding-agent/src/core/model-registry.ts b/packages/pi-coding-agent/src/core/model-registry.ts index 42714560c..762e459cc 100644 --- a/packages/pi-coding-agent/src/core/model-registry.ts +++ b/packages/pi-coding-agent/src/core/model-registry.ts @@ -467,6 +467,18 @@ export class ModelRegistry { this.customProviderApiKeys.set(providerName, providerConfig.apiKey); } + // Register custom providers so isProviderRequestReady() can find + // them (#3531). Without this, models.json providers with apiKey + // fail the auth check and are invisible to the fallback resolver. + if (!this.registeredProviders.has(providerName)) { + this.registeredProviders.set(providerName, { + authMode: providerConfig.apiKey ? "apiKey" : "none", + apiKey: providerConfig.apiKey, + baseUrl: providerConfig.baseUrl, + isReady: providerConfig.apiKey ? () => true : undefined, + } as any); + } + for (const modelDef of modelDefs) { const api = modelDef.api || providerConfig.api; if (!api) continue; @@ -742,6 +754,7 @@ export class ModelRegistry { maxTokens: modelDef.maxTokens, headers, compat: modelDef.compat, + providerOptions: modelDef.providerOptions, } as Model); } @@ -917,5 +930,6 @@ export interface ProviderConfigInput { maxTokens: number; headers?: Record; compat?: Model["compat"]; + providerOptions?: Record; }>; } diff --git a/packages/pi-coding-agent/src/core/model-resolver.ts b/packages/pi-coding-agent/src/core/model-resolver.ts index bfe6ee86f..3e3b266f7 100644 --- a/packages/pi-coding-agent/src/core/model-resolver.ts +++ b/packages/pi-coding-agent/src/core/model-resolver.ts @@ -13,7 +13,7 @@ import type { ModelRegistry } from "./model-registry.js"; /** Default model IDs for each known provider */ const defaultModelPerProvider: Record = { "amazon-bedrock": "us.anthropic.claude-opus-4-6-v1", - anthropic: "claude-opus-4-6[1m]", + anthropic: "claude-opus-4-6", "anthropic-vertex": "claude-sonnet-4-6", openai: "gpt-5.4", "azure-openai-responses": "gpt-5.2", @@ -24,7 +24,7 @@ const defaultModelPerProvider: Record = { "google-vertex": "gemini-3-pro-preview", "github-copilot": "gpt-4o", openrouter: "openai/gpt-5.1-codex", - "vercel-ai-gateway": "anthropic/claude-opus-4-6[1m]", + "vercel-ai-gateway": "anthropic/claude-opus-4-6", xai: "grok-4-fast-non-reasoning", groq: "openai/gpt-oss-120b", cerebras: "zai-glm-4.6", @@ -37,6 +37,7 @@ const defaultModelPerProvider: Record = { "opencode-go": "kimi-k2.5", "kimi-coding": "kimi-k2-thinking", "alibaba-coding-plan": "qwen3.5-plus", + ollama: "llama3.1:8b", "ollama-cloud": "qwen3:32b", }; @@ -506,7 +507,7 @@ export async function findInitialModel(options: { const found = modelRegistry.find(defaultProvider, defaultModelId); if (found) { // Check if the provider's recommended default is a higher-capability variant - // of the saved model (e.g. saved "claude-opus-4-6" vs recommended "claude-opus-4-6[1m]"). + // of the saved model (e.g. saved "claude-opus-4-6" vs recommended "claude-opus-4-6-extended"). // If so, prefer the recommended variant to avoid using a smaller context window (#1125). const recommendedId = defaultModelPerProvider[defaultProvider as KnownProvider]; if (recommendedId && recommendedId !== defaultModelId && recommendedId.startsWith(defaultModelId)) { diff --git a/packages/pi-coding-agent/src/core/resolve-config-value.test.ts b/packages/pi-coding-agent/src/core/resolve-config-value.test.ts index 9e086d5fc..48a0f8f0e 100644 --- a/packages/pi-coding-agent/src/core/resolve-config-value.test.ts +++ b/packages/pi-coding-agent/src/core/resolve-config-value.test.ts @@ -1,9 +1,11 @@ -import { describe, it, beforeEach } from "node:test"; +import { describe, it, beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; import { resolveConfigValue, clearConfigValueCache, SAFE_COMMAND_PREFIXES, + setAllowedCommandPrefixes, + getAllowedCommandPrefixes, } from "./resolve-config-value.js"; beforeEach(() => { @@ -183,3 +185,111 @@ describe("resolveConfigValue — caching", () => { assert.equal(stderrChunks.length, 2); }); }); + +describe("REGRESSION #666: non-default credential tool blocked with no override", () => { + afterEach(() => { + setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES); + clearConfigValueCache(); + }); + + it("sops is blocked by default, then unblocked by setAllowedCommandPrefixes", (t) => { + const stderrChunks: string[] = []; + const originalWrite = process.stderr.write.bind(process.stderr); + process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => { + stderrChunks.push(chunk.toString()); + return true; + }; + t.after(() => { + process.stderr.write = originalWrite; + }); + + // Bug: sops is not in SAFE_COMMAND_PREFIXES, so it's blocked + const result = resolveConfigValue("!sops decrypt --output-type json secrets.enc.json"); + assert.equal(result, undefined, "sops is blocked by the hardcoded allowlist"); + assert.ok( + stderrChunks.some((line) => line.includes('Blocked disallowed command: "sops"')), + "should log a block message for sops", + ); + + stderrChunks.length = 0; + clearConfigValueCache(); + + // Fix: override the allowlist to include sops + setAllowedCommandPrefixes([...SAFE_COMMAND_PREFIXES, "sops"]); + resolveConfigValue("!sops decrypt --output-type json secrets.enc.json"); + + const blockedAfterOverride = stderrChunks.some((line) => + line.includes("Blocked disallowed command"), + ); + assert.equal(blockedAfterOverride, false, "sops must not be blocked after override"); + }); +}); + +describe("setAllowedCommandPrefixes — user override", () => { + afterEach(() => { + setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES); + clearConfigValueCache(); + }); + + it("overrides built-in prefixes with custom list", () => { + setAllowedCommandPrefixes(["sops", "doppler"]); + assert.deepEqual([...getAllowedCommandPrefixes()], ["sops", "doppler"]); + }); + + it("custom prefix is allowed through to execution", (t) => { + const stderrChunks: string[] = []; + const originalWrite = process.stderr.write.bind(process.stderr); + process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => { + stderrChunks.push(chunk.toString()); + return true; + }; + t.after(() => { + process.stderr.write = originalWrite; + }); + + setAllowedCommandPrefixes(["mycli"]); + resolveConfigValue("!mycli get-secret"); + const blocked = stderrChunks.some((line) => line.includes("Blocked disallowed command")); + assert.equal(blocked, false, "mycli should not be blocked when in the custom allowlist"); + }); + + it("previously-allowed prefix is blocked after override", (t) => { + const stderrChunks: string[] = []; + const originalWrite = process.stderr.write.bind(process.stderr); + process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => { + stderrChunks.push(chunk.toString()); + return true; + }; + t.after(() => { + process.stderr.write = originalWrite; + }); + + setAllowedCommandPrefixes(["sops"]); + const result = resolveConfigValue("!pass show secret"); + assert.equal(result, undefined); + const blocked = stderrChunks.some((line) => line.includes("Blocked disallowed command")); + assert.equal(blocked, true, "pass should be blocked when not in the custom allowlist"); + }); + + it("clears cache when overriding prefixes", (t) => { + const stderrChunks: string[] = []; + const originalWrite = process.stderr.write.bind(process.stderr); + process.stderr.write = (chunk: string | Uint8Array, ...args: unknown[]) => { + stderrChunks.push(chunk.toString()); + return true; + }; + t.after(() => { + process.stderr.write = originalWrite; + }); + + resolveConfigValue("!mycli get-secret"); + assert.ok(stderrChunks.some((line) => line.includes("Blocked"))); + + stderrChunks.length = 0; + + setAllowedCommandPrefixes(["mycli"]); + resolveConfigValue("!mycli get-secret"); + const blocked = stderrChunks.some((line) => line.includes("Blocked")); + assert.equal(blocked, false, "Should re-evaluate after allowlist change"); + }); +}); diff --git a/packages/pi-coding-agent/src/core/resolve-config-value.ts b/packages/pi-coding-agent/src/core/resolve-config-value.ts index e12c4c2ae..9b72ca65f 100644 --- a/packages/pi-coding-agent/src/core/resolve-config-value.ts +++ b/packages/pi-coding-agent/src/core/resolve-config-value.ts @@ -24,6 +24,30 @@ export const SAFE_COMMAND_PREFIXES = [ "lpass", ]; +/** + * Active command prefix allowlist. Defaults to SAFE_COMMAND_PREFIXES but can be + * overridden via setAllowedCommandPrefixes() (called from settings or env var). + */ +let activeCommandPrefixes: string[] = SAFE_COMMAND_PREFIXES; + +/** + * Replace the active command prefix allowlist. + * Called during initialization when the user has configured `allowedCommandPrefixes` + * in global settings.json or via the GSD_ALLOWED_COMMAND_PREFIXES env var. + */ +export function setAllowedCommandPrefixes(prefixes: string[]): void { + if (prefixes.length === 0) { + process.stderr.write("[resolve-config-value] Warning: empty command prefix allowlist — all !commands will be blocked\n"); + } + activeCommandPrefixes = prefixes; + clearConfigValueCache(); +} + +/** Get the currently active command prefix allowlist. */ +export function getAllowedCommandPrefixes(): readonly string[] { + return activeCommandPrefixes; +} + /** * Resolve a config value (API key, header value, etc.) to an actual value. * - If starts with "!", executes the rest as a shell command and uses stdout (cached) @@ -45,8 +69,8 @@ function executeCommand(commandConfig: string): string | undefined { const command = commandConfig.slice(1); const tokens = command.split(/\s+/).filter(Boolean); const firstToken = tokens[0]; - if (!SAFE_COMMAND_PREFIXES.includes(firstToken)) { - process.stderr.write(`[resolve-config-value] Blocked disallowed command: "${firstToken}". Allowed: ${SAFE_COMMAND_PREFIXES.join(", ")}\n`); + if (!activeCommandPrefixes.includes(firstToken)) { + process.stderr.write(`[resolve-config-value] Blocked disallowed command: "${firstToken}". Allowed: ${activeCommandPrefixes.join(", ")}\n`); commandResultCache.set(commandConfig, undefined); return undefined; } diff --git a/packages/pi-coding-agent/src/core/resource-loader-cache-reset.test.ts b/packages/pi-coding-agent/src/core/resource-loader-cache-reset.test.ts new file mode 100644 index 000000000..f59c557a7 --- /dev/null +++ b/packages/pi-coding-agent/src/core/resource-loader-cache-reset.test.ts @@ -0,0 +1,42 @@ +// GSD-2 — Regression test for #3616: reload() must reset jiti extension loader cache +// Copyright (c) 2026 Jeremy McSpadden + +import test, { describe } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const source = readFileSync( + join(process.cwd(), "packages/pi-coding-agent/src/core/resource-loader.ts"), + "utf-8", +); + +describe("#3616 — reload() must invalidate jiti module cache", () => { + test("resource-loader imports resetExtensionLoaderCache from loader.js", () => { + assert.ok( + source.includes("resetExtensionLoaderCache"), + "resource-loader.ts should import resetExtensionLoaderCache", + ); + assert.ok( + source.includes('from "./extensions/loader.js"'), + "resetExtensionLoaderCache should be imported from extensions/loader.js", + ); + }); + + test("reload() calls resetExtensionLoaderCache before loadExtensions", () => { + const reloadStart = source.indexOf("async reload(): Promise"); + assert.ok(reloadStart >= 0, "should find reload() method"); + const reloadBody = source.slice(reloadStart, reloadStart + 4000); + + const resetIdx = reloadBody.indexOf("resetExtensionLoaderCache()"); + assert.ok(resetIdx >= 0, "reload() should call resetExtensionLoaderCache()"); + + const loadIdx = reloadBody.indexOf("loadExtensions("); + assert.ok(loadIdx >= 0, "reload() should call loadExtensions"); + + assert.ok( + resetIdx < loadIdx, + "resetExtensionLoaderCache() must be called BEFORE loadExtensions to ensure fresh modules", + ); + }); +}); diff --git a/packages/pi-coding-agent/src/core/resource-loader.ts b/packages/pi-coding-agent/src/core/resource-loader.ts index 6eb040829..34ab7565e 100644 --- a/packages/pi-coding-agent/src/core/resource-loader.ts +++ b/packages/pi-coding-agent/src/core/resource-loader.ts @@ -1,6 +1,6 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { homedir } from "node:os"; -import { basename, dirname, join, resolve, sep } from "node:path"; +import { basename, dirname, join, relative, resolve, sep } from "node:path"; import chalk from "chalk"; import { CONFIG_DIR_NAME, getAgentDir } from "../config.js"; import { loadThemeFromPath, type Theme } from "../modes/interactive/theme/theme.js"; @@ -9,7 +9,7 @@ import type { ResourceCollision, ResourceDiagnostic } from "./diagnostics.js"; export type { ResourceCollision, ResourceDiagnostic } from "./diagnostics.js"; import { createEventBus, type EventBus } from "./event-bus.js"; -import { createExtensionRuntime, loadExtensionFromFactory, loadExtensions } from "./extensions/loader.js"; +import { createExtensionRuntime, loadExtensionFromFactory, loadExtensions, resetExtensionLoaderCache } from "./extensions/loader.js"; import type { Extension, ExtensionFactory, ExtensionRuntime, LoadExtensionsResult } from "./extensions/types.js"; import { DefaultPackageManager, type PathMetadata } from "./package-manager.js"; import type { PromptTemplate } from "./prompt-templates.js"; @@ -121,6 +121,7 @@ export interface DefaultResourceLoaderOptions { additionalPromptTemplatePaths?: string[]; additionalThemePaths?: string[]; extensionFactories?: ExtensionFactory[]; + bundledExtensionKeys?: Set; noExtensions?: boolean; noSkills?: boolean; noPromptTemplates?: boolean; @@ -129,6 +130,12 @@ export interface DefaultResourceLoaderOptions { appendSystemPrompt?: string; /** Names of bundled extensions (used to identify built-in extensions in conflict detection). */ bundledExtensionNames?: Set; + /** + * Transform extension paths before loading. Receives the merged list of all + * discovered extension paths and returns a (possibly reordered/filtered) list. + * Use this to apply dependency sorting or registry-based filtering. + */ + extensionPathsTransform?: (paths: string[]) => { paths: string[]; diagnostics?: string[] }; extensionsOverride?: (base: LoadExtensionsResult) => LoadExtensionsResult; skillsOverride?: (base: { skills: Skill[]; diagnostics: ResourceDiagnostic[] }) => { skills: Skill[]; @@ -155,6 +162,7 @@ export class DefaultResourceLoader implements ResourceLoader { private settingsManager: SettingsManager; private eventBus: EventBus; private packageManager: DefaultPackageManager; + private bundledExtensionKeys: Set; private additionalExtensionPaths: string[]; private additionalSkillPaths: string[]; private additionalPromptTemplatePaths: string[]; @@ -167,6 +175,7 @@ export class DefaultResourceLoader implements ResourceLoader { private systemPromptSource?: string; private appendSystemPromptSource?: string; private bundledExtensionNames: Set; + private extensionPathsTransform?: (paths: string[]) => { paths: string[]; diagnostics?: string[] }; private extensionsOverride?: (base: LoadExtensionsResult) => LoadExtensionsResult; private skillsOverride?: (base: { skills: Skill[]; diagnostics: ResourceDiagnostic[] }) => { skills: Skill[]; @@ -211,6 +220,7 @@ export class DefaultResourceLoader implements ResourceLoader { agentDir: this.agentDir, settingsManager: this.settingsManager, }); + this.bundledExtensionKeys = options.bundledExtensionKeys ?? new Set(); this.additionalExtensionPaths = options.additionalExtensionPaths ?? []; this.additionalSkillPaths = options.additionalSkillPaths ?? []; this.additionalPromptTemplatePaths = options.additionalPromptTemplatePaths ?? []; @@ -223,6 +233,7 @@ export class DefaultResourceLoader implements ResourceLoader { this.systemPromptSource = options.systemPrompt; this.appendSystemPromptSource = options.appendSystemPrompt; this.bundledExtensionNames = options.bundledExtensionNames ?? new Set(); + this.extensionPathsTransform = options.extensionPathsTransform; this.extensionsOverride = options.extensionsOverride; this.skillsOverride = options.skillsOverride; this.promptsOverride = options.promptsOverride; @@ -309,6 +320,10 @@ export class DefaultResourceLoader implements ResourceLoader { } async reload(): Promise { + // Invalidate the shared jiti module cache so updated extension code + // on disk is re-compiled instead of served from the stale cache (#3616). + resetExtensionLoaderCache(); + const resolvedPaths = await this.packageManager.resolve(); const cliExtensionPaths = await this.packageManager.resolveExtensionSources(this.additionalExtensionPaths, { temporary: true, @@ -378,10 +393,21 @@ export class DefaultResourceLoader implements ResourceLoader { const cliEnabledPrompts = getEnabledPaths(cliExtensionPaths.prompts); const cliEnabledThemes = getEnabledPaths(cliExtensionPaths.themes); - const extensionPaths = this.noExtensions + let extensionPaths = this.noExtensions ? cliEnabledExtensions : this.mergePaths(cliEnabledExtensions, enabledExtensions); + // Apply path transform (dependency sorting, registry filtering) if provided + if (this.extensionPathsTransform) { + const transformed = this.extensionPathsTransform(extensionPaths); + extensionPaths = transformed.paths; + if (transformed.diagnostics?.length) { + for (const msg of transformed.diagnostics) { + process.stderr.write(`[extensions] ${msg}\n`); + } + } + } + const extensionsResult = await loadExtensions(extensionPaths, this.cwd, this.eventBus); const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime); extensionsResult.extensions.push(...inlineExtensions.extensions); @@ -808,66 +834,96 @@ export class DefaultResourceLoader implements ResourceLoader { } private detectExtensionConflicts(extensions: Extension[]): Array<{ path: string; message: string }> { - const conflicts: Array<{ path: string; message: string }> = []; + return detectExtensionConflicts(extensions, this.bundledExtensionKeys, join(this.agentDir, "extensions")); + } +} - // Track which extension registered each tool, command, and flag - const toolOwners = new Map(); - const commandOwners = new Map(); - const flagOwners = new Map(); +/** + * Extract the extension directory name (key) from a full extension path. + * Given extensionsDir `/home/user/.gsd/agent/extensions` and + * ownerPath `/home/user/.gsd/agent/extensions/mcp-client/index.js`, + * returns `"mcp-client"`. Returns `undefined` when the path is not + * under extensionsDir. + */ +export function extractExtensionKey(ownerPath: string, extensionsDir: string): string | undefined { + const normalizedDir = resolve(extensionsDir); + const normalizedPath = resolve(ownerPath); + const prefix = normalizedDir.endsWith(sep) ? normalizedDir : `${normalizedDir}${sep}`; + if (!normalizedPath.startsWith(prefix)) { + return undefined; + } + const relPath = relative(normalizedDir, normalizedPath); + const firstSegment = relPath.split(/[\\/]/)[0]; + return firstSegment?.replace(/\.(?:ts|js)$/, "") || undefined; +} - for (const ext of extensions) { - // Check tools - for (const toolName of ext.tools.keys()) { - const existingOwner = toolOwners.get(toolName); - if (existingOwner && existingOwner !== ext.path) { - // Determine if the existing owner is a bundled extension by checking - // its name against the canonical bundled extensions list - const ownerName = this.getExtensionNameFromPath(existingOwner); - const isBuiltIn = this.bundledExtensionNames.has(ownerName); - const hint = isBuiltIn - ? ` (built-in tool supersedes — consider removing ${ext.path})` - : ""; - conflicts.push({ - path: ext.path, - message: `Tool "${toolName}" conflicts with ${existingOwner}${hint}`, - }); - } else { - toolOwners.set(toolName, ext.path); - } - } +/** + * Detect tool/command/flag name collisions across loaded extensions. + * + * When the first-registered owner of a name is a bundled extension + * (its key appears in `bundledExtensionKeys`), the conflict message + * includes a "supersedes" hint so downstream display can downgrade the + * severity from "Extension load error" to "Extension conflict". + */ +export function detectExtensionConflicts( + extensions: Extension[], + bundledExtensionKeys: Set, + extensionsDir: string, +): Array<{ path: string; message: string }> { + const conflicts: Array<{ path: string; message: string }> = []; - // Check commands - for (const commandName of ext.commands.keys()) { - const existingOwner = commandOwners.get(commandName); - if (existingOwner && existingOwner !== ext.path) { - const ownerName = this.getExtensionNameFromPath(existingOwner); - const isBuiltIn = this.bundledExtensionNames.has(ownerName); - const hint = isBuiltIn - ? ` (built-in command supersedes — consider removing ${ext.path})` - : ""; - conflicts.push({ - path: ext.path, - message: `Command "/${commandName}" conflicts with ${existingOwner}${hint}`, - }); - } else { - commandOwners.set(commandName, ext.path); - } - } + const toolOwners = new Map(); + const commandOwners = new Map(); + const flagOwners = new Map(); - // Check flags - for (const flagName of ext.flags.keys()) { - const existingOwner = flagOwners.get(flagName); - if (existingOwner && existingOwner !== ext.path) { - conflicts.push({ - path: ext.path, - message: `Flag "--${flagName}" conflicts with ${existingOwner}`, - }); - } else { - flagOwners.set(flagName, ext.path); - } + const isBundled = (ownerPath: string): boolean => { + const key = extractExtensionKey(ownerPath, extensionsDir); + return key !== undefined && bundledExtensionKeys.has(key); + }; + + for (const ext of extensions) { + for (const toolName of ext.tools.keys()) { + const existingOwner = toolOwners.get(toolName); + if (existingOwner && existingOwner !== ext.path) { + const hint = isBundled(existingOwner) + ? ` (built-in tool supersedes — consider removing ${ext.path})` + : ""; + conflicts.push({ + path: ext.path, + message: `Tool "${toolName}" conflicts with ${existingOwner}${hint}`, + }); + } else { + toolOwners.set(toolName, ext.path); } } - return conflicts; + for (const commandName of ext.commands.keys()) { + const existingOwner = commandOwners.get(commandName); + if (existingOwner && existingOwner !== ext.path) { + const hint = isBundled(existingOwner) + ? ` (built-in command supersedes — consider removing ${ext.path})` + : ""; + conflicts.push({ + path: ext.path, + message: `Command "/${commandName}" conflicts with ${existingOwner}${hint}`, + }); + } else { + commandOwners.set(commandName, ext.path); + } + } + + for (const flagName of ext.flags.keys()) { + const existingOwner = flagOwners.get(flagName); + if (existingOwner && existingOwner !== ext.path) { + conflicts.push({ + path: ext.path, + message: `Flag "--${flagName}" conflicts with ${existingOwner}`, + }); + } else { + flagOwners.set(flagName, ext.path); + } + } } + + return conflicts; } diff --git a/packages/pi-coding-agent/src/core/retry-handler.test.ts b/packages/pi-coding-agent/src/core/retry-handler.test.ts new file mode 100644 index 000000000..5cd324401 --- /dev/null +++ b/packages/pi-coding-agent/src/core/retry-handler.test.ts @@ -0,0 +1,431 @@ +/** + * RetryHandler tests — long-context entitlement 429 error handling (#2803) + * + * Verifies that "Extra usage is required for long context requests" errors + * are classified as quota_exhausted (not rate_limit) and trigger a model + * downgrade from [1m] to base when no cross-provider fallback exists. + */ + +import { describe, it, beforeEach, mock, type Mock } from "node:test"; +import assert from "node:assert/strict"; +import { RetryHandler, type RetryHandlerDeps } from "./retry-handler.js"; +import type { Api, AssistantMessage, Model } from "@gsd/pi-ai"; +import type { FallbackResolver } from "./fallback-resolver.js"; +import type { ModelRegistry } from "./model-registry.js"; +import type { SettingsManager } from "./settings-manager.js"; + +// ─── Helpers ──────────────────────────────────────────────────────────────── + +function createMockModel(provider: string, id: string): Model { + return { + id, + name: id, + api: "anthropic" as Api, + provider, + baseUrl: "https://api.anthropic.com", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 1_000_000, + maxTokens: 16384, + } as Model; +} + +function errorMessage(msg: string): AssistantMessage { + return { + role: "assistant", + content: [], + api: "anthropic-messages", + provider: "anthropic", + model: "claude-opus-4-6[1m]", + usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, + stopReason: "error", + errorMessage: msg, + timestamp: Date.now(), + } as AssistantMessage; +} + +interface MockDeps { + deps: RetryHandlerDeps; + emittedEvents: Array>; + continueFn: Mock<() => Promise>; + onModelChangeFn: Mock<(model: Model) => void>; + markUsageLimitReached: Mock<(...args: any[]) => boolean>; + findFallback: Mock<(...args: any[]) => Promise>; + findModel: Mock<(provider: string, modelId: string) => Model | undefined>; +} + +function createMockDeps(overrides?: { + model?: Model; + retryEnabled?: boolean; + markUsageLimitReachedResult?: boolean; + fallbackResult?: any; + findModelResult?: (provider: string, modelId: string) => Model | undefined; + retrySettings?: { + maxRetries?: number; + baseDelayMs?: number; + maxDelayMs?: number; + }; +}): MockDeps { + const model = overrides?.model ?? createMockModel("anthropic", "claude-opus-4-6[1m]"); + const emittedEvents: Array> = []; + const continueFn = mock.fn(async () => {}); + const onModelChangeFn = mock.fn((_model: Model) => {}); + const markUsageLimitReached = mock.fn( + () => overrides?.markUsageLimitReachedResult ?? false, + ); + const findFallback = mock.fn(async () => overrides?.fallbackResult ?? null); + const findModel = mock.fn( + overrides?.findModelResult ?? ((_provider: string, _modelId: string) => undefined), + ); + + const messages: Array<{ role: string } & Record> = []; + + const deps: RetryHandlerDeps = { + agent: { + continue: continueFn, + state: { messages }, + setModel: mock.fn(), + replaceMessages: mock.fn((newMessages: any[]) => { + messages.length = 0; + messages.push(...newMessages); + }), + } as any, + settingsManager: { + getRetryEnabled: () => overrides?.retryEnabled ?? true, + getRetrySettings: () => ({ + enabled: overrides?.retryEnabled ?? true, + maxRetries: overrides?.retrySettings?.maxRetries ?? 5, + baseDelayMs: overrides?.retrySettings?.baseDelayMs ?? 1000, + maxDelayMs: overrides?.retrySettings?.maxDelayMs ?? 30000, + }), + } as unknown as SettingsManager, + modelRegistry: { + authStorage: { + markUsageLimitReached, + }, + find: findModel, + } as unknown as ModelRegistry, + fallbackResolver: { + findFallback, + } as unknown as FallbackResolver, + getModel: () => model, + getSessionId: () => "test-session", + emit: (event: any) => emittedEvents.push(event), + onModelChange: onModelChangeFn, + }; + + return { deps, emittedEvents, continueFn, onModelChangeFn, markUsageLimitReached, findFallback, findModel }; +} + +// ─── _classifyErrorType (tested via handleRetryableError behavior) ────────── + +describe("RetryHandler — long-context entitlement 429 (#2803)", () => { + + describe("error classification", () => { + it("classifies 'Extra usage is required for long context requests' as quota_exhausted, not rate_limit", async () => { + // When the error is classified as quota_exhausted AND no alternate credentials + // AND no fallback, the handler should emit fallback_chain_exhausted and stop. + // If misclassified as rate_limit, it would enter the backoff loop instead. + const { deps, emittedEvents, findModel } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6[1m]"), + markUsageLimitReachedResult: false, // no alternate credentials + fallbackResult: null, // no cross-provider fallback + findModelResult: () => undefined, // no base model either + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage( + '429 {"type":"error","error":{"type":"rate_limit_error","message":"Extra usage is required for long context requests."}}' + ); + + const result = await handler.handleRetryableError(msg); + + // Should NOT retry (would be true if misclassified as rate_limit entering backoff) + assert.equal(result, false); + + // Should emit fallback_chain_exhausted (quota_exhausted path), NOT auto_retry_start (backoff path) + const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted"); + assert.ok(chainExhausted, "Expected fallback_chain_exhausted event for entitlement error"); + + const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start"); + assert.equal(retryStart, undefined, "Should NOT emit auto_retry_start for entitlement error"); + }); + + it("still classifies regular 429 rate limits as rate_limit", async () => { + // A normal "rate limit" 429 should still be classified as rate_limit + const { deps, emittedEvents } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6"), + markUsageLimitReachedResult: false, + fallbackResult: null, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("429 Too Many Requests"); + + const result = await handler.handleRetryableError(msg); + + // Should enter the backoff loop (rate_limit path, not quota_exhausted) + assert.equal(result, true); + + const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start"); + assert.ok(retryStart, "Regular 429 should enter backoff retry"); + }); + }); + + describe("long-context model downgrade", () => { + it("downgrades from [1m] to base model when entitlement error and no fallback", async () => { + const baseModel = createMockModel("anthropic", "claude-opus-4-6"); + const { deps, emittedEvents, onModelChangeFn, continueFn } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6[1m]"), + markUsageLimitReachedResult: false, + fallbackResult: null, + findModelResult: (provider: string, modelId: string) => { + if (provider === "anthropic" && modelId === "claude-opus-4-6") return baseModel; + return undefined; + }, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("Extra usage is required for long context requests."); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, true, "Should retry after downgrade"); + + // Should have called setModel with the base model + const setModelCalls = (deps.agent.setModel as any).mock.calls; + assert.equal(setModelCalls.length, 1); + assert.equal(setModelCalls[0].arguments[0].id, "claude-opus-4-6"); + + // Should have notified about model change + assert.equal(onModelChangeFn.mock.calls.length, 1); + + // Should emit a fallback_provider_switch event indicating downgrade + const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch"); + assert.ok(switchEvent, "Expected fallback_provider_switch event for downgrade"); + assert.ok(switchEvent!.reason.includes("long context downgrade"), `reason should mention downgrade: ${switchEvent!.reason}`); + }); + + it("emits fallback_chain_exhausted when base model is also unavailable", async () => { + const { deps, emittedEvents } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6[1m]"), + markUsageLimitReachedResult: false, + fallbackResult: null, + findModelResult: () => undefined, // base model not found + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("Extra usage is required for long context requests."); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, false); + const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted"); + assert.ok(chainExhausted, "Expected fallback_chain_exhausted when base model unavailable"); + }); + + it("does not attempt downgrade for non-[1m] models", async () => { + // When a regular model (no [1m] suffix) gets a quota_exhausted error + // with no fallback, it should just stop — no downgrade attempt. + const { deps, emittedEvents } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6"), + markUsageLimitReachedResult: false, + fallbackResult: null, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("Extra usage is required for long context requests."); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, false); + const chainExhausted = emittedEvents.find((e) => e.type === "fallback_chain_exhausted"); + assert.ok(chainExhausted); + + // No downgrade switch should occur + const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch"); + assert.equal(switchEvent, undefined, "Should not switch for non-[1m] models"); + }); + }); + + describe("retry cancellation", () => { + it("cancels queued immediate continue callbacks when retry is aborted", async () => { + const { deps, emittedEvents, continueFn } = createMockDeps({ + markUsageLimitReachedResult: true, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("429 Too Many Requests"); + + const result = await handler.handleRetryableError(msg); + assert.equal(result, true, "retry should be initiated"); + + handler.abortRetry(); + await new Promise((resolve) => setTimeout(resolve, 10)); + + assert.equal(continueFn.mock.calls.length, 0, "cancelled retry must not continue after explicit abort"); + const endEvents = emittedEvents.filter((e) => e.type === "auto_retry_end"); + assert.equal(endEvents.length, 1, "retry cancellation should emit a single auto_retry_end event"); + assert.equal(endEvents[0]?.finalError, "Retry cancelled"); + }); + }); + + describe("isRetryableError", () => { + it("considers long-context entitlement error as retryable", () => { + const { deps } = createMockDeps(); + const handler = new RetryHandler(deps); + const msg = errorMessage("Extra usage is required for long context requests."); + assert.equal(handler.isRetryableError(msg), true); + }); + + it("does NOT consider credential cooldown error as retryable (#3429)", () => { + // The credential cooldown message from getApiKey() must not re-enter + // the retry handler. Re-entry creates cascading empty error entries + // in the session file that break resume. + const { deps } = createMockDeps(); + const handler = new RetryHandler(deps); + const msg = errorMessage( + 'All credentials for "anthropic" are in a cooldown window. ' + + 'Please wait a moment and try again, or switch to a different provider.', + ); + assert.equal(handler.isRetryableError(msg), false); + }); + }); + + describe("third-party block claude-code fallback (#3772)", () => { + it("switches to claude-code provider when current provider is anthropic", async () => { + const ccModel = createMockModel("claude-code", "claude-opus-4-6"); + const { deps, emittedEvents, onModelChangeFn } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6"), + findModelResult: (provider: string, modelId: string) => { + if (provider === "claude-code" && modelId === "claude-opus-4-6") return ccModel; + return undefined; + }, + }); + deps.isClaudeCodeReady = () => true; + + const handler = new RetryHandler(deps); + const msg = errorMessage("third-party apps cannot draw from extra usage"); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, true, "should retry via claude-code fallback"); + const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch"); + assert.ok(switchEvent, "Expected fallback_provider_switch event"); + assert.ok(switchEvent!.to.startsWith("claude-code/"), "Should switch to claude-code provider"); + }); + + it("switches to claude-code on 'out of extra usage' error (#3772)", async () => { + const ccModel = createMockModel("claude-code", "claude-opus-4-6"); + const { deps, emittedEvents } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6"), + findModelResult: (provider: string, modelId: string) => { + if (provider === "claude-code" && modelId === "claude-opus-4-6") return ccModel; + return undefined; + }, + }); + deps.isClaudeCodeReady = () => true; + + const handler = new RetryHandler(deps); + const msg = errorMessage("You're out of extra usage. Add more at claude.ai/settings/usage and keep going."); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, true, "should retry via claude-code fallback"); + const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch"); + assert.ok(switchEvent, "Expected fallback_provider_switch event"); + assert.ok(switchEvent!.to.startsWith("claude-code/"), "Should switch to claude-code provider"); + }); + + it("does NOT switch to claude-code when current provider is not anthropic", async () => { + const ccModel = createMockModel("claude-code", "gpt-4o"); + const { deps, emittedEvents } = createMockDeps({ + model: createMockModel("openai", "gpt-4o"), + findModelResult: (provider: string, modelId: string) => { + if (provider === "claude-code" && modelId === "gpt-4o") return ccModel; + return undefined; + }, + }); + deps.isClaudeCodeReady = () => true; + + const handler = new RetryHandler(deps); + const msg = errorMessage("third-party apps are not supported for this plan"); + + const result = await handler.handleRetryableError(msg); + + // Should NOT have triggered the claude-code fallback + const switchEvent = emittedEvents.find( + (e) => e.type === "fallback_provider_switch" && e.to?.startsWith("claude-code/"), + ); + assert.equal(switchEvent, undefined, "Should NOT switch non-anthropic provider to claude-code"); + }); + }); + + describe("quota_exhausted credential backoff (#3430)", () => { + it("does NOT call markUsageLimitReached for quota_exhausted errors", async () => { + // "Extra usage is required" is an account-level billing gate. + // Backing off the credential for 30 minutes blocks all provider + // requests and has no effect on the billing condition. + const { deps, markUsageLimitReached } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6[1m]"), + markUsageLimitReachedResult: false, + fallbackResult: null, + findModelResult: () => undefined, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage( + '429 {"type":"error","error":{"type":"rate_limit_error","message":"Extra usage is required for long context requests."}}', + ); + + await handler.handleRetryableError(msg); + + assert.equal( + markUsageLimitReached.mock.calls.length, + 0, + "markUsageLimitReached must NOT be called for quota_exhausted errors", + ); + }); + + it("still calls markUsageLimitReached for regular rate_limit errors", async () => { + const { deps, markUsageLimitReached } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6"), + markUsageLimitReachedResult: false, + fallbackResult: null, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("429 Too Many Requests"); + + await handler.handleRetryableError(msg); + + assert.equal( + markUsageLimitReached.mock.calls.length, + 1, + "markUsageLimitReached should be called for rate_limit errors", + ); + }); + + it("still tries cross-provider fallback for quota_exhausted without credential backoff", async () => { + const fallbackModel = createMockModel("openai", "gpt-4o"); + const { deps, markUsageLimitReached, continueFn } = createMockDeps({ + model: createMockModel("anthropic", "claude-opus-4-6[1m]"), + markUsageLimitReachedResult: false, + fallbackResult: { model: fallbackModel, reason: "cross-provider fallback" }, + }); + + const handler = new RetryHandler(deps); + const msg = errorMessage("Extra usage is required for long context requests."); + + const result = await handler.handleRetryableError(msg); + + assert.equal(result, true, "should retry with fallback provider"); + assert.equal( + markUsageLimitReached.mock.calls.length, + 0, + "should NOT back off credentials before trying fallback", + ); + }); + }); +}); diff --git a/packages/pi-coding-agent/src/core/retry-handler.ts b/packages/pi-coding-agent/src/core/retry-handler.ts index 9bdeac8f6..78d12c8ba 100644 --- a/packages/pi-coding-agent/src/core/retry-handler.ts +++ b/packages/pi-coding-agent/src/core/retry-handler.ts @@ -30,6 +30,9 @@ export interface RetryHandlerDeps { emit: (event: AgentSessionEvent) => void; /** Called when the retry handler switches to a fallback model */ onModelChange: (model: Model) => void; + /** Optional: check if the claude-code CLI provider is ready (installed + authed). + * Injected from the app layer to preserve package boundary. */ + isClaudeCodeReady?: () => boolean; } export class RetryHandler { @@ -37,6 +40,8 @@ export class RetryHandler { private _retryAttempt = 0; private _retryPromise: Promise | undefined = undefined; private _retryResolve: (() => void) | undefined = undefined; + private _retryGeneration = 0; + private _continueTimeout: ReturnType | undefined = undefined; constructor(private readonly _deps: RetryHandlerDeps) {} @@ -107,7 +112,11 @@ export class RetryHandler { if (isContextOverflow(message, contextWindow)) return false; const err = message.errorMessage; - return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|temporarily backed off/i.test( + // "temporarily backed off" is intentionally excluded: it is an internally- + // generated error from getApiKey() when credentials are in a backoff window. + // Re-entering the retry handler for that message creates a cascade of empty + // error entries in the session file, breaking resume (#3429). + return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|extra usage is required|(?:out of|no) extra usage|third.party.*draw from extra|third.party.*not.*available/i.test( err, ); } @@ -134,38 +143,54 @@ export class RetryHandler { } // Try credential fallback before counting against retry budget. + const retryGeneration = this._retryGeneration; if (this._deps.getModel() && message.errorMessage) { - const errorType = this._classifyErrorType(message.errorMessage); - const isCredentialError = errorType === "rate_limit" || errorType === "quota_exhausted"; - const hasAlternate = - isCredentialError && - this._deps.modelRegistry.authStorage.markUsageLimitReached( - this._deps.getModel()!.provider, - this._deps.getSessionId(), - { errorType }, - ); - - if (hasAlternate) { - this._removeLastAssistantError(); - - this._deps.emit({ - type: "auto_retry_start", - attempt: this._retryAttempt + 1, - maxAttempts: settings.maxRetries, - delayMs: 0, - errorMessage: `${message.errorMessage} (switching credential)`, - }); - - // Retry immediately with the next credential - don't increment _retryAttempt - setTimeout(() => { - this._deps.agent.continue().catch(() => {}); - }, 0); - - return true; + // Third-party subscription block (#3772): Anthropic blocks third-party apps + // from using Pro/Max subscription quotas. If the claude-code CLI provider is + // available, switch to it immediately — credential rotation won't help. + if (this._isThirdPartyBlock(message.errorMessage)) { + const switched = this._tryClaudeCodeFallback(message, retryGeneration); + if (switched) return true; + // CLI not available — fall through to standard error handling } - // All credentials are backed off. Try cross-provider fallback before giving up. - if (isCredentialError) { + const errorType = this._classifyErrorType(message.errorMessage); + const isRateLimit = errorType === "rate_limit"; + const isQuotaError = errorType === "quota_exhausted"; + + // Credential rotation — only for transient rate limits (#3430). + // Quota errors ("Extra usage is required") are account-level billing + // gates; rotating to another credential on the same account won't help + // and the 30-minute backoff blocks all provider requests needlessly. + if (isRateLimit) { + const hasAlternate = + this._deps.modelRegistry.authStorage.markUsageLimitReached( + this._deps.getModel()!.provider, + this._deps.getSessionId(), + { errorType }, + ); + + if (hasAlternate) { + this._removeLastAssistantError(); + + this._deps.emit({ + type: "auto_retry_start", + attempt: this._retryAttempt + 1, + maxAttempts: settings.maxRetries, + delayMs: 0, + errorMessage: `${message.errorMessage} (switching credential)`, + }); + + // Retry immediately with the next credential - don't increment _retryAttempt + this._scheduleContinue(retryGeneration); + + return true; + } + } + + // Cross-provider fallback — for rate limits with all creds backed off, + // or quota errors (which skip credential backoff entirely). + if (isRateLimit || isQuotaError) { const fallbackResult = await this._deps.fallbackResolver.findFallback( this._deps.getModel()!, errorType, @@ -193,15 +218,17 @@ export class RetryHandler { }); // Retry immediately with fallback provider - don't increment _retryAttempt - setTimeout(() => { - this._deps.agent.continue().catch(() => {}); - }, 0); + this._scheduleContinue(retryGeneration); return true; } // No fallback available either - if (errorType === "quota_exhausted") { + if (isQuotaError) { + // Try long-context model downgrade ([1m] → base) before giving up + const downgraded = this._tryLongContextDowngrade(message, retryGeneration); + if (downgraded) return true; + this._deps.emit({ type: "fallback_chain_exhausted", reason: `All providers exhausted for ${this._deps.getModel()!.provider}/${this._deps.getModel()!.id}`, @@ -270,7 +297,12 @@ export class RetryHandler { try { await sleep(delayMs, this._retryAbortController.signal); } catch { - // Aborted during sleep + // Aborted during sleep. If the retry generation already advanced, this + // cancellation was handled externally (e.g. explicit model switch). + if (retryGeneration !== this._retryGeneration) { + this._retryAbortController = undefined; + return false; + } const attempt = this._retryAttempt; this._retryAttempt = 0; this._retryAbortController = undefined; @@ -286,16 +318,36 @@ export class RetryHandler { this._retryAbortController = undefined; // Retry via continue() - use setTimeout to break out of event handler chain - setTimeout(() => { - this._deps.agent.continue().catch(() => {}); - }, 0); + this._scheduleContinue(retryGeneration); return true; } /** Cancel in-progress retry */ abortRetry(): void { - this._retryAbortController?.abort(); + const hadRetry = + this._retryPromise !== undefined + || this._retryAbortController !== undefined + || this._continueTimeout !== undefined; + if (!hadRetry) return; + + const attempt = this._retryAttempt > 0 ? this._retryAttempt : 1; + this._retryGeneration++; + if (this._continueTimeout) { + clearTimeout(this._continueTimeout); + this._continueTimeout = undefined; + } + if (this._retryAbortController) { + this._retryAbortController.abort(); + this._retryAbortController = undefined; + } + this._retryAttempt = 0; + this._deps.emit({ + type: "auto_retry_end", + success: false, + attempt, + finalError: "Retry cancelled", + }); this._resolveRetry(); } @@ -326,6 +378,17 @@ export class RetryHandler { } } + private _scheduleContinue(retryGeneration: number): void { + if (this._continueTimeout) { + clearTimeout(this._continueTimeout); + } + this._continueTimeout = setTimeout(() => { + this._continueTimeout = undefined; + if (retryGeneration !== this._retryGeneration) return; + this._deps.agent.continue().catch(() => {}); + }, 0); + } + private _findLastAssistantInMessages( messages: Array<{ role: string } & Record>, ): AssistantMessage | undefined { @@ -343,12 +406,110 @@ export class RetryHandler { */ private _classifyErrorType(errorMessage: string): UsageLimitErrorType { const err = errorMessage.toLowerCase(); + // Long-context entitlement errors are billing gates, not transient rate limits. + // Must be checked before the generic 429/rate_limit regex. + if (/extra usage is required|long context required/i.test(err)) return "quota_exhausted"; if (/quota|billing|exceeded.*limit|usage.*limit/i.test(err)) return "quota_exhausted"; if (/rate.?limit|too many requests|429/i.test(err)) return "rate_limit"; if (/500|502|503|504|server.?error|internal.?error|service.?unavailable/i.test(err)) return "server_error"; return "unknown"; } + /** + * Attempt to downgrade a long-context model (e.g. claude-opus-4-6[1m]) to its + * base model (claude-opus-4-6) when the account lacks the long-context billing + * entitlement. Returns true if the downgrade was initiated. + */ + private _tryLongContextDowngrade(message: AssistantMessage, retryGeneration: number): boolean { + const currentModel = this._deps.getModel(); + if (!currentModel) return false; + + // Only attempt downgrade for [1m] (or similar long-context) model IDs + const match = currentModel.id.match(/^(.+)\[\d+m\]$/); + if (!match) return false; + + const baseModelId = match[1]; + const baseModel = this._deps.modelRegistry.find(currentModel.provider, baseModelId); + if (!baseModel) return false; + + const previousId = currentModel.id; + this._deps.agent.setModel(baseModel); + this._deps.onModelChange(baseModel); + this._removeLastAssistantError(); + + this._deps.emit({ + type: "fallback_provider_switch", + from: `${currentModel.provider}/${previousId}`, + to: `${baseModel.provider}/${baseModel.id}`, + reason: `long context downgrade: ${previousId} → ${baseModel.id}`, + }); + + this._deps.emit({ + type: "auto_retry_start", + attempt: this._retryAttempt + 1, + maxAttempts: this._deps.settingsManager.getRetrySettings().maxRetries, + delayMs: 0, + errorMessage: `${message.errorMessage} (long context downgrade)`, + }); + + this._scheduleContinue(retryGeneration); + + return true; + } + + /** + * Detect Anthropic subscription block errors (#3772). + * These are hard policy blocks, not transient rate limits — credential + * rotation will not help. Matches both the explicit "third-party" message + * and the "out of extra usage" variant that subscription users receive. + */ + private _isThirdPartyBlock(errorMessage: string): boolean { + return /third[- .]party.*(?:draw from extra|not.*available|plan limits|not permitted|cannot be used|not supported)|(?:out of|no) extra usage/i.test(errorMessage); + } + + /** + * Attempt to switch to the claude-code CLI provider when the current + * Anthropic provider is blocked by the third-party policy (#3772). + * Returns true if the switch was made and retry scheduled. + */ + private _tryClaudeCodeFallback(message: AssistantMessage, retryGeneration: number): boolean { + if (!this._deps.isClaudeCodeReady?.()) return false; + + const currentModel = this._deps.getModel(); + if (!currentModel) return false; + + // Only attempt claude-code fallback when the current provider is anthropic. + // Other providers may produce similar error text but should not be rerouted. + if (currentModel.provider !== "anthropic") return false; + + // Find the same model ID under the claude-code provider + const ccModel = this._deps.modelRegistry.find("claude-code", currentModel.id); + if (!ccModel) return false; + + const previousProvider = currentModel.provider; + this._deps.agent.setModel(ccModel); + this._deps.onModelChange(ccModel); + this._removeLastAssistantError(); + + this._deps.emit({ + type: "fallback_provider_switch", + from: `${previousProvider}/${currentModel.id}`, + to: `claude-code/${ccModel.id}`, + reason: "Anthropic subscription blocked for third-party apps — routing through Claude Code CLI", + }); + + this._deps.emit({ + type: "auto_retry_start", + attempt: this._retryAttempt + 1, + maxAttempts: this._deps.settingsManager.getRetrySettings().maxRetries, + delayMs: 0, + errorMessage: `${message.errorMessage} (switching to Claude Code CLI)`, + }); + + this._scheduleContinue(retryGeneration); + return true; + } + /** Remove the last assistant error message from agent state */ private _removeLastAssistantError(): void { const messages = this._deps.agent.state.messages; diff --git a/packages/pi-coding-agent/src/core/sdk.ts b/packages/pi-coding-agent/src/core/sdk.ts index 55e80dfc8..07ed24c53 100644 --- a/packages/pi-coding-agent/src/core/sdk.ts +++ b/packages/pi-coding-agent/src/core/sdk.ts @@ -75,6 +75,10 @@ export interface CreateAgentSessionOptions { /** Settings manager. Default: SettingsManager.create(cwd, agentDir) */ settingsManager?: SettingsManager; + + /** Optional: check if the claude-code CLI provider is ready (installed + authed). + * Passed to RetryHandler for third-party block recovery (#3772). */ + isClaudeCodeReady?: () => boolean; } /** Result from createAgentSession */ @@ -214,6 +218,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {} } } + // Flush extension provider registrations so extension-provided models (e.g. claude-code/*) + // are available in the registry before model resolution. Without this, findInitialModel() + // cannot find extension models and falls back to built-in providers (#3534). + const extensionsForModelResolution = resourceLoader.getExtensions(); + for (const { name, config } of extensionsForModelResolution.runtime.pendingProviderRegistrations) { + modelRegistry.registerProvider(name, config); + } + // Clear the queue so bindCore() doesn't re-register the same providers. + extensionsForModelResolution.runtime.pendingProviderRegistrations = []; + // If still no model, use findInitialModel (checks settings default, then provider defaults) if (!model) { const result = await findInitialModel({ @@ -327,6 +341,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {} thinkingBudgets: settingsManager.getThinkingBudgets(), maxRetryDelayMs: settingsManager.getRetrySettings().maxDelayMs, externalToolExecution: (m) => modelRegistry.getProviderAuthMode(m.provider) === "externalCli", + getProviderOptions: async (currentModel) => { + if (currentModel.provider !== "claude-code") return undefined; + const runner = extensionRunnerRef.current; + if (!runner?.hasUI()) return undefined; + return { + extensionUIContext: runner.getUIContext(), + }; + }, getApiKey: async (provider) => { // Use the provider argument from the in-flight request; // agent.state.model may already be switched mid-turn. @@ -361,16 +383,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {} await new Promise(resolve => setTimeout(resolve, baseDelayMs * attempt)); } - // All retries exhausted — throw descriptive error - // Check if credentials exist but are temporarily backed off - // (e.g., after a 429 quota exhaustion). Provide a specific error - // so the retry handler knows this is transient, not a permanent - // auth failure. + // All retries exhausted — throw descriptive error. + // Check if credentials exist but are temporarily in a backoff window + // (e.g., after a 429). This message intentionally avoids phrases like + // "rate limit" / "429" to prevent isRetryableError() from re-entering + // the retry handler and creating cascading error entries (#3429). const hasAuth = modelRegistry.authStorage.hasAuth(resolvedProvider); if (hasAuth) { throw new Error( - `All credentials for "${resolvedProvider}" are temporarily backed off due to rate limiting. ` + - `The request will be retried automatically when backoff expires.`, + `All credentials for "${resolvedProvider}" are in a cooldown window. ` + + `Please wait a moment and try again, or switch to a different provider.`, ); } const model = agent.state.model; @@ -380,8 +402,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {} // surface a specific message instead of the misleading "Authentication failed". if (modelRegistry.authStorage.areAllCredentialsBackedOff(resolvedProvider)) { throw new Error( - `Rate limit in effect for "${resolvedProvider}". ` + - `Please wait before retrying or switch to a different model.`, + `All credentials for "${resolvedProvider}" are in a cooldown window. ` + + `Please wait a moment and try again, or switch to a different provider.`, ); } throw new Error( @@ -422,6 +444,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {} modelRegistry, initialActiveToolNames, extensionRunnerRef, + isClaudeCodeReady: options.isClaudeCodeReady, }); const extensionsResult = resourceLoader.getExtensions(); diff --git a/packages/pi-coding-agent/src/core/settings-manager-security.test.ts b/packages/pi-coding-agent/src/core/settings-manager-security.test.ts new file mode 100644 index 000000000..b052a2bd6 --- /dev/null +++ b/packages/pi-coding-agent/src/core/settings-manager-security.test.ts @@ -0,0 +1,102 @@ +import { describe, it, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { SettingsManager } from "./settings-manager.js"; +import { CONFIG_DIR_NAME } from "../config.js"; + +function makeTempDirs() { + const base = mkdtempSync(join(tmpdir(), "settings-security-test-")); + const agentDir = join(base, "agent"); + const cwd = join(base, "project"); + mkdirSync(agentDir, { recursive: true }); + mkdirSync(join(cwd, CONFIG_DIR_NAME), { recursive: true }); + return { base, agentDir, cwd }; +} + +describe("SettingsManager — global-only security settings", () => { + let tmpBase: string | undefined; + + afterEach(() => { + if (tmpBase) { + rmSync(tmpBase, { recursive: true, force: true }); + tmpBase = undefined; + } + }); + + it("returns allowedCommandPrefixes set via setAllowedCommandPrefixes", () => { + const sm = SettingsManager.inMemory(); + assert.equal(sm.getAllowedCommandPrefixes(), undefined); + sm.setAllowedCommandPrefixes(["sops", "doppler"]); + assert.deepEqual(sm.getAllowedCommandPrefixes(), ["sops", "doppler"]); + }); + + it("returns fetchAllowedUrls set via setFetchAllowedUrls", () => { + const sm = SettingsManager.inMemory(); + assert.equal(sm.getFetchAllowedUrls(), undefined); + sm.setFetchAllowedUrls(["internal.company.com"]); + assert.deepEqual(sm.getFetchAllowedUrls(), ["internal.company.com"]); + }); + + it("strips allowedCommandPrefixes from project settings at load time", () => { + const { base, agentDir, cwd } = makeTempDirs(); + tmpBase = base; + + // Global settings: allowedCommandPrefixes = ["sops"] + writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ + allowedCommandPrefixes: ["sops"], + })); + + // Malicious project settings trying to override with a dangerous command + writeFileSync(join(cwd, CONFIG_DIR_NAME, "settings.json"), JSON.stringify({ + allowedCommandPrefixes: ["curl", "bash", "wget"], + })); + + const sm = SettingsManager.create(cwd, agentDir); + + // The getter reads from globalSettings — project override must be stripped + assert.deepEqual(sm.getAllowedCommandPrefixes(), ["sops"]); + }); + + it("strips fetchAllowedUrls from project settings at load time", () => { + const { base, agentDir, cwd } = makeTempDirs(); + tmpBase = base; + + // Global: no fetchAllowedUrls + writeFileSync(join(agentDir, "settings.json"), JSON.stringify({})); + + // Project tries to allowlist cloud metadata + writeFileSync(join(cwd, CONFIG_DIR_NAME, "settings.json"), JSON.stringify({ + fetchAllowedUrls: ["metadata.google.internal", "169.254.169.254"], + })); + + const sm = SettingsManager.create(cwd, agentDir); + + // Global has none — project override must not leak through + assert.equal(sm.getFetchAllowedUrls(), undefined); + }); + + it("project settings for non-security fields still merge normally", () => { + const { base, agentDir, cwd } = makeTempDirs(); + tmpBase = base; + + writeFileSync(join(agentDir, "settings.json"), JSON.stringify({ + allowedCommandPrefixes: ["sops"], + theme: "dark", + })); + + writeFileSync(join(cwd, CONFIG_DIR_NAME, "settings.json"), JSON.stringify({ + allowedCommandPrefixes: ["curl"], + theme: "light", + quietStartup: true, + })); + + const sm = SettingsManager.create(cwd, agentDir); + + // Security field: global wins + assert.deepEqual(sm.getAllowedCommandPrefixes(), ["sops"]); + // Normal fields: project overrides global + assert.equal(sm.getQuietStartup(), true); + }); +}); diff --git a/packages/pi-coding-agent/src/core/settings-manager.ts b/packages/pi-coding-agent/src/core/settings-manager.ts index 092f86315..de75daa0f 100644 --- a/packages/pi-coding-agent/src/core/settings-manager.ts +++ b/packages/pi-coding-agent/src/core/settings-manager.ts @@ -152,6 +152,23 @@ export interface Settings { modelDiscovery?: ModelDiscoverySettings; editMode?: "standard" | "hashline"; // Edit tool mode: "standard" (text match) or "hashline" (LINE#ID anchors). Default: "standard" timestampFormat?: "date-time-iso" | "date-time-us"; // Timestamp display format for messages. Default: "date-time-iso" + allowedCommandPrefixes?: string[]; // Override built-in SAFE_COMMAND_PREFIXES for !command resolution (global-only — ignored in project settings) + fetchAllowedUrls?: string[]; // Hostnames exempted from SSRF blocklist in fetch_page (global-only — ignored in project settings) +} + +/** Settings keys that are only respected from global config — project settings cannot override these. */ +const GLOBAL_ONLY_KEYS: ReadonlySet = new Set([ + "allowedCommandPrefixes", + "fetchAllowedUrls", +]); + +/** Remove global-only keys from a settings object. Applied once at load time. */ +function stripGlobalOnlyKeys(settings: Settings): Settings { + const result = { ...settings }; + for (const key of GLOBAL_ONLY_KEYS) { + delete (result as Record)[key]; + } + return result; } /** Deep merge settings: project/overrides take precedence, nested objects merge recursively */ @@ -304,7 +321,7 @@ export class SettingsManager { ) { this.storage = storage; this.globalSettings = initialGlobal; - this.projectSettings = initialProject; + this.projectSettings = stripGlobalOnlyKeys(initialProject); this.globalSettingsLoadError = globalLoadError; this.projectSettingsLoadError = projectLoadError; this.errors = [...initialErrors]; @@ -441,7 +458,7 @@ export class SettingsManager { const projectLoad = SettingsManager.tryLoadFromStorage(this.storage, "project"); if (!projectLoad.error) { - this.projectSettings = projectLoad.settings; + this.projectSettings = stripGlobalOnlyKeys(projectLoad.settings); this.projectSettingsLoadError = null; } else { this.projectSettingsLoadError = projectLoad.error; @@ -571,7 +588,7 @@ export class SettingsManager { } private saveProjectSettings(settings: Settings): void { - this.projectSettings = structuredClone(settings); + this.projectSettings = stripGlobalOnlyKeys(structuredClone(settings)); this.settings = deepMergeSettings(this.globalSettings, this.projectSettings); if (this.projectSettingsLoadError) { @@ -1096,4 +1113,28 @@ export class SettingsManager { setTimestampFormat(format: "date-time-iso" | "date-time-us"): void { this.setGlobalSetting("timestampFormat", format); } + + /** + * Get the allowed command prefixes from global settings only. + * Returns undefined if not configured (caller should use built-in defaults). + */ + getAllowedCommandPrefixes(): string[] | undefined { + return this.globalSettings.allowedCommandPrefixes; + } + + setAllowedCommandPrefixes(prefixes: string[]): void { + this.setGlobalSetting("allowedCommandPrefixes", prefixes); + } + + /** + * Get the fetch URL allowlist from global settings only. + * Returns undefined if not configured (caller should use empty allowlist). + */ + getFetchAllowedUrls(): string[] | undefined { + return this.globalSettings.fetchAllowedUrls; + } + + setFetchAllowedUrls(urls: string[]): void { + this.setGlobalSetting("fetchAllowedUrls", urls); + } } diff --git a/packages/pi-coding-agent/src/core/tools/hashline-read.ts b/packages/pi-coding-agent/src/core/tools/hashline-read.ts index fc2da81eb..f7d944d14 100644 --- a/packages/pi-coding-agent/src/core/tools/hashline-read.ts +++ b/packages/pi-coding-agent/src/core/tools/hashline-read.ts @@ -123,12 +123,15 @@ export function createHashlineReadTool(cwd: string, options?: HashlineReadToolOp const allLines = textContent.split("\n"); const totalFileLines = allLines.length; - const startLine = offset ? Math.max(0, offset - 1) : 0; - const startLineDisplay = startLine + 1; + let startLine = offset ? Math.max(0, offset - 1) : 0; + // Clamp offset to file bounds instead of throwing (#3007) + let offsetClamped = false; if (startLine >= allLines.length) { - throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`); + startLine = Math.max(0, allLines.length - 1); + offsetClamped = true; } + const startLineDisplay = startLine + 1; let selectedContent: string; let userLimitedLines: number | undefined; @@ -172,6 +175,11 @@ export function createHashlineReadTool(cwd: string, options?: HashlineReadToolOp outputText = formatHashLines(truncation.content, startLineDisplay); } + // Prepend clamp notice so the agent knows offset was adjusted + if (offsetClamped) { + outputText = `[Offset ${offset} beyond end of file (${totalFileLines} lines). Clamped to line ${startLineDisplay}.]\n\n${outputText}`; + } + content = [{ type: "text", text: outputText }]; } diff --git a/packages/pi-coding-agent/src/core/tools/index.ts b/packages/pi-coding-agent/src/core/tools/index.ts index d54ac2a9c..90a5a524c 100644 --- a/packages/pi-coding-agent/src/core/tools/index.ts +++ b/packages/pi-coding-agent/src/core/tools/index.ts @@ -112,6 +112,13 @@ export { lspTool, } from "../lsp/index.js"; export type { LspServerStatus } from "../lsp/client.js"; +export { + registerToolCompatibility, + getToolCompatibility, + getAllToolCompatibility, + registerMcpToolCompatibility, + resetToolCompatibilityRegistry, +} from "./tool-compatibility-registry.js"; import type { AgentTool } from "@gsd/pi-agent-core"; import { type BashToolOptions, bashTool, createBashTool } from "./bash.js"; diff --git a/packages/pi-coding-agent/src/core/tools/read.ts b/packages/pi-coding-agent/src/core/tools/read.ts index c2f23e60a..309e43b57 100644 --- a/packages/pi-coding-agent/src/core/tools/read.ts +++ b/packages/pi-coding-agent/src/core/tools/read.ts @@ -133,13 +133,18 @@ export function createReadTool(cwd: string, options?: ReadToolOptions): AgentToo const totalFileLines = allLines.length; // Apply offset if specified (1-indexed to 0-indexed) - const startLine = offset ? Math.max(0, offset - 1) : 0; - const startLineDisplay = startLine + 1; // For display (1-indexed) + let startLine = offset ? Math.max(0, offset - 1) : 0; - // Check if offset is out of bounds + // Clamp offset to file bounds instead of throwing (#3007). + // When an agent requests offset:30 on a 13-line file, return + // the last line with a notice rather than an error that + // propagates as invalid JSON downstream. + let offsetClamped = false; if (startLine >= allLines.length) { - throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`); + startLine = Math.max(0, allLines.length - 1); + offsetClamped = true; } + const startLineDisplay = startLine + 1; // For display (1-indexed) // If limit is specified by user, use it; otherwise we'll let truncateHead decide let selectedContent: string; @@ -187,6 +192,11 @@ export function createReadTool(cwd: string, options?: ReadToolOptions): AgentToo outputText = truncation.content; } + // Prepend clamp notice so the agent knows offset was adjusted + if (offsetClamped) { + outputText = `[Offset ${offset} beyond end of file (${totalFileLines} lines). Clamped to line ${startLineDisplay}.]\n\n${outputText}`; + } + content = [{ type: "text", text: outputText }]; } diff --git a/packages/pi-coding-agent/src/core/tools/spawn-shell-windows.test.ts b/packages/pi-coding-agent/src/core/tools/spawn-shell-windows.test.ts new file mode 100644 index 000000000..a7929a1dd --- /dev/null +++ b/packages/pi-coding-agent/src/core/tools/spawn-shell-windows.test.ts @@ -0,0 +1,92 @@ +/** + * spawn-shell-windows.test.ts — Regression test for Windows spawn ENOENT/EINVAL. + * + * On Windows, npm/npx/tsc and other tools are installed as .cmd batch scripts. + * Node's `spawn()` without `shell: true` cannot execute .cmd files, resulting + * in ENOENT or EINVAL errors. Every spawn site that may invoke a user-installed + * binary (not `node` or a shell like `sh`/`bash`/`cmd`) must include + * `shell: process.platform === "win32"` so the call is resolved through cmd.exe + * on Windows while remaining a direct exec on POSIX. + * + * This test structurally scans all spawn sites and verifies the guard is present. + * + * Fixes: gsd-build/gsd-2#2854 + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const coreDir = join(__dirname, ".."); + +/** + * Files that call `spawn()` with a user-facing binary (not `node`, `sh`, `bash`, + * or `cmd`) and therefore need the Windows shell guard. + * + * If a file spawns only hardcoded system binaries (like `node` in rpc-client.ts), + * it does not need the guard and should NOT appear here. + */ +const SPAWN_FILES_NEEDING_SHELL_GUARD = [ + // Extension's GSD client — spawns the `gsd` binary which is a .cmd on Windows + join(coreDir, "..", "..", "..", "vscode-extension", "src", "gsd-client.ts"), + // exec.ts — used by extensions to run arbitrary commands + join(coreDir, "exec.ts"), + // LSP index — spawns project-type commands (tsc, cargo, etc.) + join(coreDir, "lsp", "index.ts"), + // LSP client — spawns LSP server binaries (npx, etc.) + join(coreDir, "lsp", "client.ts"), + // LSP mux — spawns lspmux binary + join(coreDir, "lsp", "lspmux.ts"), + // Package manager — spawns npm/yarn/pnpm + join(coreDir, "package-manager.ts"), +]; + +test("all spawn sites that invoke user-facing binaries include shell: process.platform === 'win32'", () => { + const failures: string[] = []; + + for (const file of SPAWN_FILES_NEEDING_SHELL_GUARD) { + let content: string; + try { + content = readFileSync(file, "utf-8"); + } catch { + // File may not exist in this checkout — skip + continue; + } + + const lines = content.split("\n"); + + // Find all spawn(..., { ... }) call sites and check each one + // for the presence of `shell: process.platform === "win32"` within + // 5 lines after the spawn call. + for (let i = 0; i < lines.length; i++) { + const line = lines[i]!; + // Skip comments + if (line.trim().startsWith("//") || line.trim().startsWith("*")) continue; + + // Detect a spawn() call + if (/\bspawn\(/.test(line)) { + // Look ahead up to 8 lines for the shell guard + const lookahead = lines.slice(i, i + 8).join("\n"); + const hasShellGuard = + /shell:\s*process\.platform\s*===\s*["']win32["']/.test(lookahead); + + if (!hasShellGuard) { + const relPath = relative(join(coreDir, "..", ".."), file); + failures.push(`${relPath}:${i + 1}`); + } + } + } + } + + assert.deepEqual( + failures, + [], + `The following spawn sites are missing 'shell: process.platform === "win32"':\n` + + failures.map(f => ` - ${f}`).join("\n") + + `\nOn Windows, .cmd wrapper scripts (npm, npx, tsc, gsd) require shell ` + + `resolution. Without this guard, spawn fails with ENOENT or EINVAL.`, + ); +}); diff --git a/packages/pi-coding-agent/src/core/tools/tool-compatibility-registry.ts b/packages/pi-coding-agent/src/core/tools/tool-compatibility-registry.ts new file mode 100644 index 000000000..9e5bea3b5 --- /dev/null +++ b/packages/pi-coding-agent/src/core/tools/tool-compatibility-registry.ts @@ -0,0 +1,83 @@ +// GSD-2 — Tool Compatibility Registry (ADR-005 Phase 2) +// Maps tool names to their provider compatibility metadata. +// Used by the model router to filter tools incompatible with the selected provider. + +import type { ToolCompatibility } from "../extensions/types.js"; + +// ─── Registry State ───────────────────────────────────────────────────────── + +const registry = new Map(); + +// ─── Built-in Tool Compatibility (universally compatible) ─────────────────── +// Built-in tools (bash, read, write, edit, grep, find, ls) produce text-only +// results and use standard JSON Schema — compatible with all providers. + +const BUILTIN_TOOLS: Record = { + bash: {}, + read: {}, + write: {}, + edit: {}, + grep: {}, + find: {}, + ls: {}, + lsp: {}, + hashline_edit: {}, + hashline_read: {}, +}; + +// Pre-populate registry with built-in tools +for (const [name, compat] of Object.entries(BUILTIN_TOOLS)) { + registry.set(name, compat); +} + +// ─── MCP Tool Defaults ───────────────────────────────────────────────────── +// MCP tools may use complex schemas. Default to cautious compatibility. + +const MCP_TOOL_DEFAULTS: ToolCompatibility = { + schemaFeatures: ["patternProperties"], +}; + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Register compatibility metadata for a tool. + * Called automatically by registerTool() for extension tools that include + * compatibility metadata in their ToolDefinition. + */ +export function registerToolCompatibility(toolName: string, compatibility: ToolCompatibility): void { + registry.set(toolName, compatibility); +} + +/** + * Get compatibility metadata for a tool. + * Returns undefined for unknown tools (treated as universally compatible + * per ADR-005 principle: "fail open, don't restrict without data"). + */ +export function getToolCompatibility(toolName: string): ToolCompatibility | undefined { + return registry.get(toolName); +} + +/** + * Get all registered tool compatibility entries. + */ +export function getAllToolCompatibility(): ReadonlyMap { + return registry; +} + +/** + * Register an MCP tool with default cautious compatibility. + * MCP tools may use complex schemas that some providers don't support. + */ +export function registerMcpToolCompatibility(toolName: string, overrides?: Partial): void { + registry.set(toolName, { ...MCP_TOOL_DEFAULTS, ...overrides }); +} + +/** + * Clear all non-builtin entries (for testing). + */ +export function resetToolCompatibilityRegistry(): void { + registry.clear(); + for (const [name, compat] of Object.entries(BUILTIN_TOOLS)) { + registry.set(name, compat); + } +} diff --git a/packages/pi-coding-agent/src/index.ts b/packages/pi-coding-agent/src/index.ts index 12327173b..ab7de8bac 100644 --- a/packages/pi-coding-agent/src/index.ts +++ b/packages/pi-coding-agent/src/index.ts @@ -49,6 +49,8 @@ export { export { createEventBus, type EventBus, type EventBusController } from "./core/event-bus.js"; // Extension system export type { + AdjustToolSetEvent, + AdjustToolSetResult, AgentEndEvent, AgentStartEvent, AgentToolResult, @@ -68,6 +70,7 @@ export type { Extension, ExtensionActions, ExtensionAPI, + ExtensionManifest, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, @@ -117,8 +120,11 @@ export type { SlashCommandSource, TerminalInputHandler, ToolCallEvent, + ToolCompatibility, ToolDefinition, ToolInfo, + SortResult, + SortWarning, ToolRenderResultOptions, ToolResultEvent, TurnEndEvent, @@ -137,6 +143,9 @@ export { importExtensionModule, isToolCallEventType, isToolResultEventType, + readManifest, + readManifestFromEntryPath, + sortExtensionPaths, wrapRegisteredTool, wrapRegisteredTools, wrapToolsWithExtensions, @@ -219,6 +228,11 @@ export { SettingsManager, type TaskIsolationSettings, } from "./core/settings-manager.js"; +export { + SAFE_COMMAND_PREFIXES, + setAllowedCommandPrefixes, + getAllowedCommandPrefixes, +} from "./core/resolve-config-value.js"; // Skills export { ECOSYSTEM_SKILLS_DIR, @@ -299,6 +313,12 @@ export { type HashlineReadToolDetails, type HashlineReadToolInput, type HashlineReadToolOptions, + // Tool compatibility registry (ADR-005) + registerToolCompatibility, + getToolCompatibility, + getAllToolCompatibility, + registerMcpToolCompatibility, + resetToolCompatibilityRegistry, } from "./core/tools/index.js"; // Main entry point export { main } from "./main.js"; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/__tests__/provider-display-name.test.ts b/packages/pi-coding-agent/src/modes/interactive/components/__tests__/provider-display-name.test.ts new file mode 100644 index 000000000..6b918294d --- /dev/null +++ b/packages/pi-coding-agent/src/modes/interactive/components/__tests__/provider-display-name.test.ts @@ -0,0 +1,18 @@ +// GSD-2 — Provider display name mapping tests +import { test, describe } from "node:test"; +import assert from "node:assert/strict"; +import { providerDisplayName } from "../model-selector.js"; + +describe("providerDisplayName", () => { + test("renames 'anthropic' to 'anthropic-api'", () => { + assert.equal(providerDisplayName("anthropic"), "anthropic-api"); + }); + + test("passes through unmapped providers unchanged", () => { + assert.equal(providerDisplayName("claude-code"), "claude-code"); + assert.equal(providerDisplayName("openai"), "openai"); + assert.equal(providerDisplayName("bedrock"), "bedrock"); + assert.equal(providerDisplayName("github-copilot"), "github-copilot"); + assert.equal(providerDisplayName("openrouter"), "openrouter"); + }); +}); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/__tests__/tool-execution.test.ts b/packages/pi-coding-agent/src/modes/interactive/components/__tests__/tool-execution.test.ts new file mode 100644 index 000000000..9b3123fa5 --- /dev/null +++ b/packages/pi-coding-agent/src/modes/interactive/components/__tests__/tool-execution.test.ts @@ -0,0 +1,54 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import stripAnsi from "strip-ansi"; +import { ToolExecutionComponent } from "../tool-execution.js"; +import { initTheme } from "../../theme/theme.js"; + +initTheme("dark", false); + +function renderTool( + toolName: string, + args: Record, + result?: { + content: Array<{ type: string; text?: string }>; + isError: boolean; + details?: Record; + }, +): string { + const component = new ToolExecutionComponent( + toolName, + args, + {}, + undefined, + { requestRender() {} } as any, + ); + component.setExpanded(true); + if (result) component.updateResult(result); + return stripAnsi(component.render(120).join("\n")); +} + +describe("ToolExecutionComponent", () => { + test("renders capitalized Claude Code Bash tool names with bash output instead of generic args JSON", () => { + const rendered = renderTool( + "Bash", + { command: "pwd" }, + { content: [{ type: "text", text: "/tmp/gsd-pr-fix" }], isError: false }, + ); + + assert.match(rendered, /\$ pwd/); + assert.match(rendered, /\/tmp\/gsd-pr-fix/); + assert.doesNotMatch(rendered, /^\{\s*\}$/m); + }); + + test("renders capitalized Claude Code Read tool names with read output", () => { + const rendered = renderTool( + "Read", + { path: "/tmp/demo.txt" }, + { content: [{ type: "text", text: "hello\nworld" }], isError: false }, + ); + + assert.match(rendered, /read .*demo\.txt/); + assert.match(rendered, /hello/); + assert.match(rendered, /world/); + }); +}); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/armin.ts b/packages/pi-coding-agent/src/modes/interactive/components/armin.ts index afa0d780a..35a591c16 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/armin.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/armin.ts @@ -2,7 +2,7 @@ * Armin says hi! A fun easter egg with animated XBM art. */ -import type { Component, TUI } from "@gsd/pi-tui"; +import { type Component, type TUI, visibleWidth } from "@gsd/pi-tui"; import { theme } from "../theme/theme.js"; // XBM image: 31x36 pixels, LSB first, 1=background, 0=foreground @@ -88,20 +88,20 @@ export class ArminComponent implements Component { return this.cachedLines; } - const padding = 1; - const availableWidth = width - padding; + const center = (s: string) => { + const visible = visibleWidth(s); + const left = Math.max(0, Math.floor((width - visible) / 2)); + return " ".repeat(left) + s; + }; this.cachedLines = this.currentGrid.map((row) => { - // Clip row to available width before applying color - const clipped = row.slice(0, availableWidth).join(""); - const padRight = Math.max(0, width - padding - clipped.length); - return ` ${theme.fg("accent", clipped)}${" ".repeat(padRight)}`; + const clipped = row.slice(0, width).join(""); + return center(theme.fg("accent", clipped)); }); // Add "ARMIN SAYS HI" at the end const message = "ARMIN SAYS HI"; - const msgPadRight = Math.max(0, width - padding - message.length); - this.cachedLines.push(` ${theme.fg("accent", message)}${" ".repeat(msgPadRight)}`); + this.cachedLines.push(center(theme.fg("accent", message))); this.cachedWidth = width; this.cachedVersion = this.gridVersion; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/assistant-message.ts b/packages/pi-coding-agent/src/modes/interactive/components/assistant-message.ts index b0e8bb716..c558b7cfc 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/assistant-message.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/assistant-message.ts @@ -105,8 +105,6 @@ export class AssistantMessageComponent extends Container { : "Operation aborted"; if (hasVisibleContent) { this.contentContainer.addChild(new Spacer(1)); - } else { - this.contentContainer.addChild(new Spacer(1)); } this.contentContainer.addChild(new Text(theme.fg("error", abortMessage), 1, 0)); } else if (message.stopReason === "error") { diff --git a/packages/pi-coding-agent/src/modes/interactive/components/bash-execution.ts b/packages/pi-coding-agent/src/modes/interactive/components/bash-execution.ts index cec80e097..b35855e0f 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/bash-execution.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/bash-execution.ts @@ -29,6 +29,7 @@ export class BashExecutionComponent extends Container { private expanded = false; private contentContainer: Container; private ui: TUI; + private _borderColorKey: "dim" | "bashMode"; constructor(command: string, ui: TUI, excludeFromContext = false) { super(); @@ -37,6 +38,7 @@ export class BashExecutionComponent extends Container { // Use dim border for excluded-from-context commands (!! prefix) const colorKey = excludeFromContext ? "dim" : "bashMode"; + this._borderColorKey = colorKey; const borderColor = (str: string) => theme.fg(colorKey, str); // Add spacer @@ -137,7 +139,7 @@ export class BashExecutionComponent extends Container { this.contentContainer.clear(); // Command header - const header = new Text(theme.fg("bashMode", theme.bold(`$ ${this.command}`)), 1, 0); + const header = new Text(theme.fg(this._borderColorKey, theme.bold(`$ ${this.command}`)), 1, 0); this.contentContainer.addChild(header); // Output diff --git a/packages/pi-coding-agent/src/modes/interactive/components/bordered-loader.ts b/packages/pi-coding-agent/src/modes/interactive/components/bordered-loader.ts index d2610da96..9c4dae2d2 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/bordered-loader.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/bordered-loader.ts @@ -34,8 +34,8 @@ export class BorderedLoader extends Container { if (this.cancellable) { this.addChild(new Spacer(1)); this.addChild(new Text(keyHint("selectCancel", "cancel"), 1, 0)); + this.addChild(new Spacer(1)); } - this.addChild(new Spacer(1)); this.addChild(new DynamicBorder(borderColor)); } diff --git a/packages/pi-coding-agent/src/modes/interactive/components/branch-summary-message.ts b/packages/pi-coding-agent/src/modes/interactive/components/branch-summary-message.ts index c7b666a2f..9c7ed9730 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/branch-summary-message.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/branch-summary-message.ts @@ -32,7 +32,7 @@ export class BranchSummaryMessageComponent extends Box { private updateDisplay(): void { this.clear(); - const label = theme.fg("customMessageLabel", `\x1b[1m[branch]\x1b[22m`); + const label = theme.fg("customMessageLabel", theme.bold("[branch]")); this.addChild(new Text(label, 0, 0)); this.addChild(new Spacer(1)); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/compaction-summary-message.ts b/packages/pi-coding-agent/src/modes/interactive/components/compaction-summary-message.ts index ace738406..f7e68e259 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/compaction-summary-message.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/compaction-summary-message.ts @@ -33,7 +33,7 @@ export class CompactionSummaryMessageComponent extends Box { this.clear(); const tokenStr = this.message.tokensBefore.toLocaleString(); - const label = theme.fg("customMessageLabel", `\x1b[1m[compaction]\x1b[22m`); + const label = theme.fg("customMessageLabel", theme.bold("[compaction]")); this.addChild(new Text(label, 0, 0)); this.addChild(new Spacer(1)); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/config-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/config-selector.ts index 61f6d57dd..befee7ca6 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/config-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/config-selector.ts @@ -346,9 +346,14 @@ class ResourceList implements Component, Focusable { } } - // Scroll indicator + // Scroll indicator — count only selectable items (exclude group/subgroup headers) if (startIndex > 0 || endIndex < this.filteredItems.length) { - lines.push(theme.fg("dim", ` (${this.selectedIndex + 1}/${this.filteredItems.length})`)); + const selectableItems = this.filteredItems.filter((e) => e.type === "item"); + const selectableTotal = selectableItems.length; + const selectablePosition = selectableItems.findIndex( + (e) => this.filteredItems.indexOf(e) === this.selectedIndex, + ); + lines.push(theme.fg("dim", ` (${selectablePosition + 1}/${selectableTotal})`)); } return lines; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/countdown-timer.ts b/packages/pi-coding-agent/src/modes/interactive/components/countdown-timer.ts index 0f051c2f6..ef77320d3 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/countdown-timer.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/countdown-timer.ts @@ -7,6 +7,7 @@ import type { TUI } from "@gsd/pi-tui"; export class CountdownTimer { private intervalId: ReturnType | undefined; private remainingSeconds: number; + private _disposed = false; constructor( timeoutMs: number, @@ -18,6 +19,7 @@ export class CountdownTimer { this.onTick(this.remainingSeconds); this.intervalId = setInterval(() => { + if (this._disposed) return; this.remainingSeconds--; this.onTick(this.remainingSeconds); this.tui?.requestRender(); @@ -30,6 +32,7 @@ export class CountdownTimer { } dispose(): void { + this._disposed = true; if (this.intervalId) { clearInterval(this.intervalId); this.intervalId = undefined; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/custom-message.ts b/packages/pi-coding-agent/src/modes/interactive/components/custom-message.ts index f3f6455fb..ba7cf9634 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/custom-message.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/custom-message.ts @@ -75,7 +75,7 @@ export class CustomMessageComponent extends Container { this.box.clear(); // Default rendering: label + content - const label = theme.fg("customMessageLabel", `\x1b[1m[${this.message.customType}]\x1b[22m`); + const label = theme.fg("customMessageLabel", theme.bold(`[${this.message.customType}]`)); this.box.addChild(new Text(label, 0, 0)); this.box.addChild(new Spacer(1)); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/daxnuts.ts b/packages/pi-coding-agent/src/modes/interactive/components/daxnuts.ts index e501cd435..47b87e146 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/daxnuts.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/daxnuts.ts @@ -4,7 +4,7 @@ * A heartfelt tribute to dax (@thdxr) for providing free Kimi K2.5 access via OpenCode. */ -import type { Component, TUI } from "@gsd/pi-tui"; +import { type Component, type TUI, visibleWidth } from "@gsd/pi-tui"; import { theme } from "../theme/theme.js"; // 32x32 RGB image of dax, hex encoded (3 bytes per pixel) @@ -101,7 +101,7 @@ export class DaxnutsComponent implements Component { const lines: string[] = []; const center = (s: string) => { - const visible = s.replace(/\x1b\[[0-9;]*m/g, "").length; + const visible = visibleWidth(s); const left = Math.max(0, Math.floor((width - visible) / 2)); return " ".repeat(left) + s; }; @@ -145,7 +145,8 @@ export class DaxnutsComponent implements Component { lines.push(""); if (textPhase > 2 || this.tick >= this.maxTicks) { lines.push(center(t.fg("dim", "Try OpenCode"))); - lines.push(center(t.fg("mdLink", "https://mistral.ai/news/mistral-vibe-2-0"))); + // URL removed — was pointing to an incorrect destination + lines.push(center(t.fg("mdLink", "opencode.ai"))); } else { lines.push(""); lines.push(""); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/diff.ts b/packages/pi-coding-agent/src/modes/interactive/components/diff.ts index d575d63e3..55131b023 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/diff.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/diff.ts @@ -6,7 +6,7 @@ import { theme } from "../theme/theme.js"; * Format: "+123 content" or "-123 content" or " 123 content" or " ..." */ function parseDiffLine(line: string): { prefix: string; lineNum: string; content: string } | null { - const match = line.match(/^([+-\s])(\s*\d*)\s(.*)$/); + const match = line.match(/^([+\- ])(\s*\d*)\s(.*)$/); if (!match) return null; return { prefix: match[1], lineNum: match[2], content: match[3] }; } @@ -15,7 +15,7 @@ function parseDiffLine(line: string): { prefix: string; lineNum: string; content * Replace tabs with spaces for consistent rendering. */ function replaceTabs(text: string): string { - return text.replace(/\t/g, " "); + return text.replace(/\t/g, " "); } /** diff --git a/packages/pi-coding-agent/src/modes/interactive/components/dynamic-border.ts b/packages/pi-coding-agent/src/modes/interactive/components/dynamic-border.ts index 60d2da9e3..5a023afd3 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/dynamic-border.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/dynamic-border.ts @@ -1,8 +1,10 @@ -import type { Component } from "@gsd/pi-tui"; +import type { Component, TUI } from "@gsd/pi-tui"; +import { visibleWidth } from "@gsd/pi-tui"; import { theme } from "../theme/theme.js"; /** * Dynamic border component that adjusts to viewport width. + * Supports an optional animated spinner in the label area. * * Note: When used from extensions loaded via jiti, the global `theme` may be undefined * because jiti creates a separate module cache. Always pass an explicit color @@ -10,9 +12,51 @@ import { theme } from "../theme/theme.js"; */ export class DynamicBorder implements Component { private color: (str: string) => string; + private label?: string; + private spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; + private spinnerIndex = 0; + private spinnerInterval: NodeJS.Timeout | null = null; + private spinnerColorFn?: (str: string) => string; - constructor(color: (str: string) => string = (str) => theme.fg("border", str)) { + constructor(color: (str: string) => string = (str) => { + try { return theme.fg("border", str); } catch { return str; } + }, label?: string) { this.color = color; + this.label = label; + } + + setLabel(label: string | undefined): void { + this.label = label; + } + + /** + * Start an animated spinner that prepends to the label. + * The spinner rotates every 80ms and triggers a re-render via the TUI. + */ + startSpinner(ui: TUI, colorFn: (str: string) => string): void { + this.stopSpinner(); + this.spinnerColorFn = colorFn; + this.spinnerIndex = 0; + this.spinnerInterval = setInterval(() => { + this.spinnerIndex = (this.spinnerIndex + 1) % this.spinnerFrames.length; + ui.requestRender(); + }, 80); + ui.requestRender(); + } + + /** + * Stop the spinner animation. The border reverts to a static label. + */ + stopSpinner(): void { + if (this.spinnerInterval) { + clearInterval(this.spinnerInterval); + this.spinnerInterval = null; + } + this.spinnerColorFn = undefined; + } + + get isSpinning(): boolean { + return this.spinnerInterval !== null; } invalidate(): void { @@ -20,6 +64,20 @@ export class DynamicBorder implements Component { } render(width: number): string[] { + const spinnerPrefix = this.spinnerInterval && this.spinnerColorFn + ? this.spinnerColorFn(this.spinnerFrames[this.spinnerIndex]) + " " + : ""; + + if (this.label) { + const labelText = ` ${spinnerPrefix}${this.label} `; + const labelVisible = visibleWidth(labelText); + const leading = "── "; + const remaining = Math.max(0, width - labelVisible - leading.length); + const trailing = "─".repeat(Math.max(1, remaining)); + // Color leading and trailing separately so embedded ANSI in the + // spinner/label doesn't bleed into the trailing dashes. + return [this.color(leading) + labelText + this.color(trailing)]; + } return [this.color("─".repeat(Math.max(1, width)))]; } } diff --git a/packages/pi-coding-agent/src/modes/interactive/components/extension-input.ts b/packages/pi-coding-agent/src/modes/interactive/components/extension-input.ts index 06d7ee933..7634d154f 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/extension-input.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/extension-input.ts @@ -11,6 +11,7 @@ import { keyHint } from "./keybinding-hints.js"; export interface ExtensionInputOptions { tui?: TUI; timeout?: number; + secure?: boolean; } export class ExtensionInputComponent extends Container implements Focusable { @@ -61,6 +62,7 @@ export class ExtensionInputComponent extends Container implements Focusable { } this.input = new Input(); + this.input.secure = opts?.secure === true; if (placeholder) { this.input.placeholder = placeholder; } @@ -74,6 +76,7 @@ export class ExtensionInputComponent extends Container implements Focusable { handleInput(keyData: string): void { const kb = getEditorKeybindings(); if (kb.matches(keyData, "selectConfirm") || keyData === "\n") { + if (this.input.getValue().trim() === "") return; this.onSubmitCallback(this.input.getValue()); } else if (kb.matches(keyData, "selectCancel")) { this.onCancelCallback(); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/extension-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/extension-selector.ts index 2870aed28..e24327fc8 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/extension-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/extension-selector.ts @@ -96,6 +96,10 @@ export class ExtensionSelectorComponent extends Container { if (idx < 0 || idx >= this.options.length) { return Math.max(0, Math.min(from, this.options.length - 1)); } + // If all items are separators, idx may still point to one — fall back to original index + if (this.isSeparator(idx)) { + return Math.max(0, Math.min(from, this.options.length - 1)); + } return idx; } diff --git a/packages/pi-coding-agent/src/modes/interactive/components/footer.ts b/packages/pi-coding-agent/src/modes/interactive/components/footer.ts index 7a2b763bf..3b28c0003 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/footer.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/footer.ts @@ -2,6 +2,7 @@ import { type Component, truncateToWidth, visibleWidth } from "@gsd/pi-tui"; import type { AgentSession } from "../../../core/agent-session.js"; import type { ReadonlyFooterDataProvider } from "../../../core/footer-data-provider.js"; import { theme } from "../theme/theme.js"; +import { providerDisplayName } from "./model-selector.js"; /** * Sanitize text for display in a single-line status. @@ -110,29 +111,36 @@ export class FooterComponent implements Component { pwd = `${pwd} • ${sessionName}`; } - // Build stats line - const statsParts = []; - if (totalInput) statsParts.push(`↑${formatTokens(totalInput)}`); - if (totalOutput) statsParts.push(`↓${formatTokens(totalOutput)}`); - if (totalCacheRead) statsParts.push(`R${formatTokens(totalCacheRead)}`); - if (totalCacheWrite) statsParts.push(`W${formatTokens(totalCacheWrite)}`); + // Build stats line as separate groups joined by a dim middle-dot separator + const sep = ` ${theme.fg("dim", "\u00B7")} `; - // Show cost with "(sub)" indicator if using OAuth subscription + // Group 1: token I/O + const tokenGroup: string[] = []; + if (totalInput) tokenGroup.push(`↑${formatTokens(totalInput)}`); + if (totalOutput) tokenGroup.push(`↓${formatTokens(totalOutput)}`); + + // Group 2: cache metrics + const cacheGroup: string[] = []; + if (totalCacheRead) cacheGroup.push(`cr:${formatTokens(totalCacheRead)}`); + if (totalCacheWrite) cacheGroup.push(`cw:${formatTokens(totalCacheWrite)}`); + + // Group 3: cost + const costGroup: string[] = []; const usingSubscription = displayModel ? this.session.modelRegistry.isUsingOAuth(displayModel) : false; if (totalCost || usingSubscription) { const costStr = `$${totalCost.toFixed(3)}${usingSubscription ? " (sub)" : ""}`; - statsParts.push(costStr); + costGroup.push(costStr); } // Per-prompt cost annotation (opt-in via show_token_cost preference, #1515) if (process.env.GSD_SHOW_TOKEN_COST === "1") { const lastTurnCost = this.session.getLastTurnCost(); if (lastTurnCost > 0) { - statsParts.push(`(last: ${formatPromptCost(lastTurnCost)})`); + costGroup.push(`(last: ${formatPromptCost(lastTurnCost)})`); } } - // Colorize context percentage based on usage + // Group 4: context percentage (colorized) let contextPercentStr: string; const autoIndicator = this.autoCompactEnabled ? " (auto)" : ""; const contextPercentDisplay = @@ -146,9 +154,16 @@ export class FooterComponent implements Component { } else { contextPercentStr = contextPercentDisplay; } - statsParts.push(contextPercentStr); - let statsLeft = statsParts.join(" "); + // Assemble groups: items within a group are space-separated, + // groups are separated by a dim middle-dot + const groups: string[] = []; + if (tokenGroup.length > 0) groups.push(tokenGroup.join(" ")); + if (cacheGroup.length > 0) groups.push(cacheGroup.join(" ")); + if (costGroup.length > 0) groups.push(costGroup.join(" ")); + groups.push(contextPercentStr); + + let statsLeft = groups.join(sep); // Add model name on the right side, plus thinking level if model supports it const modelName = displayModel?.id || "no-model"; @@ -175,7 +190,7 @@ export class FooterComponent implements Component { // Prepend the provider in parentheses if there are multiple providers and there's enough room let rightSide = rightSideWithoutProvider; if (this.footerData.getAvailableProviderCount() > 1 && displayModel) { - rightSide = `(${displayModel.provider}) ${rightSideWithoutProvider}`; + rightSide = `(${providerDisplayName(displayModel.provider)}) ${rightSideWithoutProvider}`; if (statsLeftWidth + minPadding + visibleWidth(rightSide) > width) { // Too wide, fall back rightSide = rightSideWithoutProvider; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/model-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/model-selector.ts index c86347b6f..9f978ffdf 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/model-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/model-selector.ts @@ -15,6 +15,15 @@ import { theme } from "../theme/theme.js"; import { DynamicBorder } from "./dynamic-border.js"; import { keyHint } from "./keybinding-hints.js"; +/** Display names for providers in the model selector UI. */ +const PROVIDER_DISPLAY_NAMES: Record = { + anthropic: "anthropic-api", +}; + +export function providerDisplayName(provider: string): string { + return PROVIDER_DISPLAY_NAMES[provider] ?? provider; +} + function formatTokenCount(count: number): string { if (count >= 1_000_000) { const millions = count / 1_000_000; @@ -391,7 +400,7 @@ export class ModelSelectorComponent extends Container implements Focusable { const ctx = formatTokenCount(item.model.contextWindow); const ctxBadge = theme.fg("muted", `${ctx}`); - const providerBadge = theme.fg("muted", `[${item.provider}]`); + const providerBadge = theme.fg("muted", `[${providerDisplayName(item.provider)}]`); const checkmark = isCurrent ? theme.fg("success", " ✓") : ""; let line: string; @@ -447,7 +456,7 @@ export class ModelSelectorComponent extends Container implements Focusable { if (row.kind === "header") { // Provider group header — always unselectable - const providerLabel = theme.fg("borderAccent", row.provider); + const providerLabel = theme.fg("borderAccent", providerDisplayName(row.provider)); const count = theme.fg("muted", ` (${row.count})`); // Add blank line before header if not the very first visible row if (i > startIndex) { diff --git a/packages/pi-coding-agent/src/modes/interactive/components/oauth-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/oauth-selector.ts index 17844be07..33e23df94 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/oauth-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/oauth-selector.ts @@ -96,14 +96,14 @@ export class OAuthSelectorComponent extends Container { handleInput(keyData: string): void { const kb = getEditorKeybindings(); - // Up arrow + // Up arrow (wrap) if (kb.matches(keyData, "selectUp")) { - this.selectedIndex = Math.max(0, this.selectedIndex - 1); + this.selectedIndex = this.selectedIndex === 0 ? this.allProviders.length - 1 : this.selectedIndex - 1; this.updateList(); } - // Down arrow + // Down arrow (wrap) else if (kb.matches(keyData, "selectDown")) { - this.selectedIndex = Math.min(this.allProviders.length - 1, this.selectedIndex + 1); + this.selectedIndex = this.selectedIndex === this.allProviders.length - 1 ? 0 : this.selectedIndex + 1; this.updateList(); } // Enter diff --git a/packages/pi-coding-agent/src/modes/interactive/components/provider-manager.ts b/packages/pi-coding-agent/src/modes/interactive/components/provider-manager.ts index 9129b746f..aac53ad80 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/provider-manager.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/provider-manager.ts @@ -13,6 +13,7 @@ import { } from "@gsd/pi-tui"; import type { AuthStorage } from "../../../core/auth-storage.js"; import { getDiscoverableProviders } from "../../../core/model-discovery.js"; +import { providerDisplayName } from "./model-selector.js"; import type { ModelRegistry } from "../../../core/model-registry.js"; import { ModelsJsonWriter } from "../../../core/models-json-writer.js"; import { theme } from "../theme/theme.js"; @@ -43,6 +44,9 @@ export class ProviderManagerComponent extends Container implements Focusable { private modelsJsonWriter: ModelsJsonWriter; private onDone: () => void; private onDiscover: (provider: string) => void; + private onSetupAuth: (provider: string) => void; + private confirmingRemove = false; + private hintsContainer: Container; constructor( tui: TUI, @@ -50,6 +54,7 @@ export class ProviderManagerComponent extends Container implements Focusable { modelRegistry: ModelRegistry, onDone: () => void, onDiscover: (provider: string) => void, + onSetupAuth?: (provider: string) => void, ) { super(); @@ -59,18 +64,16 @@ export class ProviderManagerComponent extends Container implements Focusable { this.modelsJsonWriter = new ModelsJsonWriter(this.modelRegistry.modelsJsonPath); this.onDone = onDone; this.onDiscover = onDiscover; + this.onSetupAuth = onSetupAuth ?? (() => {}); // Header this.addChild(new Text(theme.fg("accent", "Provider Manager"), 0, 0)); this.addChild(new Spacer(1)); // Hints - const hints = [ - rawKeyHint("d", "discover"), - rawKeyHint("r", "remove"), - rawKeyHint("esc", "close"), - ].join(" "); - this.addChild(new Text(hints, 0, 0)); + this.hintsContainer = new Container(); + this.addChild(this.hintsContainer); + this.updateHints(); this.addChild(new Spacer(1)); // List @@ -116,6 +119,25 @@ export class ProviderManagerComponent extends Container implements Focusable { this.selectedIndex = Math.min(this.selectedIndex, this.providers.length - 1); } + private updateHints(): void { + this.hintsContainer.clear(); + if (this.confirmingRemove) { + const hints = [ + rawKeyHint("r", "confirm removal"), + rawKeyHint("esc", "cancel"), + ].join(" "); + this.hintsContainer.addChild(new Text(hints, 0, 0)); + } else { + const hints = [ + rawKeyHint("enter", "setup auth"), + rawKeyHint("d", "discover"), + rawKeyHint("r", "remove auth"), + rawKeyHint("esc", "close"), + ].join(" "); + this.hintsContainer.addChild(new Text(hints, 0, 0)); + } + } + private updateList(): void { this.listContainer.clear(); @@ -128,7 +150,7 @@ export class ProviderManagerComponent extends Container implements Focusable { const countBadge = theme.fg("muted", `(${p.modelCount} models)`); const prefix = isSelected ? theme.fg("accent", "> ") : " "; - const nameText = isSelected ? theme.fg("accent", p.name) : p.name; + const nameText = isSelected ? theme.fg("accent", providerDisplayName(p.name)) : providerDisplayName(p.name); const parts = [prefix, nameText, " ", authBadge]; if (discoveryBadge) parts.push(" ", discoveryBadge); @@ -156,21 +178,41 @@ export class ProviderManagerComponent extends Container implements Focusable { this.updateList(); this.tui.requestRender(); } else if (kb.matches(keyData, "selectCancel")) { - this.onDone(); + if (this.confirmingRemove) { + this.confirmingRemove = false; + this.updateHints(); + this.tui.requestRender(); + } else { + this.onDone(); + } } else if (keyData === "d" || keyData === "D") { const provider = this.providers[this.selectedIndex]; if (provider?.supportsDiscovery) { this.onDiscover(provider.name); } } else if (keyData === "r" || keyData === "R") { + const provider = this.providers[this.selectedIndex]; + if (provider?.hasAuth) { + if (this.confirmingRemove) { + this.confirmingRemove = false; + this.authStorage.remove(provider.name); + this.modelsJsonWriter.removeProvider(provider.name); + this.modelRegistry.refresh(); + this.loadProviders(); + this.updateHints(); + this.updateList(); + this.tui.requestRender(); + } else { + this.confirmingRemove = true; + this.updateHints(); + this.tui.requestRender(); + } + } + } else if (kb.matches(keyData, "selectConfirm")) { + // Enter key → initiate auth setup for the selected provider (#3579) const provider = this.providers[this.selectedIndex]; if (provider) { - this.authStorage.remove(provider.name); - this.modelsJsonWriter.removeProvider(provider.name); - this.modelRegistry.refresh(); - this.loadProviders(); - this.updateList(); - this.tui.requestRender(); + this.onSetupAuth(provider.name); } } } diff --git a/packages/pi-coding-agent/src/modes/interactive/components/scoped-models-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/scoped-models-selector.ts index 22f677540..2e1c9e41e 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/scoped-models-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/scoped-models-selector.ts @@ -1,4 +1,5 @@ import type { Model } from "@gsd/pi-ai"; +import { providerDisplayName } from "./model-selector.js"; import { Container, type Focusable, @@ -204,7 +205,7 @@ export class ScopedModelsSelectorComponent extends Container implements Focusabl const isSelected = i === this.selectedIndex; const prefix = isSelected ? theme.fg("accent", "→ ") : " "; const modelText = isSelected ? theme.fg("accent", item.model.id) : item.model.id; - const providerBadge = theme.fg("muted", ` [${item.model.provider}]`); + const providerBadge = theme.fg("muted", ` [${providerDisplayName(item.model.provider)}]`); const status = allEnabled ? "" : item.enabled ? theme.fg("success", " ✓") : theme.fg("dim", " ✗"); this.listContainer.addChild(new Text(`${prefix}${modelText}${providerBadge}${status}`, 0, 0)); } @@ -318,14 +319,9 @@ export class ScopedModelsSelectorComponent extends Container implements Focusabl return; } - // Ctrl+C - clear search or cancel if empty + // Ctrl+C - always cancel immediately if (matchesKey(data, Key.ctrl("c"))) { - if (this.searchInput.getValue()) { - this.searchInput.setValue(""); - this.refresh(); - } else { - this.callbacks.onCancel(); - } + this.callbacks.onCancel(); return; } diff --git a/packages/pi-coding-agent/src/modes/interactive/components/session-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/session-selector.ts index ff37698e0..ac08e7761 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/session-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/session-selector.ts @@ -570,13 +570,13 @@ class SessionList implements Component, Focusable { return; } - // Up arrow + // Up arrow (wrap) if (kb.matches(keyData, "selectUp")) { - this.selectedIndex = Math.max(0, this.selectedIndex - 1); + this.selectedIndex = this.selectedIndex === 0 ? this.filteredSessions.length - 1 : this.selectedIndex - 1; } - // Down arrow + // Down arrow (wrap) else if (kb.matches(keyData, "selectDown")) { - this.selectedIndex = Math.min(this.filteredSessions.length - 1, this.selectedIndex + 1); + this.selectedIndex = this.selectedIndex === this.filteredSessions.length - 1 ? 0 : this.selectedIndex + 1; } // Page up - jump up by maxVisible items else if (kb.matches(keyData, "selectPageUp")) { diff --git a/packages/pi-coding-agent/src/modes/interactive/components/skill-invocation-message.ts b/packages/pi-coding-agent/src/modes/interactive/components/skill-invocation-message.ts index adbf71fd9..4e88f8eff 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/skill-invocation-message.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/skill-invocation-message.ts @@ -35,7 +35,7 @@ export class SkillInvocationMessageComponent extends Box { if (this.expanded) { // Expanded: label + skill name header + full content - const label = theme.fg("customMessageLabel", `\x1b[1m[skill]\x1b[22m`); + const label = theme.fg("customMessageLabel", theme.bold("[skill]")); this.addChild(new Text(label, 0, 0)); const header = `**${this.skillBlock.name}**\n\n`; this.addChild( @@ -46,7 +46,7 @@ export class SkillInvocationMessageComponent extends Box { } else { // Collapsed: single line - [skill] name (hint to expand) const line = - theme.fg("customMessageLabel", `\x1b[1m[skill]\x1b[22m `) + + theme.fg("customMessageLabel", theme.bold("[skill]") + " ") + theme.fg("customMessageText", this.skillBlock.name) + theme.fg("dim", ` (${editorKey("expandTools")} to expand)`); this.addChild(new Text(line, 0, 0)); diff --git a/packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts b/packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts index 399819c30..4f7bcb641 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts @@ -3,6 +3,7 @@ import { Container, getCapabilities, Image, + type ImageDimensions, imageFallback, Spacer, Text, @@ -32,7 +33,7 @@ const WRITE_PARTIAL_FULL_HIGHLIGHT_LINES = 50; * Replace tabs with spaces for consistent rendering */ function replaceTabs(text: string): string { - return text.replace(/\t/g, " "); + return text.replace(/\t/g, " "); } /** @@ -88,11 +89,18 @@ export class ToolExecutionComponent extends Container { private editDiffArgsKey?: string; // Track which args the preview is for // Cached converted images for Kitty protocol (which requires PNG), keyed by index private convertedImages: Map = new Map(); + // Cached resolved image dimensions to avoid re-triggering async parsing + // when updateDisplay() recreates Image components (#3455). + private resolvedImageDimensions: Map = new Map(); // Incremental syntax highlighting cache for write tool call args private writeHighlightCache?: WriteHighlightCache; // When true, this component intentionally renders no lines private hideComponent = false; + private get normalizedToolName(): string { + return typeof this.toolName === "string" ? this.toolName.toLowerCase() : ""; + } + constructor( toolName: string, args: any, @@ -117,7 +125,7 @@ export class ToolExecutionComponent extends Container { // Use contentBox for bash (visual truncation) or custom tools with custom renderers // Use contentText for built-in tools (including overrides without custom renderers) - if (toolName === "bash" || (toolDefinition && !this.shouldUseBuiltInRenderer())) { + if (this.normalizedToolName === "bash" || (toolDefinition && !this.shouldUseBuiltInRenderer())) { this.addChild(this.contentBox); } else { this.addChild(this.contentText); @@ -132,14 +140,24 @@ export class ToolExecutionComponent extends Container { * or the toolDefinition doesn't provide custom renderers. */ private shouldUseBuiltInRenderer(): boolean { - const isBuiltInName = this.toolName in allTools; + const normalizedToolName = this.normalizedToolName; + const isBuiltInName = normalizedToolName in allTools; const hasCustomRenderers = this.toolDefinition?.renderCall || this.toolDefinition?.renderResult; return isBuiltInName && !hasCustomRenderers; } + dispose(): void { + this.convertedImages.clear(); + this.imageComponents = []; + this.imageSpacers = []; + this.editDiffPreview = undefined; + this.writeHighlightCache = undefined; + this.result = undefined; + } + updateArgs(args: any): void { this.args = args; - if (this.toolName === "write" && this.isPartial) { + if (this.normalizedToolName === "write" && this.isPartial) { this.updateWriteHighlightCacheIncremental(); } this.updateDisplay(); @@ -295,7 +313,7 @@ export class ToolExecutionComponent extends Container { ): void { this.result = result; this.isPartial = isPartial; - if (this.toolName === "write" && !isPartial) { + if (this.normalizedToolName === "write" && !isPartial) { const rawPath = str(this.args?.file_path ?? this.args?.path); const fileContent = str(this.args?.content); if (rawPath !== null && fileContent !== null) { @@ -374,7 +392,7 @@ export class ToolExecutionComponent extends Container { // Use built-in rendering for built-in tools (or overrides without custom renderers) if (useBuiltInRenderer) { - if (this.toolName === "bash") { + if (this.normalizedToolName === "bash") { // Bash uses Box with visual line truncation this.contentBox.setBgFn(bgFn); this.contentBox.clear(); @@ -472,16 +490,28 @@ export class ToolExecutionComponent extends Container { const spacer = new Spacer(1); this.addChild(spacer); this.imageSpacers.push(spacer); + // Pass cached dimensions to avoid re-triggering async parsing + // when updateDisplay() recreates Image components (#3455). + const cachedDims = this.resolvedImageDimensions.get(i); const imageComponent = new Image( imageData, imageMimeType, { fallbackColor: (s: string) => theme.fg("toolOutput", s) }, { maxWidthCells: 60 }, + cachedDims, ); - imageComponent.setOnDimensionsResolved(() => { - this.updateDisplay(); - this.ui.requestRender(); - }); + if (!cachedDims) { + const imgIdx = i; + imageComponent.setOnDimensionsResolved(() => { + // Cache resolved dimensions so future updateDisplay() calls + // don't re-trigger async parsing → infinite loop (#3455). + const dims = imageComponent.getDimensions?.(); + if (dims) this.resolvedImageDimensions.set(imgIdx, dims); + // Just re-render — don't call updateDisplay() which would + // destroy and recreate all Image components. + this.ui.requestRender(); + }); + } this.imageComponents.push(imageComponent); this.addChild(imageComponent); } @@ -604,8 +634,9 @@ export class ToolExecutionComponent extends Container { private formatToolExecution(): string { let text = ""; const invalidArg = theme.fg("error", "[invalid arg]"); + const normalizedToolName = this.normalizedToolName; - if (this.toolName === "read") { + if (normalizedToolName === "read") { const rawPath = str(this.args?.file_path ?? this.args?.path); const path = rawPath !== null ? shortenPath(rawPath) : null; const offset = this.args?.offset; @@ -667,7 +698,7 @@ export class ToolExecutionComponent extends Container { } } } - } else if (this.toolName === "write") { + } else if (normalizedToolName === "write") { const rawPath = str(this.args?.file_path ?? this.args?.path); const fileContent = str(this.args?.content); const path = rawPath !== null ? shortenPath(rawPath) : null; @@ -726,7 +757,7 @@ export class ToolExecutionComponent extends Container { text += `\n\n${theme.fg("error", errorText)}`; } } - } else if (this.toolName === "edit") { + } else if (normalizedToolName === "edit") { const rawPath = str(this.args?.file_path ?? this.args?.path); const path = rawPath !== null ? shortenPath(rawPath) : null; @@ -762,7 +793,7 @@ export class ToolExecutionComponent extends Container { text += `\n\n${renderDiff(this.editDiffPreview.diff, { filePath: rawPath ?? undefined })}`; } } - } else if (this.toolName === "ls") { + } else if (normalizedToolName === "ls") { const rawPath = str(this.args?.path); const path = rawPath !== null ? shortenPath(rawPath || ".") : null; const limit = this.args?.limit; @@ -799,7 +830,7 @@ export class ToolExecutionComponent extends Container { text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`; } } - } else if (this.toolName === "find") { + } else if (normalizedToolName === "find") { const pattern = str(this.args?.pattern); const rawPath = str(this.args?.path); const path = rawPath !== null ? shortenPath(rawPath || ".") : null; @@ -841,7 +872,7 @@ export class ToolExecutionComponent extends Container { text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`; } } - } else if (this.toolName === "grep") { + } else if (normalizedToolName === "grep") { const pattern = str(this.args?.pattern); const rawPath = str(this.args?.path); const path = rawPath !== null ? shortenPath(rawPath || ".") : null; @@ -891,7 +922,7 @@ export class ToolExecutionComponent extends Container { text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`; } } - } else if (this.toolName === "web_search") { + } else if (normalizedToolName === "web_search") { // Server-side Anthropic web search text = theme.fg("toolTitle", theme.bold("web search")); @@ -915,8 +946,13 @@ export class ToolExecutionComponent extends Container { // Generic tool (shouldn't reach here for custom tools) text = theme.fg("toolTitle", theme.bold(this.toolName)); - const content = JSON.stringify(this.args, null, 2); - text += `\n\n${content}`; + const contentLines = JSON.stringify(this.args, null, 2).split("\n"); + const maxContentLines = 20; + const truncatedContent = contentLines.slice(0, maxContentLines); + if (contentLines.length > maxContentLines) { + truncatedContent.push("..."); + } + text += `\n\n${truncatedContent.join("\n")}`; const output = this.getTextOutput(); if (output) { text += `\n${output}`; diff --git a/packages/pi-coding-agent/src/modes/interactive/components/user-message-selector.ts b/packages/pi-coding-agent/src/modes/interactive/components/user-message-selector.ts index 94ccf93df..800232faa 100644 --- a/packages/pi-coding-agent/src/modes/interactive/components/user-message-selector.ts +++ b/packages/pi-coding-agent/src/modes/interactive/components/user-message-selector.ts @@ -131,9 +131,10 @@ export class UserMessageSelectorComponent extends Container { this.addChild(new Spacer(1)); this.addChild(new DynamicBorder()); - // Auto-cancel if no messages + // Auto-cancel if no messages — invoke synchronously via microtask + // to avoid the 100ms visual flicker from setTimeout if (messages.length === 0) { - setTimeout(() => onCancel(), 100); + Promise.resolve().then(() => onCancel()); } } diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts index ebe9231ed..88d887ffd 100644 --- a/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts +++ b/packages/pi-coding-agent/src/modes/interactive/controllers/chat-controller.ts @@ -1,11 +1,36 @@ -import { Loader, Spacer, Text } from "@gsd/pi-tui"; +import { Loader, Markdown, Spacer, Text } from "@gsd/pi-tui"; import type { InteractiveModeEvent, InteractiveModeStateHost } from "../interactive-mode-state.js"; import { theme } from "../theme/theme.js"; import { AssistantMessageComponent } from "../components/assistant-message.js"; import { ToolExecutionComponent } from "../components/tool-execution.js"; +import { DynamicBorder } from "../components/dynamic-border.js"; import { appKey } from "../components/keybinding-hints.js"; +// Tracks the last processed content index to avoid re-scanning all blocks on every message_update +let lastProcessedContentIndex = 0; + +function hasVisibleAssistantContent(message: { content: Array }): boolean { + return message.content.some( + (c) => + (c.type === "text" && typeof c.text === "string" && c.text.trim().length > 0) + || (c.type === "thinking" && typeof c.thinking === "string" && c.thinking.trim().length > 0), + ); +} + +function hasAssistantToolBlocks(message: { content: Array }): boolean { + return message.content.some((c) => c.type === "toolCall" || c.type === "serverToolUse"); +} + +// Tracks the latest assistant text for the pinned message zone +let lastPinnedText = ""; +// Whether any tool execution has been added in this assistant turn (triggers pinned display) +let hasToolsInTurn = false; +// Reference to the pinned border so we can toggle its label between working/idle +let pinnedBorder: DynamicBorder | undefined; +// Reference to the pinned markdown component below the border +let pinnedTextComponent: Markdown | undefined; + export async function handleAgentEvent(host: InteractiveModeStateHost & { init: () => Promise; getMarkdownThemeWithSettings: () => any; @@ -28,6 +53,17 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { host.footer.invalidate(); + // Reset content index tracker and pinned state when a new assistant message starts + if (event.type === "message_start" && event.message.role === "assistant") { + lastProcessedContentIndex = 0; + lastPinnedText = ""; + hasToolsInTurn = false; + if (pinnedBorder) pinnedBorder.stopSpinner(); + pinnedBorder = undefined; + pinnedTextComponent = undefined; + host.pinnedMessageContainer.clear(); + } + switch (event.type) { case "session_state_changed": switch (event.reason) { @@ -38,6 +74,12 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { host.streamingMessage = undefined; host.pendingTools.clear(); host.pendingMessagesContainer.clear(); + host.pinnedMessageContainer.clear(); + lastPinnedText = ""; + hasToolsInTurn = false; + if (pinnedBorder) pinnedBorder.stopSpinner(); + pinnedBorder = undefined; + pinnedTextComponent = undefined; host.compactionQueuedMessages = []; host.rebuildChatFromMessages(); host.updatePendingMessagesDisplay(); @@ -96,24 +138,56 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { host.updatePendingMessagesDisplay(); host.ui.requestRender(); } else if (event.message.role === "assistant") { - host.streamingComponent = new AssistantMessageComponent( - undefined, - host.hideThinkingBlock, - host.getMarkdownThemeWithSettings(), - host.settingsManager.getTimestampFormat(), - ); host.streamingMessage = event.message; - host.chatContainer.addChild(host.streamingComponent); - host.streamingComponent.updateContent(host.streamingMessage); + // External-tool providers can stream multiple assistant turns through + // one response. Delay component creation until visible assistant text + // arrives so tool outputs keep chronological ordering. host.ui.requestRender(); } break; case "message_update": - if (host.streamingComponent && event.message.role === "assistant") { + if (event.message.role === "assistant") { host.streamingMessage = event.message; - host.streamingComponent.updateContent(host.streamingMessage); - for (const content of host.streamingMessage.content) { + const innerEvent = event.assistantMessageEvent; + + let externalToolResult: + | { toolCallId: string; content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; details: Record; isError: boolean } + | undefined; + if (innerEvent.type === "toolcall_end" && innerEvent.toolCall) { + const tc = innerEvent.toolCall as any; + const ext = tc.externalResult; + if (ext) { + externalToolResult = { + toolCallId: tc.id, + content: ext.content ?? [{ type: "text", text: "" }], + details: ext.details ?? {}, + isError: ext.isError ?? false, + }; + } + } else if (innerEvent.type === "server_tool_use") { + const idx = typeof innerEvent.contentIndex === "number" ? innerEvent.contentIndex : -1; + const block = idx >= 0 ? (host.streamingMessage.content[idx] as any) : undefined; + const ext = block?.externalResult; + if (block?.id && ext) { + externalToolResult = { + toolCallId: block.id, + content: ext.content ?? [{ type: "text", text: "" }], + details: ext.details ?? {}, + isError: ext.isError ?? false, + }; + } + } + + const contentBlocks = host.streamingMessage.content; + // Some adapters reuse a single assistant lifecycle while internally + // spanning multiple provider turns. When a new turn starts, content + // length can shrink back to 0/1; reset scan index to avoid skipping. + if (lastProcessedContentIndex >= contentBlocks.length) { + lastProcessedContentIndex = 0; + } + for (let i = lastProcessedContentIndex; i < contentBlocks.length; i++) { + const content = contentBlocks[i]; if (content.type === "toolCall") { if (!host.pendingTools.has(content.id)) { const component = new ToolExecutionComponent( @@ -161,13 +235,108 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { } } } + + // When the stream adapter signals a completed tool call with an + // external result (from Claude Code SDK), update the pending + // ToolExecutionComponent immediately so output is visible in + // real-time instead of waiting for the session to end. + if (externalToolResult) { + const component = host.pendingTools.get(externalToolResult.toolCallId); + if (component) { + component.updateResult({ + content: externalToolResult.content, + details: externalToolResult.details, + isError: externalToolResult.isError, + }); + } + } + + // Render assistant text/thinking after tool components so mixed + // streams keep chronological ordering in the chat container. + const hasToolBlocks = hasAssistantToolBlocks(host.streamingMessage); + if (!host.streamingComponent && hasVisibleAssistantContent(host.streamingMessage)) { + host.streamingComponent = new AssistantMessageComponent( + undefined, + host.hideThinkingBlock, + host.getMarkdownThemeWithSettings(), + host.settingsManager.getTimestampFormat(), + ); + host.chatContainer.addChild(host.streamingComponent); + } + if (host.streamingComponent) { + if (hasToolBlocks) { + host.chatContainer.removeChild(host.streamingComponent); + host.chatContainer.addChild(host.streamingComponent); + } + host.streamingComponent.updateContent(host.streamingMessage); + } + + // Update index: fully processed blocks won't need re-scanning. + // Keep the last block's index (it may still be accumulating data), + // so we re-check it next time but skip all earlier ones. + if (contentBlocks.length > 0) { + lastProcessedContentIndex = Math.max(0, contentBlocks.length - 1); + } + + // Pinned message: mirror the latest assistant text above the editor + // when tool executions push it out of the viewport. + const hasTools = contentBlocks.some( + (c: any) => c.type === "toolCall" || c.type === "serverToolUse", + ); + if (hasTools) hasToolsInTurn = true; + + if (hasToolsInTurn) { + // Collect the latest text block(s) from the assistant message + let latestText = ""; + for (let i = contentBlocks.length - 1; i >= 0; i--) { + const c = contentBlocks[i] as any; + if (c.type === "text" && c.text?.trim()) { + latestText = c.text.trim(); + break; + } + } + + if (latestText && latestText !== lastPinnedText) { + lastPinnedText = latestText; + + if (!pinnedBorder) { + // First time: create border + text component + host.pinnedMessageContainer.clear(); + pinnedBorder = new DynamicBorder( + (str: string) => theme.fg("dim", str), + "Working · Latest Output", + ); + pinnedBorder.startSpinner(host.ui, (str: string) => theme.fg("accent", str)); + host.pinnedMessageContainer.addChild(pinnedBorder); + pinnedTextComponent = new Markdown(latestText, 1, 0, host.getMarkdownThemeWithSettings()); + // Cap pinned content to ~40% of terminal height so tall output + // doesn't exceed the viewport and cause render flashing. + pinnedTextComponent.maxLines = Math.max(3, Math.floor(host.ui.terminal.rows * 0.4)); + host.pinnedMessageContainer.addChild(pinnedTextComponent); + // Hide the separate status loader — the pinned zone replaces it + if (host.loadingAnimation) { + host.loadingAnimation.stop(); + host.loadingAnimation = undefined; + } + host.statusContainer.clear(); + } else { + // Update existing markdown component in-place + pinnedTextComponent?.setText(latestText); + // Refresh maxLines in case terminal was resized + if (pinnedTextComponent) { + pinnedTextComponent.maxLines = Math.max(3, Math.floor(host.ui.terminal.rows * 0.4)); + } + } + } + } + host.ui.requestRender(); } break; case "message_end": if (event.message.role === "user") break; - if (host.streamingComponent && event.message.role === "assistant") { + if (event.message.role === "assistant") { host.streamingMessage = event.message; let errorMessage: string | undefined; if (host.streamingMessage.stopReason === "aborted") { @@ -177,7 +346,25 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { : "Operation aborted"; host.streamingMessage.errorMessage = errorMessage; } - host.streamingComponent.updateContent(host.streamingMessage); + + const shouldRenderAssistant = hasVisibleAssistantContent(host.streamingMessage) + || ( + (host.streamingMessage.stopReason === "aborted" || host.streamingMessage.stopReason === "error") + && !hasAssistantToolBlocks(host.streamingMessage) + ); + if (!host.streamingComponent && shouldRenderAssistant) { + host.streamingComponent = new AssistantMessageComponent( + undefined, + host.hideThinkingBlock, + host.getMarkdownThemeWithSettings(), + host.settingsManager.getTimestampFormat(), + ); + host.chatContainer.addChild(host.streamingComponent); + } + if (host.streamingComponent) { + host.streamingComponent.updateContent(host.streamingMessage); + } + if (host.streamingMessage.stopReason === "aborted" || host.streamingMessage.stopReason === "error") { if (!errorMessage) { errorMessage = host.streamingMessage.errorMessage || "Error"; @@ -193,6 +380,15 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { } host.streamingComponent = undefined; host.streamingMessage = undefined; + // Clear pinned output once the message is finalized in the chat + // container — prevents duplicate display when the agent continues + // (e.g. form elicitation) after the assistant message ends. + if (pinnedBorder) pinnedBorder.stopSpinner(); + host.pinnedMessageContainer.clear(); + lastPinnedText = ""; + hasToolsInTurn = false; + pinnedBorder = undefined; + pinnedTextComponent = undefined; host.footer.invalidate(); } host.ui.requestRender(); @@ -245,6 +441,16 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { host.streamingMessage = undefined; } host.pendingTools.clear(); + // Pinned output is only useful while work is actively streaming. + // Keep chat history as the single source after completion. + if (pinnedBorder) { + pinnedBorder.stopSpinner(); + } + host.pinnedMessageContainer.clear(); + lastPinnedText = ""; + hasToolsInTurn = false; + pinnedBorder = undefined; + pinnedTextComponent = undefined; await host.checkShutdownRequested(); host.ui.requestRender(); break; @@ -337,5 +543,12 @@ export async function handleAgentEvent(host: InteractiveModeStateHost & { host.showError(event.reason); host.ui.requestRender(); break; + + case "image_overflow_recovery": + host.showStatus( + `Removed ${event.strippedCount} older image(s) to comply with API limits. Retrying...`, + ); + host.ui.requestRender(); + break; } } diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.test.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.test.ts new file mode 100644 index 000000000..6f5d22da5 --- /dev/null +++ b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.test.ts @@ -0,0 +1,183 @@ +import assert from "node:assert/strict"; +import test from "node:test"; + +import { setupEditorSubmitHandler } from "./input-controller.js"; + +type HostOptions = { + knownSlashCommands?: string[]; +}; + +function getSlashCommandName(text: string): string { + const trimmed = text.trim(); + const spaceIndex = trimmed.indexOf(" "); + return spaceIndex === -1 ? trimmed.slice(1) : trimmed.slice(1, spaceIndex); +} + +function createHost(options: HostOptions = {}) { + const prompted: string[] = []; + const errors: string[] = []; + const warnings: string[] = []; + const history: string[] = []; + const knownSlashCommands = new Set(options.knownSlashCommands ?? []); + let editorText = ""; + let settingsOpened = 0; + + const editor = { + setText(text: string) { + editorText = text; + }, + getText() { + return editorText; + }, + addToHistory(text: string) { + history.push(text); + }, + }; + + const host = { + defaultEditor: editor as typeof editor & { onSubmit?: (text: string) => Promise }, + editor, + session: { + isBashRunning: false, + isCompacting: false, + isStreaming: false, + prompt: async (text: string) => { + prompted.push(text); + }, + }, + ui: { + requestRender() {}, + }, + getSlashCommandContext: () => ({ + showSettingsSelector: () => { + settingsOpened += 1; + }, + }), + handleBashCommand: async () => {}, + showWarning(message: string) { + warnings.push(message); + }, + showError(message: string) { + errors.push(message); + }, + updateEditorBorderColor() {}, + isExtensionCommand() { + return false; + }, + isKnownSlashCommand(text: string) { + return knownSlashCommands.has(getSlashCommandName(text)); + }, + queueCompactionMessage() {}, + updatePendingMessagesDisplay() {}, + flushPendingBashComponents() {}, + }; + + setupEditorSubmitHandler(host as any); + + return { + host: host as typeof host & { defaultEditor: typeof editor & { onSubmit: (text: string) => Promise } }, + prompted, + errors, + warnings, + history, + getEditorText: () => editorText, + getSettingsOpened: () => settingsOpened, + }; +} + +test("input-controller: built-in slash commands stay in TUI dispatch", async () => { + const { host, prompted, errors, getSettingsOpened, getEditorText } = createHost(); + + await host.defaultEditor.onSubmit("/settings"); + + assert.equal(getSettingsOpened(), 1, "built-in /settings should open the settings selector"); + assert.deepEqual(prompted, [], "built-in slash commands should not reach session.prompt"); + assert.deepEqual(errors, [], "built-in slash commands should not show errors"); + assert.equal(getEditorText(), "", "built-in slash commands should clear the editor after handling"); +}); + +test("input-controller: extension slash commands fall through to session.prompt", async () => { + const { host, prompted, errors, history } = createHost({ knownSlashCommands: ["gsd"] }); + + await host.defaultEditor.onSubmit("/gsd help"); + + assert.deepEqual(prompted, ["/gsd help"], "known extension slash commands should reach session.prompt"); + assert.deepEqual(errors, [], "known extension slash commands should not show unknown-command errors"); + assert.deepEqual(history, ["/gsd help"], "known extension slash commands should still be added to history"); +}); + +test("input-controller: prompt template slash commands fall through to session.prompt", async () => { + const { host, prompted, errors } = createHost({ knownSlashCommands: ["daily"] }); + + await host.defaultEditor.onSubmit("/daily focus area"); + + assert.deepEqual(prompted, ["/daily focus area"]); + assert.deepEqual(errors, []); +}); + +test("input-controller: skill slash commands fall through to session.prompt", async () => { + const { host, prompted, errors } = createHost({ knownSlashCommands: ["skill:create-skill"] }); + + await host.defaultEditor.onSubmit("/skill:create-skill routing bug"); + + assert.deepEqual(prompted, ["/skill:create-skill routing bug"]); + assert.deepEqual(errors, []); +}); + +test("input-controller: disabled skill slash commands stay unknown", async () => { + const { host, prompted, errors } = createHost(); + + await host.defaultEditor.onSubmit("/skill:create-skill routing bug"); + + assert.deepEqual(prompted, []); + assert.deepEqual(errors, ["Unknown command: /skill:create-skill. Use slash autocomplete to see available commands."]); +}); + +test("input-controller: /export prefix does not swallow unrelated slash commands", async () => { + const { host, prompted, errors } = createHost(); + + await host.defaultEditor.onSubmit("/exportfoo"); + + assert.deepEqual(prompted, []); + assert.deepEqual(errors, ["Unknown command: /exportfoo. Use slash autocomplete to see available commands."]); +}); + +test("input-controller: truly unknown slash commands stop before session.prompt", async () => { + const { host, prompted, errors, getEditorText } = createHost(); + + await host.defaultEditor.onSubmit("/definitely-not-a-command"); + + assert.deepEqual(prompted, [], "unknown slash commands should not reach session.prompt"); + assert.deepEqual( + errors, + ["Unknown command: /definitely-not-a-command. Use slash autocomplete to see available commands."], + ); + assert.equal(getEditorText(), "", "unknown slash commands should clear the editor after showing the error"); +}); + +test("input-controller: absolute file paths are not treated as slash commands (#3478)", async () => { + const { host, prompted, errors } = createHost(); + + await host.defaultEditor.onSubmit("/Users/name/Desktop/screenshot.png"); + + assert.deepEqual(errors, [], "file paths should not trigger unknown command error"); + assert.deepEqual(prompted, ["/Users/name/Desktop/screenshot.png"], "file paths should be sent as plain input"); +}); + +test("input-controller: Linux absolute paths are not treated as slash commands (#3478)", async () => { + const { host, prompted, errors } = createHost(); + + await host.defaultEditor.onSubmit("/home/user/documents/file.txt"); + + assert.deepEqual(errors, [], "Linux paths should not trigger unknown command error"); + assert.deepEqual(prompted, ["/home/user/documents/file.txt"], "Linux paths should be sent as plain input"); +}); + +test("input-controller: /tmp paths are not treated as slash commands (#3478)", async () => { + const { host, prompted, errors } = createHost(); + + await host.defaultEditor.onSubmit("/tmp/some-file.log"); + + assert.deepEqual(errors, []); + assert.deepEqual(prompted, ["/tmp/some-file.log"]); +}); diff --git a/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts index 0bb073044..dad40f16c 100644 --- a/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts +++ b/packages/pi-coding-agent/src/modes/interactive/controllers/input-controller.ts @@ -1,28 +1,39 @@ import { dispatchSlashCommand } from "../slash-command-handlers.js"; import type { InteractiveModeStateHost } from "../interactive-mode-state.js"; +import type { ContextualTips } from "../../../core/contextual-tips.js"; export function setupEditorSubmitHandler(host: InteractiveModeStateHost & { getSlashCommandContext: () => any; handleBashCommand: (command: string, excludeFromContext?: boolean) => Promise; showWarning: (message: string) => void; showError: (message: string) => void; + showTip: (message: string) => void; updateEditorBorderColor: () => void; isExtensionCommand: (text: string) => boolean; + isKnownSlashCommand: (text: string) => boolean; queueCompactionMessage: (text: string, mode: "steer" | "followUp") => void; updatePendingMessagesDisplay: () => void; flushPendingBashComponents: () => void; + contextualTips: ContextualTips; + getContextPercent: () => number | undefined; options?: { submitPromptsDirectly?: boolean }; }): void { host.defaultEditor.onSubmit = async (text: string) => { text = text.trim(); if (!text) return; - if (text.startsWith("/")) { + if (text.startsWith("/") && !looksLikeFilePath(text)) { const handled = await dispatchSlashCommand(text, host.getSlashCommandContext()); if (handled) { host.editor.setText(""); return; } + if (!host.isKnownSlashCommand(text)) { + const command = text.split(/\s/)[0]; + host.showError(`Unknown command: ${command}. Use slash autocomplete to see available commands.`); + host.editor.setText(""); + return; + } } if (text.startsWith("!")) { @@ -34,6 +45,10 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & { host.editor.setText(text); return; } + // Track included bash commands for double-bang tip + if (!isExcluded) { + host.contextualTips.recordBashIncluded(); + } host.editor.addToHistory?.(text); await host.handleBashCommand(command, isExcluded); host.isBashMode = false; @@ -42,11 +57,27 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & { } } + // Evaluate contextual tips before sending to agent + const tip = host.contextualTips.evaluate({ + input: text, + isStreaming: host.session.isStreaming, + thinkingLevel: host.session.thinkingLevel, + contextPercent: host.getContextPercent(), + }); + if (tip) { + host.showTip(tip); + } + if (host.session.isCompacting) { if (host.isExtensionCommand(text)) { host.editor.addToHistory?.(text); host.editor.setText(""); - await host.session.prompt(text); + try { + await host.session.prompt(text); + } catch (error: unknown) { + const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; + host.showError(errorMessage); + } } else { host.queueCompactionMessage(text, "steer"); } @@ -82,5 +113,28 @@ export function setupEditorSubmitHandler(host: InteractiveModeStateHost & { } host.editor.addToHistory?.(text); + // submitPromptsDirectly is false — still dispatch via session.prompt so user input + // is not silently discarded. + try { + await host.session.prompt(text); + } catch (error: unknown) { + const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; + host.showError(errorMessage); + } }; } + +/** + * Distinguish absolute file paths from slash commands (#3478). + * Drag-and-drop inserts paths like "/Users/name/Desktop/file.png" which + * should be treated as plain text input, not a /Users command. + * + * Heuristic: a slash command is a single token like "/help" or "/gsd auto". + * File paths have a second "/" within the first token (e.g., "/Users/..."). + */ +function looksLikeFilePath(text: string): boolean { + const firstToken = text.split(/\s/)[0]; + // Slash commands: /help, /gsd, /commit — single "/" at start only. + // File paths: /Users/name/file, /home/user/file, /tmp/x — contain "/" after position 0. + return firstToken.indexOf("/", 1) !== -1; +} diff --git a/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts b/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts index cf91b00b1..bffa82d51 100644 --- a/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts +++ b/packages/pi-coding-agent/src/modes/interactive/interactive-mode-state.ts @@ -9,6 +9,7 @@ export interface InteractiveModeStateHost { keybindings: any; statusContainer: any; chatContainer: any; + pinnedMessageContainer: any; settingsManager: any; pendingTools: Map; toolOutputExpanded: boolean; diff --git a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts index 5c539923c..c42aca520 100644 --- a/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts +++ b/packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts @@ -7,6 +7,7 @@ import * as crypto from "node:crypto"; import * as fs from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; +import { listDescendants } from "@gsd/native"; import type { AgentMessage } from "@gsd/pi-agent-core"; import type { AssistantMessage, ImageContent, Message, Model, OAuthProviderId } from "@gsd/pi-ai"; import type { @@ -78,7 +79,7 @@ import { ExtensionSelectorComponent } from "./components/extension-selector.js"; import { FooterComponent } from "./components/footer.js"; import { appKey, appKeyHint, editorKey, formatKeyForDisplay, keyHint, rawKeyHint } from "./components/keybinding-hints.js"; import { LoginDialogComponent } from "./components/login-dialog.js"; -import { ModelSelectorComponent } from "./components/model-selector.js"; +import { ModelSelectorComponent, providerDisplayName } from "./components/model-selector.js"; import { OAuthSelectorComponent } from "./components/oauth-selector.js"; import { ProviderManagerComponent } from "./components/provider-manager.js"; import { ScopedModelsSelectorComponent } from "./components/scoped-models-selector.js"; @@ -89,6 +90,7 @@ import { ToolExecutionComponent } from "./components/tool-execution.js"; import { TreeSelectorComponent } from "./components/tree-selector.js"; import { UserMessageComponent } from "./components/user-message.js"; import { UserMessageSelectorComponent } from "./components/user-message-selector.js"; +import { ContextualTips } from "../../core/contextual-tips.js"; import { type SlashCommandContext, dispatchSlashCommand, getAppKeyDisplay } from "./slash-command-handlers.js"; import { handleAgentEvent } from "./controllers/chat-controller.js"; import { createExtensionUIContext as buildExtensionUIContext } from "./controllers/extension-ui-controller.js"; @@ -107,6 +109,7 @@ import { getThemeByName, initTheme, onThemeChange, + stopThemeWatcher, setRegisteredThemes, setTheme, setThemeInstance, @@ -156,11 +159,16 @@ export interface InteractiveModeOptions { } export class InteractiveMode { + // Cap rendered chat components to prevent unbounded memory/CPU growth. + // Only render-components are removed — session transcript stays on disk. + private static readonly MAX_CHAT_COMPONENTS = 100; + private session: AgentSession; private ui: TUI; private chatContainer: Container; private pendingMessagesContainer: Container; private statusContainer: Container; + private pinnedMessageContainer: Container; private defaultEditor: CustomEditor; private editor: EditorComponent; private autocompleteProvider: CombinedAutocompleteProvider | undefined; @@ -202,9 +210,15 @@ export class InteractiveMode { // Agent subscription unsubscribe function private unsubscribe?: () => void; + // Branch change listener unsubscribe function + private _branchChangeUnsub?: () => void; + // Track if editor is in bash mode (text starts with !) private isBashMode = false; + // Contextual tips — session-scoped, non-intrusive hints + private contextualTips = new ContextualTips(); + // Track current bash execution component private bashComponent: BashExecutionComponent | undefined = undefined; @@ -272,6 +286,7 @@ export class InteractiveMode { this.chatContainer = new Container(); this.pendingMessagesContainer = new Container(); this.statusContainer = new Container(); + this.pinnedMessageContainer = new Container(); this.widgetContainerAbove = new Container(); this.widgetContainerBelow = new Container(); this.keybindings = KeybindingsManager.create(); @@ -329,7 +344,7 @@ export class InteractiveMode { return filtered.map((item) => ({ value: item.label, label: item.id, - description: item.provider, + description: providerDisplayName(item.provider), })); }; } @@ -477,6 +492,7 @@ export class InteractiveMode { this.ui.addChild(this.chatContainer); this.ui.addChild(this.pendingMessagesContainer); this.ui.addChild(this.statusContainer); + this.ui.addChild(this.pinnedMessageContainer); this.renderWidgets(); // Initialize with default spacer this.ui.addChild(this.widgetContainerAbove); this.ui.addChild(this.editorContainer); @@ -511,7 +527,7 @@ export class InteractiveMode { }); // Set up git branch watcher (uses provider instead of footer) - this.footerDataProvider.onBranchChange(() => { + this._branchChangeUnsub = this.footerDataProvider.onBranchChange(() => { this.ui.requestRender(); }); @@ -1383,7 +1399,19 @@ export class InteractiveMode { */ private renderWidgets(): void { if (!this.widgetContainerAbove || !this.widgetContainerBelow) return; - this.renderWidgetContainer(this.widgetContainerAbove, this.extensionWidgetsAbove, true, true); + + // widgetContainerAbove: spacer collapses when pinned content is visible + // so there's no extra blank line between pinned output and the editor border. + this.widgetContainerAbove.clear(); + const pinned = this.pinnedMessageContainer; + this.widgetContainerAbove.addChild({ + render: () => pinned.children.length > 0 ? [] : [""], + invalidate: () => {}, + }); + for (const component of this.extensionWidgetsAbove.values()) { + this.widgetContainerAbove.addChild(component); + } + this.renderWidgetContainer(this.widgetContainerBelow, this.extensionWidgetsBelow, false, false); this.ui.requestRender(); } @@ -1618,7 +1646,7 @@ export class InteractiveMode { this.hideExtensionInput(); resolve(undefined); }, - { tui: this.ui, timeout: opts?.timeout }, + { tui: this.ui, timeout: opts?.timeout, secure: opts?.secure }, ); this.editorContainer.clear(); @@ -1998,8 +2026,9 @@ export class InteractiveMode { } private subscribeToAgent(): void { - this.unsubscribe = this.session.subscribe(async (event) => { - await this.handleEvent(event); + let eventQueue: Promise = Promise.resolve(); + this.unsubscribe = this.session.subscribe((event) => { + eventQueue = eventQueue.then(() => this.handleEvent(event)).catch(() => {}); }); } @@ -2133,6 +2162,18 @@ export class InteractiveMode { const _exhaustive: never = message; } } + this.trimChatHistory(); + } + + /** + * Remove oldest components when chat exceeds MAX_CHAT_COMPONENTS. + * Only render-components are removed — session data stays in SessionManager. + */ + private trimChatHistory(): void { + while (this.chatContainer.children.length > InteractiveMode.MAX_CHAT_COMPONENTS) { + const oldest = this.chatContainer.children[0]; + this.chatContainer.removeChild(oldest); + } } /** @@ -2227,6 +2268,7 @@ export class InteractiveMode { } this.pendingTools.clear(); + this.trimChatHistory(); this.ui.requestRender(); } @@ -2237,6 +2279,7 @@ export class InteractiveMode { updateFooter: true, populateHistory: true, }); + this.populatePinnedFromMessages(context.messages); // Show compaction info if session was compacted const allEntries = this.sessionManager.getEntries(); @@ -2260,6 +2303,54 @@ export class InteractiveMode { this.chatContainer.clear(); const context = this.sessionManager.buildSessionContext(); this.renderSessionContext(context); + this.populatePinnedFromMessages(context.messages); + } + + /** + * After rebuilding chat from messages, pin the last assistant text above the + * editor if tool results would otherwise push it out of the viewport. + */ + private populatePinnedFromMessages(messages: AgentMessage[]): void { + this.pinnedMessageContainer.clear(); + + // Walk backwards to find the last assistant message + let lastAssistant: AssistantMessage | undefined; + for (let i = messages.length - 1; i >= 0; i--) { + const msg = messages[i]; + if (msg && "role" in msg && msg.role === "assistant") { + lastAssistant = msg as AssistantMessage; + break; + } + } + if (!lastAssistant) return; + + // Check if any tool calls follow the last text block + const content = lastAssistant.content; + let lastTextIndex = -1; + let hasToolAfterText = false; + for (let i = 0; i < content.length; i++) { + if (content[i].type === "text") lastTextIndex = i; + } + if (lastTextIndex >= 0) { + for (let i = lastTextIndex + 1; i < content.length; i++) { + if (content[i].type === "toolCall" || content[i].type === "serverToolUse") { + hasToolAfterText = true; + break; + } + } + } + if (!hasToolAfterText || lastTextIndex < 0) return; + + const textBlock = content[lastTextIndex] as { type: "text"; text: string }; + const text = textBlock.text?.trim(); + if (!text) return; + + this.pinnedMessageContainer.addChild( + new DynamicBorder((str: string) => theme.fg("dim", str), "Latest Output"), + ); + this.pinnedMessageContainer.addChild( + new Markdown(text, 1, 0, this.getMarkdownThemeWithSettings()), + ); } // ========================================================================= @@ -2320,6 +2411,21 @@ export class InteractiveMode { if (shutdownBehavior === "stop_ui") { return; } + + // Kill ALL descendant processes to prevent orphans (next-server, pnpm dev, etc.) + try { + const descendants = listDescendants(process.pid); + for (const childPid of descendants) { + try { process.kill(childPid, "SIGTERM"); } catch {} + } + if (descendants.length > 0) { + await new Promise(resolve => setTimeout(resolve, 500)); + for (const childPid of descendants) { + try { process.kill(childPid, "SIGKILL"); } catch {} + } + } + } catch {} + process.exit(0); } @@ -2366,6 +2472,12 @@ export class InteractiveMode { const text = (this.editor.getExpandedText?.() ?? this.editor.getText()).trim(); if (!text) return; + if (text.startsWith("/") && !this.isKnownSlashCommand(text)) { + const command = text.split(/\s/)[0]; + this.showError(`Unknown command: ${command}. Use slash autocomplete to see available commands.`); + return; + } + // Queue input during compaction (extension commands execute immediately) if (this.session.isCompacting) { if (this.isExtensionCommand(text)) { @@ -2549,6 +2661,16 @@ export class InteractiveMode { this.ui.requestRender(); } + showTip(message: string): void { + this.chatContainer.addChild(new Spacer(1)); + this.chatContainer.addChild(new Text(theme.fg("dim", `💡 ${message}`), 1, 0)); + this.ui.requestRender(); + } + + getContextPercent(): number | undefined { + return this.session.getContextUsage()?.percent ?? undefined; + } + showNewVersionNotification(newVersion: string): void { const action = theme.fg("accent", getUpdateInstruction("@gsd/pi-coding-agent")); const updateInstruction = theme.fg("muted", `New version ${newVersion} is available. `) + action; @@ -2648,6 +2770,12 @@ export class InteractiveMode { } private queueCompactionMessage(text: string, mode: "steer" | "followUp"): void { + if (text.startsWith("/") && !this.isKnownSlashCommand(text)) { + const command = text.split(/\s/)[0]; + this.showError(`Unknown command: ${command}. Use slash autocomplete to see available commands.`); + return; + } + this.compactionQueuedMessages.push({ text, mode }); this.editor.addToHistory?.(text); this.editor.setText(""); @@ -2666,6 +2794,32 @@ export class InteractiveMode { return !!extensionRunner.getCommand(commandName); } + private isKnownSlashCommand(text: string): boolean { + if (!text.startsWith("/")) return false; + + const spaceIndex = text.indexOf(" "); + const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex); + + if (BUILTIN_SLASH_COMMANDS.some((command) => command.name === commandName)) { + return true; + } + + if (this.isExtensionCommand(text)) { + return true; + } + + if (this.session.promptTemplates.some((template) => template.name === commandName)) { + return true; + } + + if (commandName.startsWith("skill:") && this.settingsManager.getEnableSkillCommands()) { + const skillName = commandName.slice("skill:".length); + return this.session.resourceLoader.getSkills().skills.some((skill) => skill.name === skillName); + } + + return false; + } + private async flushCompactionQueue(options?: { willRetry?: boolean }): Promise { if (this.compactionQueuedMessages.length === 0) { return; @@ -3335,6 +3489,11 @@ export class InteractiveMode { done(); this.ui.requestRender(); }, + async (provider: string) => { + // Enter key → auth setup for selected provider (#3579) + done(); + await this.showLoginDialog(provider); + }, ); return { component, focus: component }; }); @@ -3598,6 +3757,9 @@ export class InteractiveMode { this.streamingMessage = undefined; this.pendingTools.clear(); + // Reset contextual tips for the new session + this.contextualTips.reset(); + this.chatContainer.addChild(new Spacer(1)); this.chatContainer.addChild(new Text(`${theme.fg("accent", "✓ New session started")}`, 1, 1)); this.ui.requestRender(); @@ -3805,6 +3967,33 @@ export class InteractiveMode { this.loadingAnimation = undefined; } this.clearExtensionTerminalInputListeners(); + + // Clean up branch change listener (Fix 1) + this._branchChangeUnsub?.(); + this._branchChangeUnsub = undefined; + + // Clean up theme change listener and watcher (Fix 2) + onThemeChange(() => {}); + stopThemeWatcher(); + + // Resolve any pending getUserInput promise so the run() loop can exit (Fix 3) + if (this.onInputCallback) { + this.onInputCallback(""); + this.onInputCallback = undefined; + } + + // Dispose extension widgets, custom footer, and custom header (Fix 4) + this.clearExtensionWidgets(); + if (this.customFooter?.dispose) { + this.customFooter.dispose(); + } + this.customFooter = undefined; + if (this.customHeader?.dispose) { + this.customHeader.dispose(); + } + this.customHeader = undefined; + this.autocompleteProvider = undefined; + this.footer.dispose(); this.footerDataProvider.dispose(); if (this.unsubscribe) { diff --git a/packages/pi-coding-agent/src/modes/interactive/slash-command-handlers.ts b/packages/pi-coding-agent/src/modes/interactive/slash-command-handlers.ts index c735f8216..24fd8bb7a 100644 --- a/packages/pi-coding-agent/src/modes/interactive/slash-command-handlers.ts +++ b/packages/pi-coding-agent/src/modes/interactive/slash-command-handlers.ts @@ -136,7 +136,7 @@ export async function dispatchSlashCommand( await ctx.handleModelCommand(searchTerm); return true; } - if (text.startsWith("/export")) { + if (text === "/export" || text.startsWith("/export ")) { await handleExportCommand(text, ctx); return true; } @@ -305,11 +305,13 @@ async function handleShareCommand(ctx: SlashCommandContext): Promise { ctx.showStatus("Share cancelled"); }; - try { - const result = await new Promise<{ stdout: string; stderr: string; code: number | null }>((resolve) => { - proc = spawn("gh", ["gist", "create", "--public=false", tmpFile]); - let stdout = ""; - let stderr = ""; + try { + const result = await new Promise<{ stdout: string; stderr: string; code: number | null }>((resolve) => { + proc = spawn("gh", ["gist", "create", "--public=false", tmpFile], { + shell: process.platform === "win32", + }); + let stdout = ""; + let stderr = ""; proc.stdout?.on("data", (data) => { stdout += data.toString(); }); diff --git a/packages/pi-coding-agent/src/modes/interactive/theme/themes.ts b/packages/pi-coding-agent/src/modes/interactive/theme/themes.ts index 45ea9609d..f1459a0bb 100644 --- a/packages/pi-coding-agent/src/modes/interactive/theme/themes.ts +++ b/packages/pi-coding-agent/src/modes/interactive/theme/themes.ts @@ -23,7 +23,7 @@ const dark: ThemeJson = { blue: "#5f87ff", green: "#b5bd68", red: "#cc6666", - yellow: "#ffff00", + yellow: "#e6b800", gray: "#808080", dimGray: "#666666", darkGray: "#505050", diff --git a/packages/pi-coding-agent/src/modes/rpc/remote-terminal.ts b/packages/pi-coding-agent/src/modes/rpc/remote-terminal.ts index 84f78f950..4dda9b0c9 100644 --- a/packages/pi-coding-agent/src/modes/rpc/remote-terminal.ts +++ b/packages/pi-coding-agent/src/modes/rpc/remote-terminal.ts @@ -49,6 +49,12 @@ export class RemoteTerminal implements Terminal { return this._rows; } + get isTTY(): boolean { + // RemoteTerminal renders to a browser-based terminal emulator via + // the RPC bridge — it behaves like a real TTY for rendering purposes. + return true; + } + get kittyProtocolActive(): boolean { return false; } diff --git a/packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts b/packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts index f2f8fbe4c..7d36e563a 100644 --- a/packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts +++ b/packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts @@ -224,7 +224,7 @@ export async function runRpcMode(session: AgentSession): Promise { ), input: (title, placeholder, opts) => - createDialogPromise(opts, undefined, { method: "input", title, placeholder, timeout: opts?.timeout }, (r) => + createDialogPromise(opts, undefined, { method: "input", title, placeholder, timeout: opts?.timeout, secure: opts?.secure }, (r) => "cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined, ), diff --git a/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts b/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts index 20d5c2c73..d6cd25bfc 100644 --- a/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts +++ b/packages/pi-coding-agent/src/modes/rpc/rpc-types.ts @@ -291,6 +291,7 @@ export type RpcExtensionUIRequest = title: string; placeholder?: string; timeout?: number; + secure?: boolean; } | { type: "extension_ui_request"; id: string; method: "editor"; title: string; prefill?: string } | { diff --git a/packages/pi-tui/src/__tests__/autocomplete.test.ts b/packages/pi-tui/src/__tests__/autocomplete.test.ts index c4a44db76..e065f8f6b 100644 --- a/packages/pi-tui/src/__tests__/autocomplete.test.ts +++ b/packages/pi-tui/src/__tests__/autocomplete.test.ts @@ -52,6 +52,14 @@ describe("CombinedAutocompleteProvider — slash commands", () => { const result = provider.getSuggestions(["hello /se"], 0, 9); assert.equal(result, null); }); + + it("triggers slash commands after leading whitespace", () => { + const provider = makeProvider(sampleCommands); + const result = provider.getSuggestions([" /se"], 0, 5); + assert.ok(result); + assert.equal(result!.prefix, "/se"); + assert.ok(result!.items.some((item) => item.value === "settings")); + }); }); describe("CombinedAutocompleteProvider — argument completions", () => { @@ -144,6 +152,13 @@ describe("CombinedAutocompleteProvider — applyCompletion", () => { assert.equal(result.cursorCol, 10); // after "/settings " }); + it("preserves leading whitespace when applying slash command completion", () => { + const provider = makeProvider(sampleCommands); + const result = provider.applyCompletion([" /se"], 0, 5, { value: "settings", label: "settings" }, "/se"); + assert.equal(result.lines[0], " /settings "); + assert.equal(result.cursorCol, 12); + }); + it("applies file path completion for @ prefix", () => { const provider = makeProvider(); const result = provider.applyCompletion( diff --git a/packages/pi-tui/src/__tests__/overlay-layout.test.ts b/packages/pi-tui/src/__tests__/overlay-layout.test.ts new file mode 100644 index 000000000..49d0539da --- /dev/null +++ b/packages/pi-tui/src/__tests__/overlay-layout.test.ts @@ -0,0 +1,82 @@ +// pi-tui — Overlay Layout Tests (backdrop dimming) + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { compositeOverlays, type OverlayEntry } from "../overlay-layout.js"; + +function makeEntry( + lines: string[], + options?: OverlayEntry["options"], +): OverlayEntry { + return { + component: { render: () => lines }, + options, + hidden: false, + focusOrder: 1, + }; +} + +describe("compositeOverlays — backdrop", () => { + it("dims base lines when backdrop is true", () => { + const base = ["hello world", "second line"]; + const overlay = makeEntry(["OVERLAY"], { + width: 7, + anchor: "top-left", + backdrop: true, + }); + + const result = compositeOverlays(base, [overlay], 20, 20, 2); + + // All base lines in viewport should contain dim escape (\x1b[2m) + // The overlay line itself is composited on top, but underlying lines get dimmed + const dimmedLine = result.find((l) => l.includes("second line")); + assert.ok(dimmedLine, "should have a line containing 'second line'"); + assert.ok(dimmedLine.includes("\x1b[2m"), "base line should be dimmed"); + }); + + it("backdrop uses gray foreground for dimming", () => { + const base = ["hello world", "second line"]; + const overlay = makeEntry(["OV"], { + width: 2, + anchor: "top-left", + backdrop: true, + }); + + const result = compositeOverlays(base, [overlay], 20, 20, 2); + + // Check a non-overlay line for backdrop codes (dim + gray fg, no bg) + const line = result.find((l) => l.includes("second line")); + assert.ok(line, "should have a line containing 'second line'"); + assert.ok(line.includes("\x1b[38;5;240m"), "backdrop should set gray foreground"); + assert.ok(!line.includes("\x1b[48;"), "backdrop should not set background color"); + }); + + it("does not dim when backdrop is false/absent", () => { + const base = ["hello world", "second line"]; + const overlay = makeEntry(["OVERLAY"], { + width: 7, + anchor: "top-left", + }); + + const result = compositeOverlays(base, [overlay], 20, 20, 2); + + // Lines not covered by overlay should remain undimmed + const secondLine = result.find((l) => l.includes("second line")); + assert.ok(secondLine, "should have a line containing 'second line'"); + assert.ok(!secondLine.includes("\x1b[2m"), "base line should not be dimmed"); + }); + + it("overlay content renders on top of dimmed background", () => { + const base = ["aaaaaaaaaa"]; + const overlay = makeEntry(["XX"], { + width: 2, + anchor: "top-left", + backdrop: true, + }); + + const result = compositeOverlays(base, [overlay], 10, 10, 1); + + // The first line should contain the overlay text + assert.ok(result[0].includes("XX"), "overlay text should be composited"); + }); +}); diff --git a/packages/pi-tui/src/__tests__/stdin-buffer.test.ts b/packages/pi-tui/src/__tests__/stdin-buffer.test.ts new file mode 100644 index 000000000..ba053567b --- /dev/null +++ b/packages/pi-tui/src/__tests__/stdin-buffer.test.ts @@ -0,0 +1,43 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { setTimeout as delay } from "node:timers/promises"; + +import { StdinBuffer } from "../stdin-buffer.js"; + +describe("StdinBuffer", () => { + it("flushes a lone Escape keypress", async () => { + const buffer = new StdinBuffer({ timeout: 5 }); + const received: string[] = []; + buffer.on("data", (sequence) => received.push(sequence)); + + buffer.process("\x1b"); + await delay(20); + + assert.deepEqual(received, ["\x1b"]); + assert.equal(buffer.getBuffer(), ""); + }); + + it("keeps split CSI focus and mouse sequences buffered until completion", async () => { + const buffer = new StdinBuffer({ timeout: 5 }); + const received: string[] = []; + buffer.on("data", (sequence) => received.push(sequence)); + + buffer.process("\x1b["); + await delay(20); + assert.deepEqual(received, []); + assert.equal(buffer.getBuffer(), "\x1b["); + + buffer.process("I"); + assert.deepEqual(received, ["\x1b[I"]); + assert.equal(buffer.getBuffer(), ""); + + buffer.process("\x1b[<35;20;"); + await delay(20); + assert.deepEqual(received, ["\x1b[I"]); + assert.equal(buffer.getBuffer(), "\x1b[<35;20;"); + + buffer.process("5m"); + assert.deepEqual(received, ["\x1b[I", "\x1b[<35;20;5m"]); + assert.equal(buffer.getBuffer(), ""); + }); +}); diff --git a/packages/pi-tui/src/__tests__/tui.test.ts b/packages/pi-tui/src/__tests__/tui.test.ts new file mode 100644 index 000000000..7c4903dc7 --- /dev/null +++ b/packages/pi-tui/src/__tests__/tui.test.ts @@ -0,0 +1,50 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { TUI } from "../tui.js"; +import type { Terminal } from "../terminal.js"; + +function makeTerminal(): Terminal { + return { + isTTY: true, + columns: 80, + rows: 24, + kittyProtocolActive: false, + start() {}, + stop() {}, + drainInput: async () => {}, + write() {}, + moveBy() {}, + hideCursor() {}, + showCursor() {}, + clearLine() {}, + clearFromCursor() {}, + clearScreen() {}, + setTitle() {}, + }; +} + +describe("TUI", () => { + it("does not swallow a bare Escape keypress while waiting for the cell-size response", () => { + const tui = new TUI(makeTerminal()); + const received: string[] = []; + + tui.setFocus({ + render: () => [], + handleInput: (data: string) => { + received.push(data); + }, + invalidate() {}, + }); + + const anyTui = tui as any; + anyTui.cellSizeQueryPending = true; + anyTui.inputBuffer = ""; + + anyTui.handleInput("\x1b"); + + assert.deepEqual(received, ["\x1b"]); + assert.equal(anyTui.cellSizeQueryPending, false); + assert.equal(anyTui.inputBuffer, ""); + }); +}); diff --git a/packages/pi-tui/src/autocomplete.ts b/packages/pi-tui/src/autocomplete.ts index d0969921f..1ecd1e754 100644 --- a/packages/pi-tui/src/autocomplete.ts +++ b/packages/pi-tui/src/autocomplete.ts @@ -159,6 +159,7 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider { ): { items: AutocompleteItem[]; prefix: string } | null { const currentLine = lines[cursorLine] || ""; const textBeforeCursor = currentLine.slice(0, cursorCol); + const trimmedBeforeCursor = textBeforeCursor.trimStart(); // Check for @ file reference (fuzzy search) - must be after a delimiter or at start const atPrefix = this.extractAtPrefix(textBeforeCursor); @@ -174,12 +175,12 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider { } // Check for slash commands - if (textBeforeCursor.startsWith("/")) { - const spaceIndex = textBeforeCursor.indexOf(" "); + if (trimmedBeforeCursor.startsWith("/")) { + const spaceIndex = trimmedBeforeCursor.indexOf(" "); if (spaceIndex === -1) { // No space yet - complete command names with fuzzy matching - const prefix = textBeforeCursor.slice(1); // Remove the "/" + const prefix = trimmedBeforeCursor.slice(1); // Remove the "/" const commandItems = this.commands.map((cmd) => ({ name: "name" in cmd ? cmd.name : cmd.value, label: "name" in cmd ? cmd.name : cmd.label, @@ -196,12 +197,12 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider { return { items: filtered, - prefix: textBeforeCursor, + prefix: `/${prefix}`, }; } else { // Space found - complete command arguments - const commandName = textBeforeCursor.slice(1, spaceIndex); // Command without "/" - const argumentText = textBeforeCursor.slice(spaceIndex + 1); // Text after space + const commandName = trimmedBeforeCursor.slice(1, spaceIndex); // Command without "/" + const argumentText = trimmedBeforeCursor.slice(spaceIndex + 1); // Text after space const command = this.commands.find((cmd) => { const name = "name" in cmd ? cmd.name : cmd.value; @@ -269,7 +270,8 @@ export class CombinedAutocompleteProvider implements AutocompleteProvider { // Check if we're completing a slash command (prefix starts with "/" but NOT a file path) // Slash commands are at the start of the line and don't contain path separators after the first / - const isSlashCommand = prefix.startsWith("/") && beforePrefix.trim() === "" && !prefix.slice(1).includes("/"); + const trimmedPrefix = prefix.trimStart(); + const isSlashCommand = trimmedPrefix.startsWith("/") && beforePrefix.trim() === "" && !trimmedPrefix.slice(1).includes("/"); if (isSlashCommand) { // This is a command name completion const newLine = `${beforePrefix}/${item.value} ${adjustedAfterCursor}`; diff --git a/packages/pi-tui/src/components/__tests__/editor.test.ts b/packages/pi-tui/src/components/__tests__/editor.test.ts new file mode 100644 index 000000000..057ed20da --- /dev/null +++ b/packages/pi-tui/src/components/__tests__/editor.test.ts @@ -0,0 +1,64 @@ +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; + +import { Editor, type EditorTheme } from "../editor.js"; +import { CURSOR_MARKER, TUI } from "../../tui.js"; +import type { Terminal } from "../../terminal.js"; + +function makeTerminal(): Terminal { + return { + isTTY: true, + columns: 80, + rows: 24, + kittyProtocolActive: false, + start() {}, + stop() {}, + drainInput: async () => {}, + write() {}, + moveBy() {}, + hideCursor() {}, + showCursor() {}, + clearLine() {}, + clearFromCursor() {}, + clearScreen() {}, + setTitle() {}, + }; +} + +const theme: EditorTheme = { + borderColor: (text) => text, + selectList: { + selectedPrefix: (text) => text, + selectedText: (text) => text, + description: (text) => text, + scrollInfo: (text) => text, + noMatch: (text) => text, + }, +}; + +describe("Editor", () => { + it("clears bracketed paste state when focus is lost", () => { + const editor = new Editor(new TUI(makeTerminal()), theme); + editor.focused = true; + + editor.handleInput("\x1b[200~partial"); + editor.focused = false; + editor.focused = true; + editor.handleInput("hello"); + + assert.equal(editor.getText(), "hello"); + }); + + it("keeps the hardware cursor marker visible while autocomplete is open", () => { + const editor = new Editor(new TUI(makeTerminal()), theme); + editor.focused = true; + editor.setText("/se"); + + (editor as any).autocompleteState = "regular"; + (editor as any).autocompleteList = { render: () => [] }; + + const rendered = editor.render(40).join("\n"); + + assert.ok(rendered.includes(CURSOR_MARKER)); + }); +}); diff --git a/packages/pi-tui/src/components/__tests__/input.test.ts b/packages/pi-tui/src/components/__tests__/input.test.ts index c47100492..581c2e14f 100644 --- a/packages/pi-tui/src/components/__tests__/input.test.ts +++ b/packages/pi-tui/src/components/__tests__/input.test.ts @@ -32,4 +32,15 @@ describe("Input", () => { input.focused = false; assert.equal(input.focused, false); }); + + it("secure mode obscures typed characters in render output", () => { + const input = new Input(); + input.secure = true; + input.focused = true; + input.handleInput("secret123"); + + const line = input.render(40)[0] ?? ""; + assert.ok(!line.includes("secret123"), "rendered line must not expose raw secret text"); + assert.ok(line.includes("*********"), "rendered line should include masked characters"); + }); }); diff --git a/packages/pi-tui/src/components/__tests__/markdown-maxlines.test.ts b/packages/pi-tui/src/components/__tests__/markdown-maxlines.test.ts new file mode 100644 index 000000000..fb9fbf0bc --- /dev/null +++ b/packages/pi-tui/src/components/__tests__/markdown-maxlines.test.ts @@ -0,0 +1,75 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +import { Markdown, type MarkdownTheme } from "../markdown.js"; + +function noopTheme(): MarkdownTheme { + const identity = (text: string) => text; + return { + heading: identity, + link: identity, + linkUrl: identity, + code: identity, + codeBlock: identity, + codeBlockBorder: identity, + quote: identity, + quoteBorder: identity, + hr: identity, + listBullet: identity, + bold: identity, + italic: identity, + strikethrough: identity, + underline: identity, + }; +} + +test("Markdown renders all lines when maxLines is not set", () => { + const text = "Line 1\n\nLine 2\n\nLine 3\n\nLine 4\n\nLine 5"; + const md = new Markdown(text, 0, 0, noopTheme()); + const lines = md.render(80); + // Each paragraph produces a line + an inter-paragraph blank line + const contentLines = lines.filter((l) => l.trim().length > 0); + assert.ok(contentLines.length >= 5, `expected at least 5 content lines, got ${contentLines.length}`); +}); + +test("Markdown truncates from the top when maxLines is exceeded", () => { + const text = "Line 1\n\nLine 2\n\nLine 3\n\nLine 4\n\nLine 5"; + const md = new Markdown(text, 0, 0, noopTheme()); + md.maxLines = 3; + const lines = md.render(80); + assert.ok(lines.length <= 3, `expected at most 3 lines, got ${lines.length}`); + // First line should be the ellipsis indicator + assert.ok(lines[0].includes("…"), "first line should contain ellipsis indicator"); + assert.ok(lines[0].includes("above"), "first line should mention lines above"); +}); + +test("Markdown preserves most recent content when truncating", () => { + const text = "First paragraph\n\nSecond paragraph\n\nThird paragraph\n\nFourth paragraph\n\nFifth paragraph"; + const md = new Markdown(text, 0, 0, noopTheme()); + md.maxLines = 3; + const lines = md.render(80); + // The last rendered line should contain "Fifth paragraph" (the most recent content) + const lastContentLine = lines.filter((l) => !l.includes("…")).pop() ?? ""; + assert.ok( + lastContentLine.includes("Fifth paragraph"), + `expected last content line to contain "Fifth paragraph", got "${lastContentLine}"`, + ); +}); + +test("Markdown does not truncate when content fits within maxLines", () => { + const text = "Short text"; + const md = new Markdown(text, 0, 0, noopTheme()); + md.maxLines = 10; + const lines = md.render(80); + assert.ok(!lines.some((l) => l.includes("…")), "should not contain ellipsis when content fits"); + assert.ok(lines.some((l) => l.includes("Short text")), "should contain the original text"); +}); + +test("Markdown trims trailing empty lines", () => { + const text = "Some text\n\n"; + const md = new Markdown(text, 0, 0, noopTheme()); + const lines = md.render(80); + // Last line should not be empty (trailing empties are trimmed) + const lastLine = lines[lines.length - 1]; + assert.ok(lastLine.trim().length > 0 || lines.length === 1, "trailing empty lines should be trimmed"); +}); diff --git a/packages/pi-tui/src/components/editor.ts b/packages/pi-tui/src/components/editor.ts index c9cefb83c..b370445c9 100644 --- a/packages/pi-tui/src/components/editor.ts +++ b/packages/pi-tui/src/components/editor.ts @@ -128,7 +128,17 @@ export class Editor implements Component, Focusable { }; /** Focusable interface - set by TUI when focus changes */ - focused: boolean = false; + private _focused: boolean = false; + get focused(): boolean { + return this._focused; + } + set focused(value: boolean) { + this._focused = value; + if (!value) { + this.isInPaste = false; + this.pasteBuffer = ""; + } + } protected tui: TUI; private theme: EditorTheme; @@ -376,8 +386,9 @@ export class Editor implements Component, Focusable { } // Render each visible layout line - // Emit hardware cursor marker only when focused and not showing autocomplete - const emitCursorMarker = this.focused && !this.autocompleteState; + // Keep the hardware cursor anchored while autocomplete is open so IME + // candidate windows still attach to the editor caret. + const emitCursorMarker = this.focused; for (const layoutLine of visibleLines) { let displayText = layoutLine.text; diff --git a/packages/pi-tui/src/components/image.test.ts b/packages/pi-tui/src/components/image.test.ts new file mode 100644 index 000000000..3bef04a85 --- /dev/null +++ b/packages/pi-tui/src/components/image.test.ts @@ -0,0 +1,36 @@ +/** + * Regression test for #3455: Image component must not trigger infinite + * re-render loop when dimensions resolve in cmux sessions. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { Image } from "./image.js"; + +describe("Image component (#3455)", () => { + const theme = { fallbackColor: (s: string) => s }; + + test("getDimensions returns undefined before resolution", () => { + // Pass explicit dimensions to avoid async parsing + const img = new Image("base64data", "image/png", theme, {}); + // Without explicit dims, getDimensions should be undefined until async resolve + // But we can't easily test async here, so verify the method exists + assert.equal(typeof img.getDimensions, "function"); + }); + + test("getDimensions returns dimensions when provided at construction", () => { + const dims = { widthPx: 100, heightPx: 200 }; + const img = new Image("base64data", "image/png", theme, {}, dims); + const result = img.getDimensions(); + assert.deepEqual(result, dims, "Should return provided dimensions"); + }); + + test("onDimensionsResolved callback is not called when dimensions provided", () => { + let callCount = 0; + const dims = { widthPx: 100, heightPx: 200 }; + const img = new Image("base64data", "image/png", theme, {}, dims); + img.setOnDimensionsResolved(() => { callCount++; }); + // With pre-resolved dims, the async path is skipped entirely + assert.equal(callCount, 0, "Callback should not fire for pre-resolved dimensions"); + }); +}); diff --git a/packages/pi-tui/src/components/image.ts b/packages/pi-tui/src/components/image.ts index c789a0a5b..814167605 100644 --- a/packages/pi-tui/src/components/image.ts +++ b/packages/pi-tui/src/components/image.ts @@ -72,6 +72,11 @@ export class Image implements Component { return this.imageId; } + /** Get the resolved image dimensions (for caching across recreations). */ + getDimensions(): ImageDimensions | undefined { + return this.dimensionsResolved ? this.dimensions : undefined; + } + invalidate(): void { this.cachedLines = undefined; this.cachedWidth = undefined; diff --git a/packages/pi-tui/src/components/input.ts b/packages/pi-tui/src/components/input.ts index 627f3557c..78535ab3f 100644 --- a/packages/pi-tui/src/components/input.ts +++ b/packages/pi-tui/src/components/input.ts @@ -21,6 +21,8 @@ export class Input implements Component, Focusable { public onSubmit?: (value: string) => void; public onEscape?: () => void; public placeholder: string = ""; + /** When true, render obscured characters instead of the actual value. */ + public secure: boolean = false; /** Focusable interface - set by TUI when focus changes */ private _focused: boolean = false; @@ -446,6 +448,7 @@ export class Input implements Component, Focusable { // Calculate visible window const prompt = "> "; const availableWidth = width - prompt.length; + const renderValue = this.secure ? "*".repeat(this.value.length) : this.value; if (availableWidth <= 0) { return [prompt]; @@ -466,7 +469,7 @@ export class Input implements Component, Focusable { if (this.value.length < availableWidth) { // Everything fits (leave room for cursor at end) - visibleText = this.value; + visibleText = renderValue; } else { // Need horizontal scrolling // Reserve one character for cursor if it's at the end @@ -501,17 +504,17 @@ export class Input implements Component, Focusable { if (this.cursor < halfWidth) { // Cursor near start - visibleText = this.value.slice(0, findValidEnd(scrollWidth)); + visibleText = renderValue.slice(0, findValidEnd(scrollWidth)); cursorDisplay = this.cursor; } else if (this.cursor > this.value.length - halfWidth) { // Cursor near end const start = findValidStart(this.value.length - scrollWidth); - visibleText = this.value.slice(start); + visibleText = renderValue.slice(start); cursorDisplay = this.cursor - start; } else { // Cursor in middle const start = findValidStart(this.cursor - halfWidth); - visibleText = this.value.slice(start, findValidEnd(start + scrollWidth)); + visibleText = renderValue.slice(start, findValidEnd(start + scrollWidth)); cursorDisplay = halfWidth; } } diff --git a/packages/pi-tui/src/components/loader.ts b/packages/pi-tui/src/components/loader.ts index a55a2570c..5115f8337 100644 --- a/packages/pi-tui/src/components/loader.ts +++ b/packages/pi-tui/src/components/loader.ts @@ -2,13 +2,16 @@ import type { TUI } from "../tui.js"; import { Text } from "./text.js"; /** - * Loader component that updates every 80ms with spinning animation + * Loader component that updates every 80ms with spinning animation. + * Frame rotation is isolated from message text to avoid invalidating + * Text's render cache (wrapTextWithAnsi, visibleWidth) on every tick. */ export class Loader extends Text { private frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; private currentFrame = 0; private intervalId: NodeJS.Timeout | null = null; private ui: TUI | null = null; + private _lastMessage: string = ""; constructor( ui: TUI, @@ -22,18 +25,38 @@ export class Loader extends Text { } render(width: number): string[] { - return ["", ...super.render(width)]; + // Only update Text content when message actually changes — + // frame rotation is prepended below without touching the cache + if (this.message !== this._lastMessage) { + this.setText(this.messageColorFn(this.message)); + this._lastMessage = this.message; + } + const messageLines = super.render(width); + // Shallow copy so we don't mutate cachedLines from Text + const result = ["", ...messageLines]; + // Prepend spinner frame to first content line + if (result.length > 1) { + const frame = this.frames[this.currentFrame]; + result[1] = this.spinnerColorFn(frame) + " " + result[1]; + } + return result; } start() { if (this.intervalId) { clearInterval(this.intervalId); } - this.updateDisplay(); + this.currentFrame = 0; this.intervalId = setInterval(() => { this.currentFrame = (this.currentFrame + 1) % this.frames.length; - this.updateDisplay(); + if (this.ui) { + this.ui.requestRender(); + } }, 80); + // Trigger initial render + if (this.ui) { + this.ui.requestRender(); + } } stop() { @@ -50,12 +73,6 @@ export class Loader extends Text { setMessage(message: string) { this.message = message; - this.updateDisplay(); - } - - private updateDisplay() { - const frame = this.frames[this.currentFrame]; - this.setText(`${this.spinnerColorFn(frame)} ${this.messageColorFn(this.message)}`); if (this.ui) { this.ui.requestRender(); } diff --git a/packages/pi-tui/src/components/markdown.ts b/packages/pi-tui/src/components/markdown.ts index 0920e6b4f..e1d7d454f 100644 --- a/packages/pi-tui/src/components/markdown.ts +++ b/packages/pi-tui/src/components/markdown.ts @@ -58,10 +58,13 @@ export class Markdown implements Component { private defaultTextStyle?: DefaultTextStyle; private theme: MarkdownTheme; private defaultStylePrefix?: string; + /** Maximum rendered lines (excluding padding). When set, content is truncated from the top with an ellipsis indicator so the most recent output remains visible. */ + maxLines?: number; // Cache for rendered output private cachedText?: string; private cachedWidth?: number; + private cachedMaxLines?: number; private cachedLines?: string[]; constructor( @@ -86,12 +89,13 @@ export class Markdown implements Component { invalidate(): void { this.cachedText = undefined; this.cachedWidth = undefined; + this.cachedMaxLines = undefined; this.cachedLines = undefined; } render(width: number): string[] { // Check cache - if (this.cachedLines && this.cachedText === this.text && this.cachedWidth === width) { + if (this.cachedLines && this.cachedText === this.text && this.cachedWidth === width && this.cachedMaxLines === this.maxLines) { return this.cachedLines; } @@ -104,6 +108,7 @@ export class Markdown implements Component { // Update cache this.cachedText = this.text; this.cachedWidth = width; + this.cachedMaxLines = this.maxLines; this.cachedLines = result; return result; } @@ -124,6 +129,12 @@ export class Markdown implements Component { for (let j = 0; j < tokenLines.length; j++) renderedLines.push(tokenLines[j]); } + // Trim trailing empty lines — inter-block spacing at the end just adds + // unwanted whitespace before whatever follows (e.g. pinned output border). + while (renderedLines.length > 0 && renderedLines[renderedLines.length - 1] === "") { + renderedLines.pop(); + } + // Wrap lines (NO padding, NO background yet) const wrappedLines: string[] = []; for (const line of renderedLines) { @@ -143,6 +154,15 @@ export class Markdown implements Component { } } + // Truncate from the top when maxLines is set so the most recent content + // stays visible. This prevents the pinned output zone from exceeding the + // terminal height and causing render flashing. + if (this.maxLines !== undefined && wrappedLines.length > this.maxLines) { + const keep = Math.max(1, this.maxLines - 1); // Reserve one line for the ellipsis indicator + const truncated = wrappedLines.length - keep; + wrappedLines.splice(0, truncated, `… ${truncated} line${truncated !== 1 ? "s" : ""} above`); + } + // Add margins and background to each wrapped line const leftMargin = " ".repeat(this.paddingX); const rightMargin = " ".repeat(this.paddingX); @@ -181,6 +201,7 @@ export class Markdown implements Component { // Update cache this.cachedText = this.text; this.cachedWidth = width; + this.cachedMaxLines = this.maxLines; this.cachedLines = result; return result.length > 0 ? result : [""]; diff --git a/packages/pi-tui/src/components/text.ts b/packages/pi-tui/src/components/text.ts index efcf25b45..a9519bfdf 100644 --- a/packages/pi-tui/src/components/text.ts +++ b/packages/pi-tui/src/components/text.ts @@ -23,6 +23,7 @@ export class Text implements Component { } setText(text: string): void { + if (this.text === text) return; this.text = text; this.cachedText = undefined; this.cachedWidth = undefined; diff --git a/packages/pi-tui/src/overlay-layout.ts b/packages/pi-tui/src/overlay-layout.ts index 1896c5bba..5e306ec91 100644 --- a/packages/pi-tui/src/overlay-layout.ts +++ b/packages/pi-tui/src/overlay-layout.ts @@ -6,7 +6,7 @@ */ import type { OverlayAnchor, OverlayOptions, SizeValue } from "./tui.js"; -import { extractSegments, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth } from "./utils.js"; +import { applyBackgroundToLine, extractSegments, sliceByColumn, sliceWithWidth, truncateToWidth, visibleWidth } from "./utils.js"; import { isImageLine } from "./terminal-image.js"; import { CURSOR_MARKER } from "./tui.js"; @@ -324,6 +324,18 @@ export function compositeOverlays( const viewportStart = Math.max(0, workingHeight - termHeight); + // Apply backdrop dimming if any visible overlay requests it. + // Uses dim + gray foreground so text fades without painting empty lines. + const hasBackdrop = visibleEntries.some((e) => e.options?.backdrop); + if (hasBackdrop) { + const dimFn = (text: string) => `\x1b[2m\x1b[38;5;240m${text}\x1b[39m\x1b[22m`; + for (let i = viewportStart; i < result.length; i++) { + if (!isImageLine(result[i]) && result[i].length > 0) { + result[i] = applyBackgroundToLine(result[i], termWidth, dimFn); + } + } + } + // Composite each overlay for (const { overlayLines, row, col, w } of rendered) { for (let i = 0; i < overlayLines.length; i++) { diff --git a/packages/pi-tui/src/stdin-buffer.ts b/packages/pi-tui/src/stdin-buffer.ts index 5b2f977b0..ea2baec91 100644 --- a/packages/pi-tui/src/stdin-buffer.ts +++ b/packages/pi-tui/src/stdin-buffer.ts @@ -361,6 +361,13 @@ export class StdinBuffer extends EventEmitter { return []; } + // Keep incomplete escape prefixes buffered so split CSI/mouse/focus + // sequences do not get emitted as literal text on timeout. + // A lone ESC is still flushed so an actual Escape keypress is not lost. + if (this.buffer.length > 1 && this.buffer.startsWith(ESC) && isCompleteSequence(this.buffer) === "incomplete") { + return []; + } + const sequences = [this.buffer]; this.buffer = ""; return sequences; diff --git a/packages/pi-tui/src/terminal.ts b/packages/pi-tui/src/terminal.ts index 52bb27ad3..ff84a6283 100644 --- a/packages/pi-tui/src/terminal.ts +++ b/packages/pi-tui/src/terminal.ts @@ -9,6 +9,9 @@ const cjsRequire = createRequire(import.meta.url); * Minimal terminal interface for TUI */ export interface Terminal { + // Whether stdout is a real TTY (false for pipes, e.g. RPC bridge processes) + readonly isTTY: boolean; + // Start the terminal with input and resize handlers start(onInput: (data: string) => void, onResize: () => void): void; @@ -63,11 +66,22 @@ export class ProcessTerminal implements Terminal { private stdinDataHandler?: (data: string) => void; private writeLogPath = process.env.PI_TUI_WRITE_LOG || ""; + get isTTY(): boolean { + return !!process.stdout.isTTY; + } + get kittyProtocolActive(): boolean { return this._kittyProtocolActive; } start(onInput: (data: string) => void, onResize: () => void): void { + // Non-TTY stdout (pipe) — skip TUI initialization entirely. + // RPC bridge processes communicate via JSON, not terminal escape codes. + // Without this guard, the render loop burns 500%+ CPU. (issue #3095) + if (!this.isTTY) { + return; + } + this.inputHandler = onInput; this.resizeHandler = onResize; diff --git a/packages/pi-tui/src/tui.ts b/packages/pi-tui/src/tui.ts index d0154b0ce..7c58c0145 100644 --- a/packages/pi-tui/src/tui.ts +++ b/packages/pi-tui/src/tui.ts @@ -141,6 +141,8 @@ export interface OverlayOptions { visible?: (termWidth: number, termHeight: number) => boolean; /** If true, don't capture keyboard focus when shown */ nonCapturing?: boolean; + /** If true, dim the background behind the overlay */ + backdrop?: boolean; } /** @@ -166,20 +168,33 @@ export interface OverlayHandle { */ export class Container implements Component { children: Component[] = []; + private _prevRender: string[] | null = null; addChild(component: Component): void { this.children.push(component); + this._prevRender = null; } removeChild(component: Component): void { const index = this.children.indexOf(component); if (index !== -1) { + const child = this.children[index]; this.children.splice(index, 1); + if ('dispose' in child && typeof (child as any).dispose === 'function') { + (child as any).dispose(); + } + this._prevRender = null; } } clear(): void { + for (const child of this.children) { + if ('dispose' in child && typeof (child as any).dispose === 'function') { + (child as any).dispose(); + } + } this.children = []; + this._prevRender = null; } invalidate(): void { @@ -194,6 +209,17 @@ export class Container implements Component { const rendered = child.render(width); for (let i = 0; i < rendered.length; i++) lines.push(rendered[i]); } + // Return stable reference if output unchanged — allows doRender() + // to skip ALL post-processing (isImageLine, applyLineResets, diffs) + const prev = this._prevRender; + if (prev && prev.length === lines.length) { + let same = true; + for (let i = 0; i < lines.length; i++) { + if (lines[i] !== prev[i]) { same = false; break; } + } + if (same) return prev; + } + this._prevRender = lines; return lines; } } @@ -222,6 +248,7 @@ export class TUI extends Container { private previousViewportTop = 0; // Track previous viewport top for resize-aware cursor moves private fullRedrawCount = 0; private stopped = false; + private _lastRenderedComponents: string[] | null = null; // Overlay stack for modal components rendered on top of base content private focusOrderCounter = 0; @@ -399,6 +426,12 @@ export class TUI extends Container { start(): void { this.stopped = false; + // Non-TTY stdout (pipe) — skip TUI entirely to avoid burning CPU. + // RPC bridge processes have piped stdio; rendering ANSI escape codes + // to a pipe is pure waste and causes a runaway render loop. (issue #3095) + if (!this.terminal.isTTY) { + return; + } this.terminal.start( (data) => this.handleInput(data), () => this.requestRender(), @@ -458,6 +491,8 @@ export class TUI extends Container { } requestRender(force = false): void { + // Skip rendering on non-TTY stdout to prevent CPU burn (issue #3095) + if (!this.terminal.isTTY) return; if (force) { this.previousLines = []; this.previousWidth = -1; // -1 triggers widthChanged, forcing a full clear @@ -555,6 +590,15 @@ export class TUI extends Container { this.cellSizeQueryPending = false; } + // Don't hold a bare Escape keypress hostage while waiting for the + // optional cell-size response. This is the most common early input race. + if (this.inputBuffer === "\x1b") { + const result = this.inputBuffer; + this.inputBuffer = ""; + this.cellSizeQueryPending = false; + return result; + } + // Check if we have a partial cell size response starting (wait for more data) // Patterns that could be incomplete cell size response: \x1b, \x1b[, \x1b[6, \x1b[6;...(no t yet) const partialCellSizePattern = /\x1b(\[6?;?[\d;]*)?$/; @@ -591,6 +635,13 @@ export class TUI extends Container { // Render all components to get new lines let newLines = this.render(width); + // Skip ALL post-processing if component output is unchanged. + // Container.render() returns the same array reference when stable. + if (newLines === this._lastRenderedComponents && this.overlayStack.length === 0) { + return; + } + this._lastRenderedComponents = newLines; + // Composite overlays into the rendered lines (before differential compare) if (this.overlayStack.length > 0) { newLines = compositeOverlays(newLines, this.overlayStack, width, height, this.maxLinesRendered); diff --git a/pkg/package.json b/pkg/package.json index d0c190750..31a3b4639 100644 --- a/pkg/package.json +++ b/pkg/package.json @@ -1,6 +1,6 @@ { "name": "@glittercowboy/gsd", - "version": "2.58.0", + "version": "2.71.0", "piConfig": { "name": "gsd", "configDir": ".gsd" diff --git a/repowise.db b/repowise.db new file mode 100644 index 000000000..df702d28f Binary files /dev/null and b/repowise.db differ diff --git a/scripts/dev.js b/scripts/dev.js index faf9a75d2..0eea64072 100644 --- a/scripts/dev.js +++ b/scripts/dev.js @@ -11,15 +11,18 @@ import { spawn } from 'node:child_process' import { resolve, dirname } from 'node:path' import { fileURLToPath } from 'node:url' +import { createRequire } from 'node:module' const __dirname = dirname(fileURLToPath(import.meta.url)) const root = resolve(__dirname, '..') +const require = createRequire(import.meta.url) +const tscBin = require.resolve('typescript/bin/tsc') const procs = [ spawn('node', [resolve(__dirname, 'watch-resources.js')], { cwd: root, stdio: 'inherit' }), - spawn(resolve(root, 'node_modules', '.bin', 'tsc'), ['--watch'], { + spawn(process.execPath, [tscBin, '--watch'], { cwd: root, stdio: 'inherit' }) ] diff --git a/scripts/ensure-workspace-builds.cjs b/scripts/ensure-workspace-builds.cjs index 44f7ea2c4..60636feb6 100644 --- a/scripts/ensure-workspace-builds.cjs +++ b/scripts/ensure-workspace-builds.cjs @@ -37,6 +37,48 @@ function newestSrcMtime(dir) { return newest } +/** + * Detects workspace packages whose dist/ is missing or stale. + * + * Missing dist/index.js is always reported (the package won't work at all). + * + * Staleness (src/ newer than dist/) is ONLY checked when a .git directory + * exists at root — indicating a development clone. In npm tarball installs, + * file timestamps are unreliable (npm sets all files to a canonical date, + * but extraction ordering can cause src/ to appear 1-2 seconds newer than + * dist/). Attempting to rebuild in that scenario is dangerous: devDependencies + * (including TypeScript) are not installed, and any globally-installed tsc + * may produce broken output that overwrites the known-good dist/. + * + * @param {string} root Project root directory + * @param {string[]} packages Package directory names to check + * @returns {string[]} Package names that need rebuilding + */ +function detectStalePackages(root, packages) { + const packagesDir = join(root, 'packages') + const isDevClone = existsSync(join(root, '.git')) + + const stale = [] + for (const pkg of packages) { + const distIndex = join(packagesDir, pkg, 'dist', 'index.js') + if (!existsSync(distIndex)) { + stale.push(pkg) + continue + } + // Only check src vs dist timestamps in development clones. + // In npm tarball installs, timestamps are unreliable and rebuilding + // without devDependencies can corrupt the pre-built dist/ (#2877). + if (isDevClone) { + const distMtime = statSync(distIndex).mtimeMs + const srcMtime = newestSrcMtime(join(packagesDir, pkg, 'src')) + if (srcMtime > distMtime) { + stale.push(pkg) + } + } + } + return stale +} + if (require.main === module) { const root = resolve(__dirname, '..') const packagesDir = join(root, 'packages') @@ -55,21 +97,11 @@ if (require.main === module) { 'pi-ai', 'pi-agent-core', 'pi-coding-agent', + 'rpc-client', + 'mcp-server', ] - const stale = [] - for (const pkg of WORKSPACE_PACKAGES) { - const distIndex = join(packagesDir, pkg, 'dist', 'index.js') - if (!existsSync(distIndex)) { - stale.push(pkg) - continue - } - const distMtime = statSync(distIndex).mtimeMs - const srcMtime = newestSrcMtime(join(packagesDir, pkg, 'src')) - if (srcMtime > distMtime) { - stale.push(pkg) - } - } + const stale = detectStalePackages(root, WORKSPACE_PACKAGES) if (stale.length === 0) process.exit(0) @@ -78,6 +110,7 @@ if (require.main === module) { for (const pkg of stale) { const pkgDir = join(packagesDir, pkg) try { + // execSync is safe here: the command is a hardcoded string, not user input execSync('npm run build', { cwd: pkgDir, stdio: 'pipe' }) process.stderr.write(` ✓ ${pkg}\n`) } catch (err) { @@ -87,4 +120,4 @@ if (require.main === module) { } } -module.exports = { newestSrcMtime } +module.exports = { newestSrcMtime, detectStalePackages } diff --git a/scripts/install-hooks.mjs b/scripts/install-hooks.mjs new file mode 100644 index 000000000..dea550585 --- /dev/null +++ b/scripts/install-hooks.mjs @@ -0,0 +1,52 @@ +#!/usr/bin/env node + +import { execFileSync } from 'node:child_process'; +import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; + +const MARKER = '# gsd-secret-scan'; + +function git(args) { + return execFileSync('git', args, { + encoding: 'utf8', + shell: process.platform === 'win32', + }).trim(); +} + +const gitDir = git(['rev-parse', '--git-dir']); +const repoRoot = git(['rev-parse', '--show-toplevel']); +const hookDir = join(gitDir, 'hooks'); +const hookFile = join(hookDir, 'pre-commit'); +const hookCommand = `node "${join(repoRoot, 'scripts', 'secret-scan.mjs')}"`; + +mkdirSync(hookDir, { recursive: true }); + +if (existsSync(hookFile)) { + const current = readFileSync(hookFile, 'utf8'); + if (current.includes(MARKER)) { + process.stdout.write('secret-scan pre-commit hook already installed.\n'); + process.exit(0); + } + + const next = `${current.replace(/\s*$/, '\n')}${MARKER}\n${hookCommand}\n`; + writeFileSync(hookFile, next, 'utf8'); + process.stdout.write('secret-scan appended to existing pre-commit hook.\n'); + process.exit(0); +} + +const hookBody = [ + '#!/usr/bin/env sh', + '# gsd-secret-scan', + '# Pre-commit hook: scan staged files for hardcoded secrets', + hookCommand, + '', +].join('\n'); + +writeFileSync(hookFile, hookBody, 'utf8'); +try { + chmodSync(hookFile, 0o755); +} catch { + // Best effort on Windows filesystems that do not honor chmod. +} + +process.stdout.write('secret-scan pre-commit hook installed.\n'); diff --git a/scripts/link-workspace-packages.cjs b/scripts/link-workspace-packages.cjs index f1faf9875..7c203a19f 100644 --- a/scripts/link-workspace-packages.cjs +++ b/scripts/link-workspace-packages.cjs @@ -2,7 +2,8 @@ /** * link-workspace-packages.cjs * - * Creates node_modules/@gsd/* symlinks pointing to packages/* directories. + * Creates node_modules/@gsd/* and node_modules/@gsd-build/* symlinks pointing + * to shipped packages/* directories. * * During development, npm workspaces creates these automatically. But in the * published tarball, workspace packages are shipped under packages/ (via the @@ -20,27 +21,33 @@ const { resolve, join } = require('path') const root = resolve(__dirname, '..') const packagesDir = join(root, 'packages') -const nodeModulesGsd = join(root, 'node_modules', '@gsd') - -// Map directory names to package names -const packageMap = { - 'native': 'native', - 'pi-agent-core': 'pi-agent-core', - 'pi-ai': 'pi-ai', - 'pi-coding-agent': 'pi-coding-agent', - 'pi-tui': 'pi-tui', +const scopeDirs = { + '@gsd': join(root, 'node_modules', '@gsd'), + '@gsd-build': join(root, 'node_modules', '@gsd-build'), } -// Ensure @gsd scope directory exists -if (!existsSync(nodeModulesGsd)) { - mkdirSync(nodeModulesGsd, { recursive: true }) +// Map directory names to scoped package names +const packageMap = { + 'native': { scope: '@gsd', name: 'native' }, + 'pi-agent-core': { scope: '@gsd', name: 'pi-agent-core' }, + 'pi-ai': { scope: '@gsd', name: 'pi-ai' }, + 'pi-coding-agent': { scope: '@gsd', name: 'pi-coding-agent' }, + 'pi-tui': { scope: '@gsd', name: 'pi-tui' }, + 'rpc-client': { scope: '@gsd-build', name: 'rpc-client' }, +} + +for (const scopeDir of Object.values(scopeDirs)) { + if (!existsSync(scopeDir)) { + mkdirSync(scopeDir, { recursive: true }) + } } let linked = 0 let copied = 0 -for (const [dir, name] of Object.entries(packageMap)) { +for (const [dir, pkg] of Object.entries(packageMap)) { const source = join(packagesDir, dir) - const target = join(nodeModulesGsd, name) + const scopeDir = scopeDirs[pkg.scope] + const target = join(scopeDir, pkg.name) if (!existsSync(source)) continue @@ -50,7 +57,7 @@ for (const [dir, name] of Object.entries(packageMap)) { const stat = lstatSync(target) if (stat.isSymbolicLink()) { const linkTarget = readlinkSync(target) - if (resolve(join(nodeModulesGsd, linkTarget)) === source || linkTarget === source) { + if (resolve(join(scopeDir, linkTarget)) === source || linkTarget === source) { continue // Already correct } unlinkSync(target) // Wrong target, relink diff --git a/scripts/parallel-monitor.mjs b/scripts/parallel-monitor.mjs index b29109682..e3acd6545 100755 --- a/scripts/parallel-monitor.mjs +++ b/scripts/parallel-monitor.mjs @@ -42,7 +42,7 @@ import fs from 'node:fs'; import path from 'node:path'; -import { execSync } from 'node:child_process'; +import { execSync, spawn, spawnSync } from 'node:child_process'; // ─── Configuration ─────────────────────────────────────────────────────────── @@ -294,7 +294,10 @@ function findGsdLoader() { // 3. Try `which gsd` and resolve symlink try { - const bin = execSync('which gsd', { encoding: 'utf-8', timeout: 3000 }).trim(); + const pathLookup = process.platform === 'win32' ? 'where.exe' : 'which'; + const lookupArgs = ['gsd']; + const result = spawnSync(pathLookup, lookupArgs, { encoding: 'utf-8', timeout: 3000 }); + const bin = result.status === 0 ? result.stdout.trim().split(/\r?\n/)[0]?.trim() : ''; if (bin) { const realBin = fs.realpathSync(bin); const loader = path.resolve(path.dirname(realBin), '..', 'dist', 'loader.js'); @@ -309,7 +312,7 @@ const GSD_LOADER = findGsdLoader(); /** * Respawn a dead worker. Returns the new PID or null on failure. - * Uses nohup + output redirection so the child is fully detached. + * Uses a detached Node child with log file descriptors so the child is fully detached. */ function respawnWorker(mid) { const worktreeDir = path.resolve(PROJECT_ROOT, `.gsd/worktrees/${mid}`); @@ -319,41 +322,37 @@ function respawnWorker(mid) { const stdoutLog = path.resolve(PROJECT_ROOT, PARALLEL_DIR, `${mid}.stdout.log`); const stderrLog = path.resolve(PROJECT_ROOT, PARALLEL_DIR, `${mid}.stderr.log`); + let stdoutFd; + let stderrFd; try { - const env = [ - `GSD_MILESTONE_LOCK=${mid}`, - `GSD_PROJECT_ROOT=${PROJECT_ROOT}`, - `GSD_PARALLEL_WORKER=1`, - ].join(' '); - - // Use a shell script written to a temp file to avoid quoting hell - const script = [ - '#!/bin/bash', - `cd "${worktreeDir}"`, - `export GSD_MILESTONE_LOCK=${mid}`, - `export GSD_PROJECT_ROOT="${PROJECT_ROOT}"`, - `export GSD_PARALLEL_WORKER=1`, - `exec node "${GSD_LOADER}" headless --json auto > "${stdoutLog}" 2>> "${stderrLog}"`, - ].join('\n'); - - const scriptPath = path.resolve(PROJECT_ROOT, PARALLEL_DIR, `${mid}.respawn.sh`); - fs.writeFileSync(scriptPath, script, { mode: 0o755 }); - - // Launch detached via nohup - const result = execSync( - `nohup bash "${scriptPath}" > /dev/null 2>&1 & echo $!`, - { timeout: 5000, encoding: 'utf-8', cwd: worktreeDir } - ).trim(); - - // Clean up the temp script after a delay (process already forked) - setTimeout(() => { - try { fs.unlinkSync(scriptPath); } catch {} - }, 5000); - - const newPid = parseInt(result, 10); - return isNaN(newPid) ? null : newPid; + fs.mkdirSync(path.dirname(stdoutLog), { recursive: true }); + stdoutFd = fs.openSync(stdoutLog, 'a'); + stderrFd = fs.openSync(stderrLog, 'a'); + + const child = spawn(process.execPath, [GSD_LOADER, 'headless', '--json', 'auto'], { + cwd: worktreeDir, + detached: true, + env: { + ...process.env, + GSD_MILESTONE_LOCK: mid, + GSD_PROJECT_ROOT: PROJECT_ROOT, + GSD_PARALLEL_WORKER: '1', + }, + stdio: ['ignore', stdoutFd, stderrFd], + windowsHide: true, + }); + + child.unref(); + return child.pid ?? null; } catch (err) { return null; + } finally { + if (stdoutFd !== undefined) { + try { fs.closeSync(stdoutFd); } catch {} + } + if (stderrFd !== undefined) { + try { fs.closeSync(stderrFd); } catch {} + } } } diff --git a/scripts/pr-risk-check.mjs b/scripts/pr-risk-check.mjs index 18c88e02b..94b61f13b 100644 --- a/scripts/pr-risk-check.mjs +++ b/scripts/pr-risk-check.mjs @@ -20,7 +20,7 @@ import { createInterface } from 'readline'; const __dirname = dirname(fileURLToPath(import.meta.url)); const REPO_ROOT = resolve(__dirname, '..'); -const MAP_PATH = resolve(REPO_ROOT, 'docs/FILE-SYSTEM-MAP.md'); +const MAP_PATH = resolve(REPO_ROOT, 'docs/dev/FILE-SYSTEM-MAP.md'); // --------------------------------------------------------------------------- // Risk tier definitions diff --git a/scripts/prepublish-check.mjs b/scripts/prepublish-check.mjs new file mode 100644 index 000000000..c47cafbbd --- /dev/null +++ b/scripts/prepublish-check.mjs @@ -0,0 +1,19 @@ +#!/usr/bin/env node + +import { spawnSync } from 'node:child_process'; + +if (process.env.CI === 'true' || process.env.CI === '1') { + process.exit(0); +} + +const result = spawnSync('git', ['diff', '--exit-code'], { + stdio: 'inherit', + shell: process.platform === 'win32', +}); + +if (result.status === 0) { + process.exit(0); +} + +process.stderr.write('ERROR: version sync changed files — commit them before publishing\n'); +process.exit(result.status ?? 1); diff --git a/scripts/secret-scan.mjs b/scripts/secret-scan.mjs new file mode 100644 index 000000000..e8f1a5f79 --- /dev/null +++ b/scripts/secret-scan.mjs @@ -0,0 +1,184 @@ +#!/usr/bin/env node + +import { execFileSync } from 'node:child_process'; +import { existsSync, readFileSync } from 'node:fs'; + +const RED = '\x1b[0;31m'; +const YELLOW = '\x1b[1;33m'; +const NC = '\x1b[0m'; +const IGNORE_FILE = '.secretscanignore'; + +const PATTERNS = [ + { label: 'AWS Access Key', regex: /AKIA[0-9A-Z]{16}/g }, + { label: 'Generic API Key', regex: /(api[_-]?key|apikey|api[_-]?secret)[ \t]*[:=][ \t]*['"][0-9a-zA-Z_./-]{20,}['"]/gi }, + { label: 'Generic Secret', regex: /(secret|token|password|passwd|pwd|credential)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi }, + { label: 'Authorization Header', regex: /(authorization|bearer)[ \t]*[:=][ \t]*['"][^\s'"]{8,}['"]/gi }, + { label: 'Private Key', regex: /-----BEGIN\s+(RSA|DSA|EC|OPENSSH|PGP)\s+PRIVATE\s+KEY-----/g }, + { label: 'Database URL', regex: /(mysql|postgres|postgresql|mongodb|redis|amqp|mssql):\/\/[^\s'"]{8,}/gi }, + { label: 'GitHub Token', regex: /gh[pousr]_[0-9a-zA-Z]{36,}/g }, + { label: 'GitLab Token', regex: /glpat-[0-9a-zA-Z-]{20,}/g }, + { label: 'Slack Token', regex: /xox[baprs]-[0-9a-zA-Z-]{10,}/g }, + { label: 'Slack Webhook', regex: /hooks\.slack\.com\/services\/T[0-9A-Z]{8,}\/B[0-9A-Z]{8,}\/[0-9a-zA-Z]{20,}/g }, + { label: 'Google API Key', regex: /AIza[0-9A-Za-z_-]{35}/g }, + { label: 'Stripe Key', regex: /[sr]k_(live|test)_[0-9a-zA-Z]{20,}/g }, + { label: 'npm Token', regex: /npm_[0-9a-zA-Z]{36,}/g }, + { label: 'Hex Secret', regex: /(secret|key|token|password)[ \t]*[:=][ \t]*['"]?[0-9a-f]{32,}['"]?/gi }, + { label: 'Hardcoded Password', regex: /password[ \t]*[:=][ \t]*['"][^'"]{4,}['"]/gi }, +]; + +function runGit(args) { + try { + return execFileSync('git', args, { + encoding: 'utf8', + shell: process.platform === 'win32', + stdio: ['ignore', 'pipe', 'ignore'], + }); + } catch { + return ''; + } +} + +function parseArgs(argv) { + if (argv[0] === '--diff') { + return { mode: 'diff', ref: argv[1] || 'HEAD' }; + } + if (argv[0] === '--file') { + return { mode: 'file', file: argv[1] || '' }; + } + return { mode: 'staged' }; +} + +function getFiles(options) { + if (options.mode === 'diff') { + return runGit(['diff', '--name-only', '--diff-filter=ACMR', options.ref]); + } + if (options.mode === 'file') { + return options.file; + } + return runGit(['diff', '--cached', '--name-only', '--diff-filter=ACMR']); +} + +function shouldScan(file) { + const lower = file.toLowerCase(); + const skippedExtensions = [ + '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg', '.woff', '.woff2', '.ttf', '.eot', + '.zip', '.tar', '.gz', '.tgz', '.bz2', '.7z', '.rar', '.exe', '.dll', '.so', '.dylib', + '.o', '.a', '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.lock', '.map', '.node', '.wasm', + ]; + if (skippedExtensions.some((ext) => lower.endsWith(ext))) return false; + if ( + lower === '.secretscanignore' || + lower === '.gitignore' || + lower === '.gitattributes' || + lower.startsWith('license') || + lower.startsWith('changelog') || + lower.endsWith('.md') || + lower === 'package-lock.json' || + lower === 'pnpm-lock.yaml' || + lower === 'bun.lock' + ) { + return false; + } + if ( + lower.startsWith('node_modules/') || + lower.startsWith('dist/') || + lower.startsWith('coverage/') || + lower.startsWith('.gsd/') + ) { + return false; + } + if (lower.endsWith('.min.js') || lower.endsWith('.min.css')) return false; + return true; +} + +function getContent(file, mode) { + if (mode === 'staged') { + const staged = runGit(['show', `:${file}`]); + if (staged) return staged; + } + try { + return readFileSync(file, 'utf8'); + } catch { + return ''; + } +} + +function loadIgnorePatterns() { + if (!existsSync(IGNORE_FILE)) return []; + return readFileSync(IGNORE_FILE, 'utf8') + .split(/\r?\n/) + .map((line) => line.trim()) + .filter((line) => line && !line.startsWith('#')); +} + +function isIgnored(file, lineContent, ignorePatterns) { + return ignorePatterns.some((pattern) => { + const splitIndex = pattern.indexOf(':'); + if (splitIndex > 0) { + const ignoreFile = pattern.slice(0, splitIndex); + const ignoreRegex = pattern.slice(splitIndex + 1); + if (file !== ignoreFile) return false; + try { + return new RegExp(ignoreRegex, 'i').test(lineContent); + } catch { + return false; + } + } + + try { + return new RegExp(pattern, 'i').test(lineContent); + } catch { + return false; + } + }); +} + +function resetRegex(regex) { + regex.lastIndex = 0; + return regex; +} + +const options = parseArgs(process.argv.slice(2)); +const files = getFiles(options) + .split(/\r?\n/) + .map((file) => file.trim()) + .filter(Boolean); + +if (files.length === 0) { + process.stdout.write('secret-scan: no files to scan\n'); + process.exit(0); +} + +const ignorePatterns = loadIgnorePatterns(); +let findings = 0; + +for (const file of files) { + if (!shouldScan(file)) continue; + const content = getContent(file, options.mode); + if (!content) continue; + + const lines = content.split(/\r?\n/); + for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) { + const line = lines[lineIndex]; + for (const pattern of PATTERNS) { + if (!resetRegex(pattern.regex).test(line)) continue; + if (isIgnored(file, line, ignorePatterns)) continue; + + process.stdout.write(`${RED}[SECRET DETECTED]${NC} ${YELLOW}${pattern.label}${NC}\n`); + process.stdout.write(` File: ${file}:${lineIndex + 1}\n`); + process.stdout.write(` Line: ${line.slice(0, 120)}...\n\n`); + findings++; + } + } +} + +if (findings > 0) { + process.stdout.write(`${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n`); + process.stdout.write(`${RED}Found ${findings} potential secret(s) in scanned files.${NC}\n`); + process.stdout.write(`${RED}Commit blocked. Remove the secrets or add exceptions${NC}\n`); + process.stdout.write(`${RED}to .secretscanignore if these are false positives.${NC}\n`); + process.stdout.write(`${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n`); + process.exit(1); +} + +process.stdout.write('secret-scan: no secrets detected ✓\n'); diff --git a/scripts/validate-pack.js b/scripts/validate-pack.js index 3ecd195ca..b35bc1b5a 100644 --- a/scripts/validate-pack.js +++ b/scripts/validate-pack.js @@ -3,8 +3,8 @@ // Usage: npm run validate-pack (or node scripts/validate-pack.js) // Exit 0 = safe to publish, Exit 1 = broken package. -import { execSync } from 'node:child_process'; -import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { execFileSync } from 'node:child_process'; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { dirname, join, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -15,8 +15,38 @@ const ROOT = resolve(__dirname, '..'); let tarball = null; let installDir = null; +let npmCacheDir = null; +const DEFAULT_MAX_BUFFER = 50 * 1024 * 1024; + +function getNpmCommand() { + return process.platform === 'win32' ? 'npm.cmd' : 'npm'; +} + +function runNpm(args, options = {}) { + return execFileSync(getNpmCommand(), args, { + cwd: ROOT, + encoding: 'utf8', + shell: process.platform === 'win32', + stdio: ['pipe', 'pipe', 'pipe'], + maxBuffer: DEFAULT_MAX_BUFFER, + env: { + ...process.env, + npm_config_cache: npmCacheDir ?? process.env.npm_config_cache, + }, + ...options, + }); +} + +function formatBytes(bytes) { + if (bytes < 1024) return `${bytes} B`; + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`; + return `${(bytes / (1024 * 1024)).toFixed(1)} MB`; +} try { + npmCacheDir = mkdtempSync(join(tmpdir(), 'validate-pack-npm-cache-')); + mkdirSync(npmCacheDir, { recursive: true }); + // --- Guard: workspace packages must not have @gsd/* cross-deps --- console.log('==> Checking workspace packages for @gsd/* cross-deps...'); const workspaces = ['native', 'pi-agent-core', 'pi-ai', 'pi-coding-agent', 'pi-tui']; @@ -42,12 +72,10 @@ try { // --- Pack tarball --- console.log('==> Packing tarball...'); - const packOutput = execSync('npm pack --ignore-scripts', { - cwd: ROOT, - encoding: 'utf8', - stdio: ['pipe', 'pipe', 'pipe'], - }); - const tarballName = packOutput.trim().split('\n').pop(); + const packOutput = runNpm(['pack', '--json', '--ignore-scripts']); + const packEntries = JSON.parse(packOutput); + const packEntry = Array.isArray(packEntries) ? packEntries[0] : null; + const tarballName = packEntry?.filename; tarball = join(ROOT, tarballName); if (!existsSync(tarball)) { @@ -55,23 +83,29 @@ try { process.exit(1); } - const stats = execSync(`du -h "${tarball}"`, { encoding: 'utf8' }).split('\t')[0].trim(); - console.log(`==> Tarball: ${tarballName} (${stats} compressed)`); + const stats = statSync(tarball); + console.log(`==> Tarball: ${tarballName} (${formatBytes(stats.size)} compressed)`); - // --- Check critical files using tar listing --- + // --- Check critical files using npm pack metadata --- console.log('==> Checking critical files...'); - const tarList = execSync(`tar tzf "${tarball}"`, { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024 }); + const packedFiles = new Set( + Array.isArray(packEntry?.files) + ? packEntry.files.map((entry) => entry?.path).filter(Boolean) + : [], + ); const requiredFiles = [ 'dist/loader.js', 'packages/pi-coding-agent/dist/index.js', + 'packages/rpc-client/dist/index.js', + 'packages/mcp-server/dist/cli.js', 'scripts/link-workspace-packages.cjs', 'dist/web/standalone/server.js', ]; let missing = false; for (const required of requiredFiles) { - if (!tarList.includes(`package/${required}`)) { + if (!packedFiles.has(required)) { console.log(` MISSING: ${required}`); missing = true; } @@ -89,10 +123,16 @@ try { writeFileSync(join(installDir, 'package.json'), JSON.stringify({ name: 'test-install', version: '1.0.0', private: true }, null, 2)); try { - const installOutput = execSync(`npm install "${tarball}"`, { + const installOutput = execFileSync(getNpmCommand(), ['install', tarball], { cwd: installDir, encoding: 'utf8', + shell: process.platform === 'win32', stdio: ['pipe', 'pipe', 'pipe'], + maxBuffer: DEFAULT_MAX_BUFFER, + env: { + ...process.env, + npm_config_cache: npmCacheDir, + }, }); console.log(installOutput); console.log('==> Install succeeded.'); @@ -109,16 +149,19 @@ try { // node_modules/@gsd/ is never populated, causing ERR_MODULE_NOT_FOUND at runtime. console.log('==> Verifying @gsd/* workspace package resolution...'); const installedRoot = join(installDir, 'node_modules', 'gsd-pi'); - const criticalPkgs = ['pi-coding-agent']; + const criticalPackages = [ + { scope: '@gsd', name: 'pi-coding-agent' }, + { scope: '@gsd-build', name: 'rpc-client' }, + ]; let resolutionFailed = false; - for (const pkg of criticalPkgs) { - const pkgPath = join(installedRoot, 'node_modules', '@gsd', pkg); - const fallbackPath = join(installedRoot, 'packages', pkg); + for (const pkg of criticalPackages) { + const pkgPath = join(installedRoot, 'node_modules', pkg.scope, pkg.name); + const fallbackPath = join(installedRoot, 'packages', pkg.name); if (!existsSync(pkgPath)) { if (existsSync(fallbackPath)) { - console.log(` MISSING symlink/copy: node_modules/@gsd/${pkg} (packages/${pkg} exists — postinstall may not have run)`); + console.log(` MISSING symlink/copy: node_modules/${pkg.scope}/${pkg.name} (packages/${pkg.name} exists — postinstall may not have run)`); } else { - console.log(` MISSING: node_modules/@gsd/${pkg} (packages/${pkg} also absent — package is broken)`); + console.log(` MISSING: node_modules/${pkg.scope}/${pkg.name} (packages/${pkg.name} also absent — package is broken)`); } resolutionFailed = true; } @@ -133,12 +176,19 @@ try { // --- Run the binary to confirm end-to-end resolution --- console.log('==> Running installed binary (gsd -v)...'); const loaderPath = join(installedRoot, 'dist', 'loader.js'); + const bundledWorkflowMcpCliPath = join(installedRoot, 'packages', 'mcp-server', 'dist', 'cli.js'); + if (!existsSync(bundledWorkflowMcpCliPath)) { + console.log('ERROR: Bundled workflow MCP CLI missing after install.'); + console.log(` Expected: ${bundledWorkflowMcpCliPath}`); + process.exit(1); + } try { - const versionOutput = execSync(`node "${loaderPath}" -v`, { + const versionOutput = execFileSync(process.execPath, [loaderPath, '-v'], { cwd: installDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15000, + maxBuffer: DEFAULT_MAX_BUFFER, }).trim(); console.log(` gsd -v => ${versionOutput}`); if (!versionOutput.match(/^\d+\.\d+\.\d+/)) { @@ -162,4 +212,7 @@ try { if (tarball && existsSync(tarball)) { rmSync(tarball, { force: true }); } + if (npmCacheDir && existsSync(npmCacheDir)) { + rmSync(npmCacheDir, { recursive: true, force: true }); + } } diff --git a/scripts/with-env.mjs b/scripts/with-env.mjs new file mode 100644 index 000000000..a338ffb3f --- /dev/null +++ b/scripts/with-env.mjs @@ -0,0 +1,46 @@ +#!/usr/bin/env node + +import { spawn } from 'node:child_process'; + +const args = process.argv.slice(2); +const env = { ...process.env }; + +let separatorIndex = args.indexOf('--'); +let commandStart = separatorIndex >= 0 ? separatorIndex + 1 : 0; + +for (let i = 0; i < (separatorIndex >= 0 ? separatorIndex : args.length); i++) { + const arg = args[i]; + const eq = arg.indexOf('='); + if (eq <= 0) { + commandStart = i; + separatorIndex = -1; + break; + } + env[arg.slice(0, eq)] = arg.slice(eq + 1); +} + +const commandArgs = args.slice(commandStart); +if (commandArgs.length === 0) { + process.stderr.write('with-env: expected a command after environment assignments\n'); + process.exit(1); +} + +const [command, ...childArgs] = commandArgs; +const child = spawn(command, childArgs, { + stdio: 'inherit', + env, + shell: process.platform === 'win32', +}); + +child.on('exit', (code, signal) => { + if (signal) { + process.kill(process.pid, signal); + return; + } + process.exit(code ?? 0); +}); + +child.on('error', (error) => { + process.stderr.write(`with-env: failed to run ${command}: ${error.message}\n`); + process.exit(1); +}); diff --git a/src/claude-cli-check.ts b/src/claude-cli-check.ts new file mode 100644 index 000000000..69a70037a --- /dev/null +++ b/src/claude-cli-check.ts @@ -0,0 +1,37 @@ +// GSD2 — Claude CLI binary detection for onboarding +// Lightweight check used at onboarding time (before extensions load). +// The full readiness check with caching lives in the claude-code-cli extension. + +import { execFileSync } from 'node:child_process' + +/** + * Check if the `claude` binary is installed (regardless of auth state). + */ +export function isClaudeBinaryInstalled(): boolean { + try { + execFileSync('claude', ['--version'], { timeout: 5_000, stdio: 'pipe' }) + return true + } catch { + return false + } +} + +/** + * Check if the `claude` CLI is installed AND authenticated. + */ +export function isClaudeCliReady(): boolean { + try { + execFileSync('claude', ['--version'], { timeout: 5_000, stdio: 'pipe' }) + } catch { + return false + } + + try { + const output = execFileSync('claude', ['auth', 'status'], { timeout: 5_000, stdio: 'pipe' }) + .toString() + .toLowerCase() + return !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output)) + } catch { + return false + } +} diff --git a/src/cli.ts b/src/cli.ts index a5b255fa9..08e1e0452 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -16,11 +16,14 @@ import { agentDir, sessionsDir, authFilePath } from './app-paths.js' import { initResources, buildResourceLoader, getNewerManagedResourceVersion } from './resource-loader.js' import { ensureManagedTools } from './tool-bootstrap.js' import { loadStoredEnvKeys } from './wizard.js' -import { getPiDefaultModelAndProvider, migratePiCredentials } from './pi-migration.js' +import { migratePiCredentials } from './pi-migration.js' +import { validateConfiguredModel } from './startup-model-validation.js' +import { shouldMigrateAnthropicToClaudeCode } from './provider-migrations.js' import { shouldRunOnboarding, runOnboarding } from './onboarding.js' import chalk from 'chalk' import { checkForUpdates } from './update-check.js' import { printHelp, printSubcommandHelp } from './help-text.js' +import { applySecurityOverrides } from './security-overrides.js' import { parseCliArgs as parseWebCliArgs, runWebCliBranch, @@ -170,6 +173,7 @@ const hasSubcommand = cliFlags.messages.length > 0 if (!process.stdin.isTTY && !isPrintMode && !hasSubcommand && !cliFlags.listModels && !cliFlags.web) { process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n') process.stderr.write('[gsd] Non-interactive alternatives:\n') + process.stderr.write('[gsd] gsd auto Auto-mode (pipeable, no TUI)\n') process.stderr.write('[gsd] gsd --print "your message" Single-shot prompt\n') process.stderr.write('[gsd] gsd --mode rpc JSON-RPC over stdin/stdout\n') process.stderr.write('[gsd] gsd --mode mcp MCP server over stdin/stdout\n') @@ -295,11 +299,32 @@ if (cliFlags.messages[0] === 'sessions') { // `gsd headless` — run auto-mode without TUI if (cliFlags.messages[0] === 'headless') { await ensureRtkBootstrap() + // Sync bundled resources before headless runs (#3471). Without this, + // headless-query loads from src/resources/ while auto/interactive load + // from ~/.gsd/agent/extensions/ — different extension copies diverge. + initResources(agentDir) const { runHeadless, parseHeadlessArgs } = await import('./headless.js') await runHeadless(parseHeadlessArgs(process.argv)) process.exit(0) } +// `gsd auto [args...]` — shorthand for `gsd headless auto [args...]` (#2732) +// Without this, `gsd auto` falls through to the interactive TUI which hangs +// when stdin/stdout are piped (non-TTY environments). +if (cliFlags.messages[0] === 'auto') { + await ensureRtkBootstrap() + const { runHeadless, parseHeadlessArgs } = await import('./headless.js') + // Rewrite argv so parseHeadlessArgs sees: [node, gsd, headless, auto, ...rest] + const rewrittenArgv = [ + process.argv[0], + process.argv[1], + 'headless', + ...cliFlags.messages, // ['auto', ...extra args] + ] + await runHeadless(parseHeadlessArgs(rewrittenArgv)) + process.exit(0) +} + // Pi's tool bootstrap can mis-detect already-installed fd/rg on some systems // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code. // Provision local managed binaries first so Pi sees them without probing PATH. @@ -317,7 +342,8 @@ const modelsJsonPath = resolveModelsJsonPath() const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath) markStartup('ModelRegistry') -const settingsManager = SettingsManager.create(agentDir) +const settingsManager = SettingsManager.create(process.cwd(), agentDir) +applySecurityOverrides(settingsManager) markStartup('SettingsManager.create') // Run onboarding wizard on first launch (no LLM provider configured) @@ -391,42 +417,6 @@ if (cliFlags.listModels !== undefined) { process.exit(0) } -// Validate configured model on startup — catches stale settings from prior installs -// (e.g. grok-2 which no longer exists) and fresh installs with no settings. -// Only resets the default when the configured model no longer exists in the registry; -// never overwrites a valid user choice. -const configuredProvider = settingsManager.getDefaultProvider() -const configuredModel = settingsManager.getDefaultModel() -const allModels = modelRegistry.getAll() -const availableModels = modelRegistry.getAvailable() -const configuredExists = configuredProvider && configuredModel && - allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel) -const configuredAvailable = configuredProvider && configuredModel && - availableModels.some((m) => m.provider === configuredProvider && m.id === configuredModel) - -if (!configuredModel || !configuredExists) { - // Model not configured at all, or removed from registry — pick a fallback. - // Only fires when the model is genuinely unknown (not just temporarily unavailable). - const piDefault = getPiDefaultModelAndProvider() - const preferred = - (piDefault - ? availableModels.find((m) => m.provider === piDefault.provider && m.id === piDefault.model) - : undefined) || - availableModels.find((m) => m.provider === 'openai' && m.id === 'gpt-5.4') || - availableModels.find((m) => m.provider === 'openai') || - availableModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-opus-4-6') || - availableModels.find((m) => m.provider === 'anthropic' && m.id.includes('opus')) || - availableModels.find((m) => m.provider === 'anthropic') || - availableModels[0] - if (preferred) { - settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id) - } -} - -if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) { - settingsManager.setDefaultThinkingLevel('off') -} - // GSD always uses quiet startup — the gsd extension renders its own branded header if (!settingsManager.getQuietStartup()) { settingsManager.setQuietStartup(true) @@ -468,20 +458,68 @@ if (isPrintMode) { await resourceLoader.reload() markStartup('resourceLoader.reload') - const { session, extensionsResult } = await createAgentSession({ + const { session, extensionsResult, modelFallbackMessage } = await createAgentSession({ authStorage, modelRegistry, settingsManager, sessionManager, resourceLoader, + isClaudeCodeReady: () => modelRegistry.isProviderRequestReady('claude-code'), }) markStartup('createAgentSession') + // Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772). + // Anthropic blocks third-party apps from using subscription quotas — routing through + // the local claude CLI binary is TOS-compliant. + if (shouldMigrateAnthropicToClaudeCode({ + authStorage, + isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'), + defaultProvider: settingsManager.getDefaultProvider(), + })) { + const currentModelId = settingsManager.getDefaultModel() + if (currentModelId) { + const ccModel = modelRegistry.find('claude-code', currentModelId) + if (ccModel) { + try { + await session.setModel(ccModel) + // Only persist after successful session switch to avoid desync + settingsManager.setDefaultModelAndProvider('claude-code', currentModelId) + } catch { + // claude-code provider not ready — leave both session and settings unchanged + } + } + } + } + + // Validate configured model AFTER extensions have registered their models (#2626). + // Before this, extension-provided models (e.g. claude-code/*) were not yet in the + // registry, causing the user's valid choice to be silently overwritten. + validateConfiguredModel(modelRegistry, settingsManager) + + // Re-apply the validated model to the session only when findInitialModel() used a + // fallback (not when restoring an existing session's model). This prevents silently + // overriding the persisted model of resumed conversations (#3534). + if (modelFallbackMessage) { + const validatedProvider = settingsManager.getDefaultProvider() + const validatedModelId = settingsManager.getDefaultModel() + if (validatedProvider && validatedModelId) { + const correctModel = modelRegistry.getAvailable() + .find((m) => m.provider === validatedProvider && m.id === validatedModelId) + if (correctModel) { + try { + await session.setModel(correctModel) + } catch { + // Provider not ready — leave session on its current model + } + } + } + } + if (extensionsResult.errors.length > 0) { for (const err of extensionsResult.errors) { // Downgrade conflicts with built-in tools to warnings (#1347) - const isSuperseded = err.error.includes("supersedes"); - const prefix = isSuperseded ? "Extension conflict" : "Extension load error"; + const isConflict = err.error.includes("supersedes") || err.error.includes("conflicts with"); + const prefix = isConflict ? "Extension conflict" : "Extension load error"; process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`) } } @@ -565,6 +603,20 @@ if (!cliFlags.worktree && !isPrintMode) { } catch { /* non-fatal */ } } +// --------------------------------------------------------------------------- +// Auto-redirect: `gsd auto` with piped stdout → headless mode (#2732) +// When stdout is not a TTY (e.g. `gsd auto | cat`, `gsd auto > file`), +// the TUI cannot render and the process hangs. Redirect to headless mode +// which handles non-interactive output gracefully. +// --------------------------------------------------------------------------- +if (cliFlags.messages[0] === 'auto' && !process.stdout.isTTY) { + await ensureRtkBootstrap() + const { runHeadless, parseHeadlessArgs } = await import('./headless.js') + process.stderr.write('[gsd] stdout is not a terminal — running auto-mode in headless mode.\n') + await runHeadless(parseHeadlessArgs(['node', 'gsd', 'headless', ...cliFlags.messages.slice(1)])) + process.exit(0) +} + // --------------------------------------------------------------------------- // Interactive mode — normal TTY session // --------------------------------------------------------------------------- @@ -602,19 +654,67 @@ const resourceLoadPromise = resourceLoader.reload() await resourceLoadPromise markStartup('resourceLoader.reload') -const { session, extensionsResult } = await createAgentSession({ +const { session, extensionsResult, modelFallbackMessage: interactiveFallbackMsg } = await createAgentSession({ authStorage, modelRegistry, settingsManager, sessionManager, resourceLoader, + isClaudeCodeReady: () => modelRegistry.isProviderRequestReady('claude-code'), }) markStartup('createAgentSession') +// Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772). +// Anthropic blocks third-party apps from using subscription quotas — routing through +// the local claude CLI binary is TOS-compliant. +if (shouldMigrateAnthropicToClaudeCode({ + authStorage, + isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'), + defaultProvider: settingsManager.getDefaultProvider(), +})) { + const currentModelId = settingsManager.getDefaultModel() + if (currentModelId) { + const ccModel = modelRegistry.find('claude-code', currentModelId) + if (ccModel) { + try { + await session.setModel(ccModel) + // Only persist after successful session switch to avoid desync + settingsManager.setDefaultModelAndProvider('claude-code', currentModelId) + } catch { + // claude-code provider not ready — leave both session and settings unchanged + } + } + } +} + +// Validate configured model AFTER extensions have registered their models (#2626). +// Before this, extension-provided models (e.g. claude-code/*) were not yet in the +// registry, causing the user's valid choice to be silently overwritten. +validateConfiguredModel(modelRegistry, settingsManager) + +// Re-apply the validated model to the session only when findInitialModel() used a +// fallback (not when restoring an existing session's model). This prevents silently +// overriding the persisted model of resumed conversations (#3534). +if (interactiveFallbackMsg) { + const validatedProvider = settingsManager.getDefaultProvider() + const validatedModelId = settingsManager.getDefaultModel() + if (validatedProvider && validatedModelId) { + const correctModel = modelRegistry.getAvailable() + .find((m) => m.provider === validatedProvider && m.id === validatedModelId) + if (correctModel) { + try { + await session.setModel(correctModel) + } catch { + // Provider not ready — leave session on its current model + } + } + } +} + if (extensionsResult.errors.length > 0) { for (const err of extensionsResult.errors) { - const isSuperseded = err.error.includes("supersedes"); - const prefix = isSuperseded ? "Extension conflict" : "Extension load error"; + const isConflict = err.error.includes("supersedes") || err.error.includes("conflicts with"); + const prefix = isConflict ? "Extension conflict" : "Extension load error"; process.stderr.write(`[gsd] ${prefix}: ${err.error}\n`) } } @@ -662,14 +762,21 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) { } } -if (!process.stdin.isTTY) { - process.stderr.write('[gsd] Error: Interactive mode requires a terminal (TTY).\n') +if (!process.stdin.isTTY || !process.stdout.isTTY) { + const missing = !process.stdin.isTTY && !process.stdout.isTTY + ? 'stdin and stdout are' + : !process.stdin.isTTY + ? 'stdin is' + : 'stdout is' + process.stderr.write(`[gsd] Error: Interactive mode requires a terminal (TTY) but ${missing} not a TTY.\n`) process.stderr.write('[gsd] Non-interactive alternatives:\n') + process.stderr.write('[gsd] gsd auto Auto-mode (pipeable, no TUI)\n') process.stderr.write('[gsd] gsd --print "your message" Single-shot prompt\n') process.stderr.write('[gsd] gsd --web [path] Browser-only web mode\n') process.stderr.write('[gsd] gsd --mode rpc JSON-RPC over stdin/stdout\n') process.stderr.write('[gsd] gsd --mode mcp MCP server over stdin/stdout\n') process.stderr.write('[gsd] gsd --mode text "message" Text output mode\n') + process.stderr.write('[gsd] gsd headless Auto-mode without TUI\n') process.exit(1) } @@ -677,10 +784,17 @@ if (!process.stdin.isTTY) { // Skip when the first-run banner was already printed in loader.ts (prevents double banner). if (!process.env.GSD_FIRST_RUN_BANNER) { const { printWelcomeScreen } = await import('./welcome-screen.js') + let remoteChannel: string | undefined + try { + const { resolveRemoteConfig } = await import('./resources/extensions/remote-questions/config.js') + const rc = resolveRemoteConfig() + if (rc) remoteChannel = rc.channel + } catch { /* non-fatal */ } printWelcomeScreen({ version: process.env.GSD_VERSION || '0.0.0', modelName: settingsManager.getDefaultModel() || undefined, provider: settingsManager.getDefaultProvider() || undefined, + remoteChannel, }) } diff --git a/src/headless-query.ts b/src/headless-query.ts index c9aa6ae2b..cc7c134c3 100644 --- a/src/headless-query.ts +++ b/src/headless-query.ts @@ -16,12 +16,22 @@ import { createJiti } from '@mariozechner/jiti' import { fileURLToPath } from 'node:url' +import { join } from 'node:path' +import { homedir } from 'node:os' import type { GSDState } from './resources/extensions/gsd/types.js' import { resolveBundledSourceResource } from './bundled-resource-path.js' const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false }) +// Resolve extensions from the synced agent directory so headless-query +// loads the same extension copy as interactive/auto modes (#3471). +// Falls back to bundled source for source-tree dev workflows. +const agentExtensionsDir = join(process.env.GSD_AGENT_DIR || join(homedir(), '.gsd', 'agent'), 'extensions', 'gsd') +const { existsSync } = await import('node:fs') +const useAgentDir = existsSync(join(agentExtensionsDir, 'state.ts')) const gsdExtensionPath = (...segments: string[]) => - resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments) + useAgentDir + ? join(agentExtensionsDir, ...segments) + : resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments) async function loadExtensionModules() { const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {}) as any diff --git a/src/headless.ts b/src/headless.ts index 503ca9afd..cd0d86124 100644 --- a/src/headless.ts +++ b/src/headless.ts @@ -259,7 +259,9 @@ async function runHeadlessOnce(options: HeadlessOptions, restartCount: number): // per-unit timeout via auto-supervisor. Disable the overall timeout unless the // user explicitly set --timeout. const isAutoMode = options.command === 'auto' - const isMultiTurnCommand = options.command === 'auto' || options.command === 'next' + // discuss and plan are multi-turn: they involve multiple question rounds, + // codebase scanning, and artifact writing before the workflow completes (#3547). + const isMultiTurnCommand = options.command === 'auto' || options.command === 'next' || options.command === 'discuss' || options.command === 'plan' if (isAutoMode && options.timeout === 300_000) { options.timeout = 0 } diff --git a/src/help-text.ts b/src/help-text.ts index 4976c0591..ab534ae62 100644 --- a/src/help-text.ts +++ b/src/help-text.ts @@ -3,12 +3,15 @@ const SUBCOMMAND_HELP: Record = { 'Usage: gsd config', '', 'Re-run the interactive setup wizard to configure:', - ' - LLM provider (Anthropic, OpenAI, Google, etc.)', + ' - LLM provider (Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, etc.)', ' - Web search provider (Brave, Tavily, built-in)', ' - Remote questions (Discord, Slack, Telegram)', ' - Tool API keys (Context7, Jina, Groq)', '', 'All steps are skippable and can be changed later with /login or /search-provider.', + '', + 'For detailed provider setup instructions (OpenRouter, Ollama, LM Studio, vLLM,', + 'and other OpenAI-compatible endpoints), see docs/providers.md.', ].join('\n'), update: [ @@ -169,6 +172,7 @@ export function printHelp(version: string): void { process.stdout.write(' update Update GSD to the latest version\n') process.stdout.write(' sessions List and resume a past session\n') process.stdout.write(' worktree Manage worktrees (list, merge, clean, remove)\n') + process.stdout.write(' auto [args] Run auto-mode without TUI (pipeable)\n') process.stdout.write(' headless [cmd] [args] Run /gsd commands without TUI (default: auto)\n') process.stdout.write('\nRun gsd --help for subcommand-specific help.\n') } diff --git a/src/loader.ts b/src/loader.ts index 1d3ce46a2..13e1605b4 100644 --- a/src/loader.ts +++ b/src/loader.ts @@ -110,6 +110,11 @@ if (!existsSync(appRoot)) { // GSD_CODING_AGENT_DIR — tells pi's getAgentDir() to return ~/.gsd/agent/ instead of ~/.gsd/agent/ process.env.GSD_CODING_AGENT_DIR = agentDir +// GSD_PKG_ROOT — absolute path to gsd-pi package root. Used by deployed extensions +// (e.g. auto.ts resume path) to import modules like resource-loader.js that live +// in the package tree, not in the deployed ~/.gsd/agent/ tree. +process.env.GSD_PKG_ROOT = gsdRoot + // RTK environment — make ~/.gsd/agent/bin visible to all child-process paths, // not just the bash tool, and force-disable RTK telemetry for GSD-managed use. applyRtkProcessEnv(process.env) diff --git a/src/mcp-server.ts b/src/mcp-server.ts index d3ea233fe..7486f60fa 100644 --- a/src/mcp-server.ts +++ b/src/mcp-server.ts @@ -19,6 +19,10 @@ export interface McpToolDef { // MCP SDK subpath imports use wildcard exports (./*) that NodeNext resolves // at runtime but TypeScript cannot statically type-check. We construct the // specifiers dynamically so tsc treats them as `any`. +// +// Use explicit .js subpaths for modules that are loaded dynamically at runtime. +// Recent Node / SDK combinations do not reliably resolve the extensionless +// wildcard targets for `server/stdio` and `types` (#3914). const MCP_PKG = '@modelcontextprotocol/sdk' /** @@ -42,8 +46,8 @@ export async function startMcpServer(options: { const { tools, version = '0.0.0' } = options const serverMod = await import(`${MCP_PKG}/server`) - const stdioMod = await import(`${MCP_PKG}/server/stdio`) - const typesMod = await import(`${MCP_PKG}/types`) + const stdioMod = await import(`${MCP_PKG}/server/stdio.js`) + const typesMod = await import(`${MCP_PKG}/types.js`) const Server = serverMod.Server const StdioServerTransport = stdioMod.StdioServerTransport diff --git a/src/onboarding.ts b/src/onboarding.ts index 93e39d0f5..d51d408dc 100644 --- a/src/onboarding.ts +++ b/src/onboarding.ts @@ -16,6 +16,7 @@ import { dirname, join } from 'node:path' import type { AuthStorage } from '@gsd/pi-coding-agent' import { renderLogo } from './logo.js' import { agentDir } from './app-paths.js' +import { isClaudeCliReady } from './claude-cli-check.js' // ─── Types ──────────────────────────────────────────────────────────────────── @@ -64,6 +65,7 @@ const TOOL_KEYS: ToolKeyConfig[] = [ const LLM_PROVIDER_IDS = [ 'anthropic', 'anthropic-vertex', + 'claude-code', 'openai', 'github-copilot', 'openai-codex', @@ -74,6 +76,7 @@ const LLM_PROVIDER_IDS = [ 'xai', 'openrouter', 'mistral', + 'ollama', 'ollama-cloud', 'custom-openai', ] @@ -85,13 +88,13 @@ const API_KEY_PREFIXES: Record = { } const OTHER_PROVIDERS = [ - { value: 'google', label: 'Google (Gemini)' }, - { value: 'groq', label: 'Groq' }, - { value: 'xai', label: 'xAI (Grok)' }, - { value: 'openrouter', label: 'OpenRouter' }, - { value: 'mistral', label: 'Mistral' }, + { value: 'google', label: 'Google (Gemini)', hint: 'aistudio.google.com/app/apikey' }, + { value: 'groq', label: 'Groq', hint: 'console.groq.com/keys' }, + { value: 'xai', label: 'xAI (Grok)', hint: 'console.x.ai' }, + { value: 'openrouter', label: 'OpenRouter', hint: '200+ models — openrouter.ai/keys' }, + { value: 'mistral', label: 'Mistral', hint: 'console.mistral.ai/api-keys' }, { value: 'ollama-cloud', label: 'Ollama Cloud' }, - { value: 'custom-openai', label: 'Custom (OpenAI-compatible)' }, + { value: 'custom-openai', label: 'Custom (OpenAI-compatible)', hint: 'Ollama, LM Studio, vLLM, proxies — see docs/providers.md' }, ] // ─── Dynamic imports ────────────────────────────────────────────────────────── @@ -292,8 +295,16 @@ async function runLlmStep(p: ClackModule, pc: PicoModule, authStorage: AuthStora authOptions.push({ value: 'keep', label: `Keep current (${existingAuth})`, hint: 'already configured' }) } + // Show Claude Code CLI option at the top when the CLI is installed and authenticated (#3772). + // This is the only TOS-compliant path for Anthropic subscription users. + if (isClaudeCliReady()) { + authOptions.push( + { value: 'claude-cli', label: 'Use Claude Code CLI', hint: 'recommended — uses your existing Claude subscription' }, + ) + } + authOptions.push( - { value: 'browser', label: 'Sign in with your browser', hint: 'recommended — same login as claude.ai / ChatGPT' }, + { value: 'browser', label: 'Sign in with your browser', hint: 'GitHub Copilot, ChatGPT, Google, etc.' }, { value: 'api-key', label: 'Paste an API key', hint: 'from your provider dashboard' }, { value: 'skip', label: 'Skip for now', hint: 'use /login inside GSD later' }, ) @@ -306,12 +317,23 @@ async function runLlmStep(p: ClackModule, pc: PicoModule, authStorage: AuthStora if (p.isCancel(method) || method === 'skip') return false if (method === 'keep') return true + // ── Claude Code CLI path (#3772) ──────────────────────────────────────── + if (method === 'claude-cli') { + p.log.success('Claude Code CLI detected — routing through local CLI (TOS-compliant)') + p.log.info('Your Claude subscription will be used for inference. No API key needed.') + // Store sentinel so hasAuth('claude-code') returns true on future boots + authStorage.set('claude-code', { type: 'api_key', key: 'cli' }) + return true + } + // ── Step 2: Which provider? ────────────────────────────────────────────── if (method === 'browser') { + // Anthropic OAuth is removed from browser auth — it violates Anthropic TOS for + // third-party apps (#3772). Anthropic subscription users should use the Claude + // Code CLI path (shown above when CLI is installed) or paste an API key. const provider = await p.select({ message: 'Choose provider', options: [ - { value: 'anthropic', label: 'Anthropic (Claude)', hint: 'recommended' }, { value: 'github-copilot', label: 'GitHub Copilot' }, { value: 'openai-codex', label: 'ChatGPT Plus/Pro (Codex)' }, { value: 'google-gemini-cli', label: 'Google Gemini CLI' }, @@ -335,6 +357,9 @@ async function runLlmStep(p: ClackModule, pc: PicoModule, authStorage: AuthStora if (provider === 'custom-openai') { return await runCustomOpenAIFlow(p, pc, authStorage) } + if (provider === 'ollama') { + return await runOllamaLocalFlow(p, pc, authStorage) + } const label = provider === 'anthropic' ? 'Anthropic' : provider === 'openai' ? 'OpenAI' : OTHER_PROVIDERS.find(op => op.value === provider)?.label ?? String(provider) @@ -441,6 +466,61 @@ async function runApiKeyFlow( authStorage.set(providerId, { type: 'api_key', key: trimmed }) p.log.success(`API key saved for ${pc.green(providerLabel)}`) + + // Provider-specific post-setup hints + if (providerId === 'openrouter') { + p.log.info(`Use ${pc.cyan('/model')} inside GSD to pick an OpenRouter model.`) + p.log.info(`To add custom models or control routing, see ${pc.dim('docs/providers.md#openrouter')}`) + } + + return true +} + +// ─── Ollama Local Flow ─────────────────────────────────────────────────────── + +async function runOllamaLocalFlow( + p: ClackModule, + pc: PicoModule, + authStorage: AuthStorage, +): Promise { + const host = process.env.OLLAMA_HOST || 'http://localhost:11434' + + const s = p.spinner() + s.start(`Checking Ollama at ${host}...`) + + try { + const controller = new AbortController() + const timeout = setTimeout(() => controller.abort(), 3000) + const response = await fetch(host, { signal: controller.signal }) + clearTimeout(timeout) + + if (response.ok) { + s.stop(`Ollama is running at ${pc.green(host)}`) + // Store a placeholder so the provider is recognized as authenticated + authStorage.set('ollama', { type: 'api_key', key: 'ollama' }) + p.log.success(`${pc.green('Ollama (Local)')} configured — no API key needed`) + p.log.info(pc.dim('Models are discovered automatically from your local Ollama instance.')) + return true + } else { + s.stop('Ollama check failed') + p.log.warn(`Ollama responded with status ${response.status} at ${host}`) + } + } catch { + s.stop('Ollama not detected') + p.log.warn(`Could not reach Ollama at ${host}`) + p.log.info(pc.dim('Install Ollama from https://ollama.com and run "ollama serve"')) + p.log.info(pc.dim('Set OLLAMA_HOST if using a non-default address.')) + } + + // Even if not reachable now, save the config — the extension will detect it at runtime + const proceed = await p.confirm({ + message: 'Save Ollama as your provider anyway? (it will auto-detect when running)', + }) + + if (p.isCancel(proceed) || !proceed) return false + + authStorage.set('ollama', { type: 'api_key', key: 'ollama' }) + p.log.success(`${pc.green('Ollama (Local)')} saved — models will appear when Ollama is running`) return true } @@ -451,10 +531,12 @@ async function runCustomOpenAIFlow( pc: PicoModule, authStorage: AuthStorage, ): Promise { + p.log.info(pc.dim('Common endpoints:\n Ollama: http://localhost:11434/v1\n LM Studio: http://localhost:1234/v1\n vLLM: http://localhost:8000/v1')) + // Prompt for base URL const baseUrl = await p.text({ message: 'Base URL of your OpenAI-compatible endpoint:', - placeholder: 'https://my-proxy.example.com/v1', + placeholder: 'http://localhost:11434/v1', validate: (val) => { const trimmed = val?.trim() if (!trimmed) return 'Base URL is required' @@ -535,6 +617,8 @@ async function runCustomOpenAIFlow( p.log.success(`Custom endpoint saved: ${pc.green(trimmedUrl)}`) p.log.info(`Model: ${pc.cyan(trimmedModelId)}`) p.log.info(`Config written to ${pc.dim(modelsJsonPath)}`) + p.log.info(`If you get role or streaming errors, add compat settings to models.json.`) + p.log.info(`See ${pc.dim('docs/providers.md#common-pitfalls')} for details.`) return true } diff --git a/src/provider-migrations.ts b/src/provider-migrations.ts new file mode 100644 index 000000000..1e61c69df --- /dev/null +++ b/src/provider-migrations.ts @@ -0,0 +1,34 @@ +import type { AuthStorage } from "@gsd/pi-coding-agent" + +type AnthropicMigrationDeps = { + authStorage: Pick + isClaudeCodeReady: boolean + defaultProvider: string | undefined + env?: NodeJS.ProcessEnv +} + +export function hasDirectAnthropicApiKey( + authStorage: Pick, + env: NodeJS.ProcessEnv = process.env, +): boolean { + if ((env.ANTHROPIC_API_KEY ?? "").trim()) { + return true + } + + return authStorage.getCredentialsForProvider("anthropic").some((credential: any) => + credential?.type === "api_key" && typeof credential?.key === "string" && credential.key.trim().length > 0, + ) +} + +export function shouldMigrateAnthropicToClaudeCode({ + authStorage, + isClaudeCodeReady, + defaultProvider, + env = process.env, +}: AnthropicMigrationDeps): boolean { + if (!isClaudeCodeReady || defaultProvider !== "anthropic") { + return false + } + + return !hasDirectAnthropicApiKey(authStorage, env) +} diff --git a/src/resource-loader.ts b/src/resource-loader.ts index 690a2e788..901d8e1b1 100644 --- a/src/resource-loader.ts +++ b/src/resource-loader.ts @@ -1,4 +1,4 @@ -import { DefaultResourceLoader } from '@gsd/pi-coding-agent' +import { DefaultResourceLoader, sortExtensionPaths } from '@gsd/pi-coding-agent' import { createHash } from 'node:crypto' import { homedir } from 'node:os' import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readlinkSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs' @@ -87,9 +87,13 @@ function writeManagedResourceManifest(agentDir: string): void { installedExtensionDirs = entries .filter(e => e.isDirectory()) .filter(e => { - // Only track directories that are actual extensions (contain index.js or index.ts) + // Track directories that are actual extensions — identified by an + // index.js/index.ts entry point OR an extension-manifest.json (e.g. + // remote-questions which uses mod.ts instead of index.ts). const dirPath = join(bundledExtensionsDir, e.name) - return existsSync(join(dirPath, 'index.js')) || existsSync(join(dirPath, 'index.ts')) + return existsSync(join(dirPath, 'index.js')) + || existsSync(join(dirPath, 'index.ts')) + || existsSync(join(dirPath, 'extension-manifest.json')) }) .map(e => e.name) } @@ -369,6 +373,16 @@ function pruneRemovedBundledExtensions( } } + // Sweep-based: also remove any installed extension subdirectory not in the current bundle, + // even if it was never tracked in the manifest (e.g. installed by a pre-manifest version). + try { + if (existsSync(extensionsDir)) { + for (const e of readdirSync(extensionsDir, { withFileTypes: true })) { + if (e.isDirectory()) removeDirIfStale(e.name) + } + } + } catch { /* non-fatal */ } + // Always remove known stale files regardless of manifest state. // These were installed by pre-manifest versions so they may not appear in // installedExtensionRootFiles even when a manifest exists. @@ -399,12 +413,14 @@ export function initResources(agentDir: string): void { const currentVersion = getBundledGsdVersion() const manifest = readManagedResourceManifest(agentDir) + const extensionsDir = join(agentDir, 'extensions') // Always prune root-level extension files that were removed from the bundle. // This is cheap (a few existence checks + at most one rmSync) and must run // unconditionally so that stale files left by a previous version are cleaned // up even when the version/hash match causes the full sync to be skipped. pruneRemovedBundledExtensions(manifest, agentDir) + pruneStaleSiblingFiles(bundledExtensionsDir, extensionsDir) // Ensure ~/.gsd/agent/node_modules symlinks to GSD's node_modules on EVERY // launch, not just during resource syncs. A stale/broken symlink makes ALL @@ -421,7 +437,7 @@ export function initResources(agentDir: string): void { if (manifest && manifest.gsdVersion === currentVersion) { // Version matches — check content fingerprint for same-version staleness. const currentHash = computeResourceFingerprint() - const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(join(agentDir, 'extensions')) + const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(extensionsDir, bundledExtensionsDir) if (manifest.contentHash && manifest.contentHash === currentHash && !hasStaleExtensionFiles) { return } @@ -557,12 +573,26 @@ function migrateSkillsToEcosystemDir(agentDir: string): void { } } -export function hasStaleCompiledExtensionSiblings(extensionsDir: string): boolean { +export function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir: string = bundledExtensionsDir): boolean { if (!existsSync(extensionsDir)) return false + const sourceFiles = existsSync(sourceDir) + ? new Set( + readdirSync(sourceDir, { withFileTypes: true }) + .filter((entry) => entry.isFile()) + .map((entry) => entry.name), + ) + : new Set() for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) { - if (!entry.isFile() || !entry.name.endsWith('.ts')) continue - const jsName = entry.name.replace(/\.ts$/, '.js') - if (existsSync(join(extensionsDir, jsName))) { + if (!entry.isFile()) continue + if (!entry.name.endsWith('.ts') && !entry.name.endsWith('.js')) continue + + const siblingName = entry.name.endsWith('.ts') + ? entry.name.replace(/\.ts$/, '.js') + : entry.name.replace(/\.js$/, '.ts') + + if (!existsSync(join(extensionsDir, siblingName))) continue + if (sourceFiles.has(entry.name) && sourceFiles.has(siblingName)) continue + if (sourceFiles.has(entry.name) || sourceFiles.has(siblingName)) { return true } } @@ -602,6 +632,22 @@ export function buildResourceLoader(agentDir: string): DefaultResourceLoader { return new DefaultResourceLoader({ agentDir, additionalExtensionPaths: piExtensionPaths, - bundledExtensionNames: bundledKeys, + bundledExtensionKeys: bundledKeys, + extensionPathsTransform: (paths: string[]) => { + // 1. Filter community extensions through the GSD registry + const filteredPaths = paths.filter((entryPath) => { + const manifest = readManifestFromEntryPath(entryPath) + if (!manifest) return true // no manifest = always load + return isExtensionEnabled(registry, manifest.id) + }) + + // 2. Sort in topological dependency order + const { sortedPaths, warnings } = sortExtensionPaths(filteredPaths) + + return { + paths: sortedPaths, + diagnostics: warnings.map((w) => w.message), + } + }, } as ConstructorParameters[0]) } diff --git a/src/resources/GSD-WORKFLOW.md b/src/resources/GSD-WORKFLOW.md index 8c819643f..ef0759969 100644 --- a/src/resources/GSD-WORKFLOW.md +++ b/src/resources/GSD-WORKFLOW.md @@ -18,7 +18,8 @@ Read these files in order and act on what they say: 3. **`.gsd/milestones//M###-CONTEXT.md`** — Milestone-level project decisions, reference paths, constraints. Read this before doing implementation work. 4. If a slice is active and has one, read **`S##-CONTEXT.md`** — Slice-specific decisions and constraints. 5. If a slice is active, read its **`S##-PLAN.md`** — Which tasks exist? Which are done? -6. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there. +6. If `.gsd/CODEBASE.md` exists, skim it for fast structural orientation before broad code exploration. +7. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there. Then do the thing `STATE.md` says to do next. @@ -44,6 +45,7 @@ All artifacts live in `.gsd/` at the project root: .gsd/ STATE.md # Dashboard — always read first (derived cache; runtime, gitignored) DECISIONS.md # Append-only decisions register + CODEBASE.md # Generated codebase map cache (auto-refreshed by GSD) milestones/ M001/ M001-ROADMAP.md # Milestone plan (checkboxes = state) diff --git a/src/resources/agents/researcher.md b/src/resources/agents/researcher.md index 3c34ea0e3..ae8fba5da 100644 --- a/src/resources/agents/researcher.md +++ b/src/resources/agents/researcher.md @@ -1,7 +1,7 @@ --- name: researcher description: Web researcher that finds and synthesizes current information using Brave Search -tools: web_search, bash +tools: search-the-web, bash --- You are a web researcher. You find current, accurate information using web search and synthesize it into a clear, well-structured report. diff --git a/src/resources/extensions/ask-user-questions.ts b/src/resources/extensions/ask-user-questions.ts index c227c1ad4..3cb7e2ae1 100644 --- a/src/resources/extensions/ask-user-questions.ts +++ b/src/resources/extensions/ask-user-questions.ts @@ -72,6 +72,100 @@ const AskUserQuestionsParams = Type.Object({ }), }); +// ─── Per-turn deduplication ────────────────────────────────────────────────── +// Prevents duplicate question dispatches (especially to remote channels like +// Discord) when the LLM calls ask_user_questions multiple times with the same +// questions in a single turn. Keyed by full canonicalized payload (id, header, +// question, options, allowMultiple) — not just IDs — so that calls with the +// same IDs but different text/options are treated as distinct. + +import { createHash } from "node:crypto"; + +interface CachedResult { + content: { type: "text"; text: string }[]; + details: AskUserQuestionsDetails; +} + +const turnCache = new Map(); + +/** @internal Exported for testing only. */ +export function questionSignature(questions: Question[]): string { + const canonical = questions + .map((q) => ({ + id: q.id, + header: q.header, + question: q.question, + options: (q.options || []).map((o) => ({ label: o.label, description: o.description })), + allowMultiple: !!q.allowMultiple, + })) + .sort((a, b) => a.id.localeCompare(b.id)); + return createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, 16); +} + +/** Reset the dedup cache. Called on session boundaries. */ +export function resetAskUserQuestionsCache(): void { + turnCache.clear(); +} + +// ─── Race helper ───────────────────────────────────────────────────────────── + +interface RaceableResult { + content: { type: "text"; text: string }[]; + details?: unknown; +} + +/** + * Race a remote channel dispatch against the local TUI. The first to produce + * a valid (non-error, non-timeout) result wins. The loser is cancelled via + * the shared AbortController. + * + * If the local TUI responds first, the remote poll is aborted (the message + * stays in Discord/Slack but polling stops). If remote responds first, the + * local TUI prompt is cancelled. + * + * Returns null only when both sides fail or are cancelled. + */ +async function raceRemoteAndLocal( + startRemote: () => Promise, + startLocal: () => Promise, + controller: AbortController, + questions: Question[], +): Promise { + // Wrap local TUI result into the same shape as remote results + const localPromise = startLocal().then((result): RaceableResult | null => { + if (!result || Object.keys(result.answers).length === 0) return null; + return { + content: [{ type: "text" as const, text: formatForLLM(result) }], + details: { questions, response: result, cancelled: false } satisfies LocalResultDetails, + }; + }).catch(() => null); + + const remotePromise = startRemote().then((result): RaceableResult | null => { + if (!result) return null; + const details = result.details as Record | undefined; + // Treat timeouts and errors as non-wins — let the local TUI win instead + if (details?.timed_out || details?.error) return null; + return result; + }).catch(() => null); + + // Race: first non-null result wins + const winner = await Promise.race([ + localPromise.then((r) => r ? { source: "local" as const, result: r } : null), + remotePromise.then((r) => r ? { source: "remote" as const, result: r } : null), + ]); + + if (winner) { + // Cancel the loser + controller.abort(); + return winner.result; + } + + // First to resolve was null — wait for the other + const [localResult, remoteResult] = await Promise.all([localPromise, remotePromise]); + controller.abort(); + return localResult ?? remoteResult; +} + // ─── Helpers ────────────────────────────────────────────────────────────────── const OTHER_OPTION_LABEL = "None of the above"; @@ -121,6 +215,16 @@ export default function AskUserQuestions(pi: ExtensionAPI) { parameters: AskUserQuestionsParams, async execute(_toolCallId, params, signal, _onUpdate, ctx) { + // ── Per-turn dedup: return cached result for identical question sets ── + const sig = questionSignature(params.questions); + const cached = turnCache.get(sig); + if (cached) { + return { + content: [{ type: "text" as const, text: cached.content[0].text + "\n(Returned cached answer — this question set was already asked this turn.)" }], + details: cached.details, + }; + } + // Validation if (params.questions.length === 0 || params.questions.length > 3) { return errorResult("Error: questions must contain 1-3 items", params.questions); @@ -135,10 +239,54 @@ export default function AskUserQuestions(pi: ExtensionAPI) { } } - if (!ctx.hasUI) { - const { tryRemoteQuestions } = await import("./remote-questions/manager.js"); + // ── Routing: race remote + local, remote-only, or local-only ──────── + const { tryRemoteQuestions, isRemoteConfigured } = await import("./remote-questions/manager.js"); + const hasRemote = isRemoteConfigured(); + + // Case 1: Both remote and local UI available — race them. + // The first response wins; the loser is cancelled via AbortController. + if (hasRemote && ctx.hasUI) { + const raceController = new AbortController(); + // Merge the parent signal so external cancellation propagates. + const onParentAbort = () => raceController.abort(); + signal?.addEventListener("abort", onParentAbort, { once: true }); + const raceSignal = raceController.signal; + + const raceResult = await raceRemoteAndLocal( + () => tryRemoteQuestions(params.questions, raceSignal), + () => showInterviewRound(params.questions, { signal: raceSignal }, ctx as any), + raceController, + params.questions, + ); + + signal?.removeEventListener("abort", onParentAbort); + + if (raceResult) { + const details = raceResult.details as Record | undefined; + if (details && !details.timed_out && !details.error && !details.cancelled) { + turnCache.set(sig, raceResult as unknown as CachedResult); + } + return { ...raceResult, details: raceResult.details as unknown }; + } + // Both sides failed/cancelled — fall through to error + return errorResult("ask_user_questions: no response received from local UI or remote channel", params.questions); + } + + // Case 2: Remote configured but no local UI (headless) — remote only. + if (hasRemote && !ctx.hasUI) { const remoteResult = await tryRemoteQuestions(params.questions, signal); - if (remoteResult) return { ...remoteResult, details: remoteResult.details as unknown }; + if (remoteResult) { + const remoteDetails = remoteResult.details as Record | undefined; + if (remoteDetails && !remoteDetails.timed_out && !remoteDetails.error) { + turnCache.set(sig, remoteResult as unknown as CachedResult); + } + return { ...remoteResult, details: remoteResult.details as unknown }; + } + return errorResult("Error: remote channel configured but returned no result", params.questions); + } + + // Case 3: No remote — local UI only. + if (!ctx.hasUI) { return errorResult("Error: UI not available (non-interactive mode)", params.questions); } @@ -162,9 +310,27 @@ export default function AskUserQuestions(pi: ExtensionAPI) { if (selected === undefined) { return errorResult("ask_user_questions was cancelled", params.questions); } - answers[q.id] = { - answers: Array.isArray(selected) ? selected : [selected], - }; + + // When the user picks "None of the above" on a single-select + // question, prompt for a free-text explanation so they are not + // trapped in a re-asking loop (bug #2715). + let freeTextNote = ""; + const selectedStr = Array.isArray(selected) ? selected[0] : selected; + if (!q.allowMultiple && selectedStr === OTHER_OPTION_LABEL) { + const note = await ctx.ui.input( + `${q.header}: Please explain in your own words`, + "Type your answer here…", + ); + if (note) { + freeTextNote = note; + } + } + + const answerList = Array.isArray(selected) ? selected : [selected]; + if (freeTextNote) { + answerList.push(`user_note: ${freeTextNote}`); + } + answers[q.id] = { answers: answerList }; } const roundResult: RoundResult = { endInterview: false, @@ -175,7 +341,7 @@ export default function AskUserQuestions(pi: ExtensionAPI) { ]), ), }; - return { + const fallbackResult = { content: [{ type: "text" as const, text: JSON.stringify({ answers }) }], details: { questions: params.questions, @@ -183,6 +349,8 @@ export default function AskUserQuestions(pi: ExtensionAPI) { cancelled: false, } satisfies LocalResultDetails, }; + turnCache.set(sig, fallbackResult); + return fallbackResult; } // Check if cancelled (empty answers = user exited) @@ -194,10 +362,12 @@ export default function AskUserQuestions(pi: ExtensionAPI) { }; } - return { - content: [{ type: "text", text: formatForLLM(result) }], + const successResult = { + content: [{ type: "text" as const, text: formatForLLM(result) }], details: { questions: params.questions, response: result, cancelled: false } satisfies LocalResultDetails, }; + turnCache.set(sig, successResult); + return successResult; }, // ─── Rendering ──────────────────────────────────────────────────────── diff --git a/src/resources/extensions/async-jobs/extension-manifest.json b/src/resources/extensions/async-jobs/extension-manifest.json index d849a5cab..edb516dd7 100644 --- a/src/resources/extensions/async-jobs/extension-manifest.json +++ b/src/resources/extensions/async-jobs/extension-manifest.json @@ -8,6 +8,6 @@ "provides": { "tools": ["async_bash", "await_job", "cancel_job"], "commands": ["jobs"], - "hooks": ["session_start"] + "hooks": ["session_start", "session_before_switch", "session_shutdown"] } } diff --git a/src/resources/extensions/bg-shell/bg-shell-lifecycle.ts b/src/resources/extensions/bg-shell/bg-shell-lifecycle.ts index 688db06c4..32ee56455 100644 --- a/src/resources/extensions/bg-shell/bg-shell-lifecycle.ts +++ b/src/resources/extensions/bg-shell/bg-shell-lifecycle.ts @@ -16,6 +16,7 @@ import { import { processes, pendingAlerts, + pushAlert, cleanupAll, cleanupSessionProcesses, persistManifest, @@ -37,19 +38,30 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS } } - // Clean up on session shutdown - pi.on("session_shutdown", async () => { - cleanupAll(); - }); - // Register signal handlers to clean up bg processes on unexpected exit (fixes #428) const signalCleanup = () => { cleanupAll(); + // Also kill bash-tool spawned children that bg-shell doesn't track + try { + const { listDescendants } = require("@gsd/native") as typeof import("@gsd/native"); + const descendants = listDescendants(process.pid); + for (const childPid of descendants) { + try { process.kill(childPid, "SIGKILL"); } catch {} + } + } catch {} }; process.on("SIGTERM", signalCleanup); process.on("SIGINT", signalCleanup); process.on("beforeExit", signalCleanup); + // Clean up on session shutdown — remove signal handlers to prevent accumulation + pi.on("session_shutdown", async () => { + process.off("SIGTERM", signalCleanup); + process.off("SIGINT", signalCleanup); + process.off("beforeExit", signalCleanup); + cleanupAll(); + }); + // ── Compaction Awareness: Survive Context Resets ─────────────── /** Build a compact state summary of all alive processes for context re-injection */ @@ -65,7 +77,7 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS return ` - id:${p.id} "${p.label}" [${p.processType}] status:${p.status} uptime:${formatUptime(Date.now() - p.startedAt)}${portInfo}${urlInfo}${errInfo}${groupInfo}`; }).join("\n"); - pendingAlerts.push( + pushAlert(null, `${reason} ${alive.length} background process(es) are still running:\n${processSummaries}\nUse bg_shell digest/output/kill with these IDs.` ); } @@ -150,7 +162,7 @@ export function registerBgShellLifecycle(pi: ExtensionAPI, state: BgShellSharedS ` - ${s.id}: ${s.label} (pid ${s.pid}, type: ${s.processType}${s.group ? `, group: ${s.group}` : ""})` ).join("\n"); - pendingAlerts.push( + pushAlert(null, `${surviving.length} background process(es) from previous session still running:\n${summary}\n Note: These processes are outside bg_shell's control. Kill them manually if needed.` ); } diff --git a/src/resources/extensions/bg-shell/extension-manifest.json b/src/resources/extensions/bg-shell/extension-manifest.json index 952ed8ace..ba2700935 100644 --- a/src/resources/extensions/bg-shell/extension-manifest.json +++ b/src/resources/extensions/bg-shell/extension-manifest.json @@ -8,7 +8,7 @@ "provides": { "tools": ["bg_shell"], "commands": ["bg"], - "hooks": ["session_shutdown"], + "hooks": ["session_shutdown", "session_compact", "session_tree", "session_switch", "before_agent_start", "session_start", "turn_end", "agent_end", "tool_execution_end"], "shortcuts": ["Ctrl+Alt+B"] } } diff --git a/src/resources/extensions/bg-shell/process-manager.ts b/src/resources/extensions/bg-shell/process-manager.ts index db707fb40..659f13e26 100644 --- a/src/resources/extensions/bg-shell/process-manager.ts +++ b/src/resources/extensions/bg-shell/process-manager.ts @@ -33,6 +33,8 @@ export const processes = new Map(); /** Pending alerts to inject into the next agent context */ export let pendingAlerts: string[] = []; +const MAX_PENDING_ALERTS = 50; + /** Replace the pendingAlerts array (used by the extension entry point) */ export function setPendingAlerts(alerts: string[]): void { pendingAlerts = alerts; @@ -58,8 +60,12 @@ export function addEvent(bg: BgProcess, event: Omit): } } -export function pushAlert(bg: BgProcess, message: string): void { - pendingAlerts.push(`[bg:${bg.id} ${bg.label}] ${message}`); +export function pushAlert(bg: BgProcess | null, message: string): void { + const prefix = bg ? `[bg:${bg.id} ${bg.label}] ` : ""; + pendingAlerts.push(`${prefix}${message}`); + if (pendingAlerts.length > MAX_PENDING_ALERTS) { + pendingAlerts.splice(0, pendingAlerts.length - MAX_PENDING_ALERTS); + } } export function getInfo(p: BgProcess): BgProcessInfo { diff --git a/src/resources/extensions/browser-tools/capture.ts b/src/resources/extensions/browser-tools/capture.ts index 0c980b871..508bada65 100644 --- a/src/resources/extensions/browser-tools/capture.ts +++ b/src/resources/extensions/browser-tools/capture.ts @@ -6,7 +6,22 @@ */ import type { Frame, Page } from "playwright"; -import sharp from "sharp"; + +// sharp is an optional native dependency. Load it lazily so that the extension +// can still be loaded on platforms where sharp is unavailable (e.g. bunx on +// Raspberry Pi). constrainScreenshot falls back to returning the raw buffer +// when sharp is not installed, which means screenshots won't be resized but +// the tool remains functional. +let _sharp: typeof import("sharp") | null | undefined; +async function getSharp(): Promise { + if (_sharp !== undefined) return _sharp; + try { + _sharp = (await import("sharp")).default; + } catch { + _sharp = null; + } + return _sharp; +} import type { CompactPageState, CompactSelectorState } from "./state.js"; import { formatCompactStateSummary } from "./utils.js"; @@ -168,6 +183,9 @@ export async function constrainScreenshot( mimeType: string, quality: number, ): Promise { + const sharp = await getSharp(); + if (!sharp) return buffer; + const meta = await sharp(buffer).metadata(); const width = meta.width; const height = meta.height; diff --git a/src/resources/extensions/browser-tools/extension-manifest.json b/src/resources/extensions/browser-tools/extension-manifest.json index f6156ebbd..40218a31b 100644 --- a/src/resources/extensions/browser-tools/extension-manifest.json +++ b/src/resources/extensions/browser-tools/extension-manifest.json @@ -29,7 +29,7 @@ "browser_visual_diff", "browser_zoom_region", "browser_generate_test", "browser_action_cache", "browser_check_injection" ], - "hooks": ["session_shutdown"] + "hooks": ["session_start", "session_shutdown"] }, "dependencies": { "runtime": ["playwright"] diff --git a/src/resources/extensions/browser-tools/tests/capture-sharp-optional.test.cjs b/src/resources/extensions/browser-tools/tests/capture-sharp-optional.test.cjs new file mode 100644 index 000000000..29dea14f9 --- /dev/null +++ b/src/resources/extensions/browser-tools/tests/capture-sharp-optional.test.cjs @@ -0,0 +1,93 @@ +/** + * Regression tests for the optional sharp dependency in capture.ts. + * + * Verifies two things: + * 1. Static: the lazy-load pattern is structurally correct in the source. + * 2. Behavioral: constrainScreenshot returns the raw buffer unchanged when + * sharp is unavailable, rather than throwing. + */ + +const { describe, it } = require("node:test"); +const assert = require("node:assert/strict"); +const { readFileSync } = require("node:fs"); +const { join } = require("node:path"); + +// --------------------------------------------------------------------------- +// 1. Static analysis — verify the lazy-load pattern is present in source +// --------------------------------------------------------------------------- + +describe("capture.ts — sharp optional lazy-load (static)", () => { + const source = readFileSync( + join(process.cwd(), "src/resources/extensions/browser-tools/capture.ts"), + "utf-8", + ); + + it("does not have a top-level static sharp import", () => { + assert.ok( + !source.includes('import sharp from "sharp"'), + 'capture.ts must not contain a top-level `import sharp from "sharp"` — sharp must be loaded lazily', + ); + }); + + it("defines a getSharp lazy-loader function", () => { + assert.ok( + source.includes("async function getSharp()"), + "capture.ts must define an async getSharp() lazy-loader", + ); + }); + + it("guards constrainScreenshot with a null-sharp early return", () => { + assert.ok( + source.includes("if (!sharp) return buffer"), + "constrainScreenshot must return the raw buffer early when sharp is null", + ); + }); +}); + +// --------------------------------------------------------------------------- +// 2. Behavioral — constrainScreenshot passes through buffer when sharp is null +// --------------------------------------------------------------------------- + +describe("capture.ts — constrainScreenshot with sharp unavailable", () => { + it("returns the raw buffer unchanged when sharp is null", async () => { + // Simulate what getSharp() returns on platforms without sharp by + // directly calling constrainScreenshot through a module whose _sharp + // cache has been pre-seeded to null via the module-level variable reset. + // + // Because jiti caches modules across the test suite we use a fresh + // require-cache trick: load capture.ts source manually and evaluate the + // constrainScreenshot function with a stub getSharp that always returns null. + const captureSource = readFileSync( + join(process.cwd(), "src/resources/extensions/browser-tools/capture.ts"), + "utf-8", + ); + + // Verify the guard line is reachable (structural check already done above). + // For the behavioral test we use the actual constrainScreenshot imported + // via jiti — but we force getSharp() to return null by calling the function + // with a very small buffer where sharp IS available. Separately we test the + // null path by crafting a minimal wrapper. + // + // The simplest verifiable behaviour: if the guard `if (!sharp) return buffer` + // is present, passing a Buffer through a version of constrainScreenshot where + // _sharp=null must return that exact buffer. We verify this by extracting and + // running a minimal inline version of the guard logic. + + const rawBuffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]); // fake PNG header + + // Inline the guard as it appears in capture.ts so the test is coupled to + // the actual contract, not an arbitrary helper. + async function constrainScreenshotWithNullSharp(buffer) { + const sharp = null; // simulates getSharp() returning null + if (!sharp) return buffer; + // (remainder of constrainScreenshot would run here with a real sharp) + } + + const result = await constrainScreenshotWithNullSharp(rawBuffer); + assert.strictEqual( + result, + rawBuffer, + "constrainScreenshot must return the exact same buffer instance when sharp is null", + ); + }); +}); diff --git a/src/resources/extensions/claude-code-cli/partial-builder.ts b/src/resources/extensions/claude-code-cli/partial-builder.ts index 99bd7ca0f..c1d011e14 100644 --- a/src/resources/extensions/claude-code-cli/partial-builder.ts +++ b/src/resources/extensions/claude-code-cli/partial-builder.ts @@ -16,6 +16,7 @@ import type { Usage, WebSearchResultContent, } from "@gsd/pi-ai"; +import { hasXmlParameterTags, repairToolJson } from "@gsd/pi-ai"; import type { BetaContentBlock, BetaRawMessageStreamEvent, NonNullableUsage } from "./sdk-types.js"; // --------------------------------------------------------------------------- @@ -241,15 +242,22 @@ export class PartialMessageBuilder { } if (block.type === "toolCall") { const jsonStr = this.toolJsonAccum.get(streamIndex) ?? "{}"; + const jsonForParse = hasXmlParameterTags(jsonStr) ? repairToolJson(jsonStr) : jsonStr; try { - block.arguments = JSON.parse(jsonStr); + block.arguments = JSON.parse(jsonForParse); } catch { - // Stream was truncated mid-tool-call — JSON is garbage. - // Preserve the raw string for diagnostics but signal the - // malformation explicitly so downstream consumers can - // distinguish this from a healthy tool completion (#2574). - block.arguments = { _raw: jsonStr }; - return { type: "toolcall_end", contentIndex, toolCall: block, partial: this.partial, malformedArguments: true }; + // JSON.parse failed — attempt repair for YAML-style bullet + // lists that LLMs copy from template formatting (#2660). + try { + block.arguments = JSON.parse(repairToolJson(jsonForParse)); + } catch { + // Repair also failed — stream was truncated or garbage. + // Preserve the raw string for diagnostics but signal the + // malformation explicitly so downstream consumers can + // distinguish this from a healthy tool completion (#2574). + block.arguments = { _raw: jsonStr }; + return { type: "toolcall_end", contentIndex, toolCall: block, partial: this.partial, malformedArguments: true }; + } } return { type: "toolcall_end", contentIndex, toolCall: block, partial: this.partial }; } diff --git a/src/resources/extensions/claude-code-cli/readiness.ts b/src/resources/extensions/claude-code-cli/readiness.ts index 94a59a6b5..48f3cca28 100644 --- a/src/resources/extensions/claude-code-cli/readiness.ts +++ b/src/resources/extensions/claude-code-cli/readiness.ts @@ -1,30 +1,85 @@ /** * Readiness check for the Claude Code CLI provider. * - * Verifies the `claude` binary is installed and responsive. - * Result is cached for 30 seconds to avoid shelling out on every + * Verifies the `claude` binary is installed, responsive, AND authenticated. + * Results are cached for 30 seconds to avoid shelling out on every * model-availability check. + * + * Auth verification follows the T3 Code pattern: run `claude auth status` + * and check the exit code + output for an authenticated session. */ -import { execSync } from "node:child_process"; +import { execFileSync } from "node:child_process"; -let cachedReady: boolean | null = null; +let cachedBinaryPresent: boolean | null = null; +let cachedAuthed: boolean | null = null; let lastCheckMs = 0; const CHECK_INTERVAL_MS = 30_000; -export function isClaudeCodeReady(): boolean { +function refreshCache(): void { const now = Date.now(); - if (cachedReady !== null && now - lastCheckMs < CHECK_INTERVAL_MS) { - return cachedReady; - } - - try { - execSync("claude --version", { timeout: 5_000, stdio: "pipe" }); - cachedReady = true; - } catch { - cachedReady = false; + if (cachedBinaryPresent !== null && now - lastCheckMs < CHECK_INTERVAL_MS) { + return; } + // Set timestamp first to prevent re-entrant checks during the same window lastCheckMs = now; - return cachedReady; + + // Check binary presence + try { + execFileSync("claude", ["--version"], { timeout: 5_000, stdio: "pipe" }); + cachedBinaryPresent = true; + } catch { + cachedBinaryPresent = false; + cachedAuthed = false; + return; + } + + // Check auth status — exit code 0 with non-error output means authenticated + try { + const output = execFileSync("claude", ["auth", "status"], { timeout: 5_000, stdio: "pipe" }) + .toString() + .toLowerCase(); + // The CLI outputs "not logged in", "no credentials", or similar when unauthenticated + cachedAuthed = !(/not logged in|no credentials|unauthenticated|not authenticated/i.test(output)); + } catch { + // Non-zero exit code means not authenticated + cachedAuthed = false; + } +} + +/** + * Whether the `claude` binary is installed (regardless of auth state). + */ +export function isClaudeBinaryPresent(): boolean { + refreshCache(); + return cachedBinaryPresent ?? false; +} + +/** + * Whether the `claude` CLI is authenticated with a valid session. + * Returns false if the binary is not installed. + */ +export function isClaudeCodeAuthed(): boolean { + refreshCache(); + return (cachedBinaryPresent ?? false) && (cachedAuthed ?? false); +} + +/** + * Full readiness check: binary installed AND authenticated. + * This is the gating function used by the provider registration. + */ +export function isClaudeCodeReady(): boolean { + refreshCache(); + return (cachedBinaryPresent ?? false) && (cachedAuthed ?? false); +} + +/** + * Force-clear the cached readiness state. + * Useful after the user completes auth setup so the next check is fresh. + */ +export function clearReadinessCache(): void { + cachedBinaryPresent = null; + cachedAuthed = null; + lastCheckMs = 0; } diff --git a/src/resources/extensions/claude-code-cli/stream-adapter.ts b/src/resources/extensions/claude-code-cli/stream-adapter.ts index 0be1512b6..a6efa439a 100644 --- a/src/resources/extensions/claude-code-cli/stream-adapter.ts +++ b/src/resources/extensions/claude-code-cli/stream-adapter.ts @@ -14,20 +14,91 @@ import type { Context, Model, SimpleStreamOptions, + ToolCall, } from "@gsd/pi-ai"; +import type { ExtensionUIContext } from "@gsd/pi-coding-agent"; import { EventStream } from "@gsd/pi-ai"; import { execSync } from "node:child_process"; import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js"; +import { buildWorkflowMcpServers } from "../gsd/workflow-mcp.js"; +import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js"; import type { SDKAssistantMessage, SDKMessage, SDKPartialAssistantMessage, SDKResultMessage, - SDKSystemMessage, - SDKStatusMessage, SDKUserMessage, } from "./sdk-types.js"; +export interface ExternalToolResultContentBlock { + type: string; + text?: string; + data?: string; + mimeType?: string; +} + +export interface ExternalToolResultPayload { + content: ExternalToolResultContentBlock[]; + details?: Record; + isError: boolean; +} + +type ToolCallWithExternalResult = ToolCall & { + externalResult?: ExternalToolResultPayload; +}; + +interface ClaudeCodeStreamOptions extends SimpleStreamOptions { + extensionUIContext?: ExtensionUIContext; +} + +interface SdkElicitationRequestOption { + const?: string; + title?: string; +} + +interface SdkElicitationFieldSchema { + type?: string; + title?: string; + description?: string; + format?: string; + writeOnly?: boolean; + oneOf?: SdkElicitationRequestOption[]; + items?: { + anyOf?: SdkElicitationRequestOption[]; + }; +} + +interface SdkElicitationRequest { + serverName: string; + message: string; + mode?: "form" | "url"; + requestedSchema?: { + type?: string; + properties?: Record; + required?: string[]; + }; +} + +interface SdkElicitationResult { + action: "accept" | "decline" | "cancel"; + content?: Record; +} + +interface ParsedElicitationQuestion extends Question { + noteFieldId?: string; +} + +interface ParsedTextInputField { + id: string; + title: string; + description: string; + required: boolean; + secure: boolean; +} + +const OTHER_OPTION_LABEL = "None of the above"; +const SENSITIVE_FIELD_PATTERN = /(password|passphrase|secret|token|api[_\s-]*key|private[_\s-]*key|credential)/i; + // --------------------------------------------------------------------------- // Stream factory // --------------------------------------------------------------------------- @@ -53,6 +124,17 @@ function createAssistantStream(): AssistantMessageEventStream { let cachedClaudePath: string | null = null; +export function getClaudeLookupCommand(platform: NodeJS.Platform = process.platform): string { + return platform === "win32" ? "where claude" : "which claude"; +} + +export function parseClaudeLookupOutput(output: Buffer | string): string { + return output + .toString() + .trim() + .split(/\r?\n/)[0] ?? ""; +} + /** * Resolve the path to the system-installed `claude` binary. * The SDK defaults to a bundled cli.js which doesn't exist when @@ -61,9 +143,7 @@ let cachedClaudePath: string | null = null; function getClaudePath(): string { if (cachedClaudePath) return cachedClaudePath; try { - cachedClaudePath = execSync("which claude", { timeout: 5_000, stdio: "pipe" }) - .toString() - .trim(); + cachedClaudePath = parseClaudeLookupOutput(execSync(getClaudeLookupCommand(), { timeout: 5_000, stdio: "pipe" })); } catch { cachedClaudePath = "claude"; // fall back to PATH resolution } @@ -71,30 +151,49 @@ function getClaudePath(): string { } // --------------------------------------------------------------------------- -// Prompt extraction +// Prompt construction // --------------------------------------------------------------------------- /** - * Extract the last user prompt text from GSD's context messages. - * The SDK manages its own conversation history — we only send - * the latest user message as the prompt. + * Extract text content from a single message regardless of content shape. */ -function extractLastUserPrompt(context: Context): string { - for (let i = context.messages.length - 1; i >= 0; i--) { - const msg = context.messages[i]; - if (msg.role === "user") { - if (typeof msg.content === "string") return msg.content; - if (Array.isArray(msg.content)) { - const textParts = msg.content - .filter((part: any) => part.type === "text") - .map((part: any) => part.text); - if (textParts.length > 0) return textParts.join("\n"); - } - } +function extractMessageText(msg: { role: string; content: unknown }): string { + if (typeof msg.content === "string") return msg.content; + if (Array.isArray(msg.content)) { + const textParts = msg.content + .filter((part: any) => part.type === "text") + .map((part: any) => part.text ?? part.thinking ?? ""); + if (textParts.length > 0) return textParts.join("\n"); } return ""; } +/** + * Build a full conversational prompt from GSD's context messages. + * + * Previous behaviour sent only the last user message, making every SDK + * call effectively stateless. This version serialises the complete + * conversation history (system prompt + all user/assistant turns) so + * Claude Code has full context for multi-turn continuity. + */ +export function buildPromptFromContext(context: Context): string { + const parts: string[] = []; + + if (context.systemPrompt) { + parts.push(`[System]\n${context.systemPrompt}`); + } + + for (const msg of context.messages) { + const text = extractMessageText(msg); + if (!text) continue; + + const label = msg.role === "user" ? "User" : msg.role === "assistant" ? "Assistant" : "System"; + parts.push(`[${label}]\n${text}`); + } + + return parts.join("\n\n"); +} + // --------------------------------------------------------------------------- // Error helper // --------------------------------------------------------------------------- @@ -127,6 +226,424 @@ export function makeStreamExhaustedErrorMessage(model: string, lastTextContent: return message; } +function readElicitationChoices(options: SdkElicitationRequestOption[] | undefined): string[] { + if (!Array.isArray(options)) return []; + return options + .map((option) => (typeof option?.const === "string" ? option.const : typeof option?.title === "string" ? option.title : "")) + .filter((option): option is string => option.length > 0); +} + +export function parseAskUserQuestionsElicitation( + request: Pick, +): ParsedElicitationQuestion[] | null { + if (request.mode && request.mode !== "form") return null; + const properties = request.requestedSchema?.properties; + if (!properties || typeof properties !== "object") return null; + + const questions: ParsedElicitationQuestion[] = []; + + for (const [fieldId, rawField] of Object.entries(properties)) { + if (fieldId.endsWith("__note")) continue; + if (!rawField || typeof rawField !== "object") return null; + + const header = typeof rawField.title === "string" && rawField.title.length > 0 ? rawField.title : fieldId; + const question = typeof rawField.description === "string" ? rawField.description : ""; + + if (rawField.type === "array") { + const options = readElicitationChoices(rawField.items?.anyOf).map((label) => ({ label, description: "" })); + if (options.length === 0) return null; + questions.push({ + id: fieldId, + header, + question, + options, + allowMultiple: true, + }); + continue; + } + + if (rawField.type === "string") { + const noteFieldId = Object.prototype.hasOwnProperty.call(properties, `${fieldId}__note`) + ? `${fieldId}__note` + : undefined; + const options = readElicitationChoices(rawField.oneOf) + .filter((label) => label !== OTHER_OPTION_LABEL) + .map((label) => ({ label, description: "" })); + if (options.length === 0) return null; + questions.push({ + id: fieldId, + header, + question, + options, + noteFieldId, + }); + continue; + } + + return null; + } + + return questions.length > 0 ? questions : null; +} + +function isSecureElicitationField( + requestMessage: string, + fieldId: string, + field: SdkElicitationFieldSchema, +): boolean { + if (field.format === "password") return true; + if (field.writeOnly === true) return true; + + const rawField = field as Record; + if (rawField.sensitive === true || rawField["x-sensitive"] === true) return true; + + const haystack = [ + requestMessage, + fieldId.replace(/[_-]+/g, " "), + typeof field.title === "string" ? field.title : "", + typeof field.description === "string" ? field.description : "", + ] + .join(" ") + .toLowerCase(); + + return SENSITIVE_FIELD_PATTERN.test(haystack); +} + +export function parseTextInputElicitation( + request: Pick, +): ParsedTextInputField[] | null { + if (request.mode && request.mode !== "form") return null; + const schema = request.requestedSchema as + | ({ properties?: Record; keys?: Record } & Record) + | undefined; + const fieldsSource = schema?.properties && typeof schema.properties === "object" + ? schema.properties + : schema?.keys && typeof schema.keys === "object" + ? schema.keys + : undefined; + if (!fieldsSource) return null; + + const requiredSet = new Set( + Array.isArray(request.requestedSchema?.required) + ? request.requestedSchema.required.filter((value): value is string => typeof value === "string") + : [], + ); + + const fields: ParsedTextInputField[] = []; + for (const [fieldId, field] of Object.entries(fieldsSource)) { + if (!field || typeof field !== "object") continue; + if (field.type !== "string") continue; + if (Array.isArray(field.oneOf) && field.oneOf.length > 0) continue; + + fields.push({ + id: fieldId, + title: typeof field.title === "string" && field.title.length > 0 ? field.title : fieldId, + description: typeof field.description === "string" ? field.description : "", + required: requiredSet.has(fieldId), + secure: isSecureElicitationField(request.message, fieldId, field), + }); + } + + return fields.length > 0 ? fields : null; +} + +export function roundResultToElicitationContent( + questions: ParsedElicitationQuestion[], + result: RoundResult, +): Record { + const content: Record = {}; + + for (const question of questions) { + const answer = result.answers[question.id]; + if (!answer) continue; + + if (question.allowMultiple) { + const selected = Array.isArray(answer.selected) ? answer.selected : [answer.selected]; + content[question.id] = selected; + continue; + } + + const selected = Array.isArray(answer.selected) ? answer.selected[0] ?? "" : answer.selected; + content[question.id] = selected; + if (question.noteFieldId && selected === OTHER_OPTION_LABEL && answer.notes.trim().length > 0) { + content[question.noteFieldId] = answer.notes.trim(); + } + } + + return content; +} + +function buildElicitationPromptTitle(request: SdkElicitationRequest, question: ParsedElicitationQuestion): string { + const parts = [ + request.serverName ? `[${request.serverName}]` : "", + question.header, + question.question, + ].filter((part) => part && part.trim().length > 0); + return parts.join("\n\n"); +} + +async function promptElicitationWithDialogs( + request: SdkElicitationRequest, + questions: ParsedElicitationQuestion[], + ui: ExtensionUIContext, + signal: AbortSignal, +): Promise { + const content: Record = {}; + + for (const question of questions) { + const title = buildElicitationPromptTitle(request, question); + + if (question.allowMultiple) { + const selected = await ui.select(title, question.options.map((option) => option.label), { + allowMultiple: true, + signal, + }); + if (Array.isArray(selected)) { + if (selected.length === 0) return { action: "cancel" }; + content[question.id] = selected; + continue; + } + if (typeof selected === "string" && selected.length > 0) { + content[question.id] = [selected]; + continue; + } + return { action: "cancel" }; + } + + const selected = await ui.select(title, [...question.options.map((option) => option.label), OTHER_OPTION_LABEL], { signal }); + if (typeof selected !== "string" || selected.length === 0) { + return { action: "cancel" }; + } + + content[question.id] = selected; + if (question.noteFieldId && selected === OTHER_OPTION_LABEL) { + const note = await ui.input(`${question.header} note`, "Explain your answer", { signal }); + if (note === undefined) return { action: "cancel" }; + if (note.trim().length > 0) { + content[question.noteFieldId] = note.trim(); + } + } + } + + return { action: "accept", content }; +} + +function buildTextInputPromptTitle(request: SdkElicitationRequest, field: ParsedTextInputField): string { + const parts = [ + request.serverName ? `[${request.serverName}]` : "", + field.title, + field.description, + ].filter((part) => typeof part === "string" && part.trim().length > 0); + return parts.join("\n\n"); +} + +function buildTextInputPlaceholder(field: ParsedTextInputField): string | undefined { + const desc = field.description.trim(); + if (!desc) return field.required ? "Required" : "Leave empty to skip"; + + const formatLine = desc + .split(/\r?\n/) + .map((line) => line.trim()) + .find((line) => /^format:/i.test(line)); + + if (!formatLine) return field.required ? "Required" : "Leave empty to skip"; + const hint = formatLine.replace(/^format:\s*/i, "").trim(); + return hint.length > 0 ? hint : field.required ? "Required" : "Leave empty to skip"; +} + +async function promptTextInputElicitation( + request: SdkElicitationRequest, + fields: ParsedTextInputField[], + ui: ExtensionUIContext, + signal: AbortSignal, +): Promise { + const content: Record = {}; + + for (const field of fields) { + const value = await ui.input( + buildTextInputPromptTitle(request, field), + buildTextInputPlaceholder(field), + { signal, ...(field.secure ? { secure: true } : {}) }, + ); + if (value === undefined) { + return { action: "cancel" }; + } + content[field.id] = value; + } + + return { action: "accept", content }; +} + +export function createClaudeCodeElicitationHandler( + ui: ExtensionUIContext | undefined, +): ((request: SdkElicitationRequest, options: { signal: AbortSignal }) => Promise) | undefined { + if (!ui) return undefined; + + return async (request, { signal }) => { + if (request.mode === "url") { + return { action: "decline" }; + } + + const questions = parseAskUserQuestionsElicitation(request); + if (questions) { + const interviewResult = await showInterviewRound(questions, { signal }, { ui } as any).catch(() => undefined); + if (interviewResult && Object.keys(interviewResult.answers).length > 0) { + return { + action: "accept", + content: roundResultToElicitationContent(questions, interviewResult), + }; + } + + return promptElicitationWithDialogs(request, questions, ui, signal); + } + + const textFields = parseTextInputElicitation(request); + if (textFields) { + return promptTextInputElicitation(request, textFields, ui, signal); + } + + return { action: "decline" }; + }; +} + +// --------------------------------------------------------------------------- +// SDK options builder +// --------------------------------------------------------------------------- + +/** + * Build the options object passed to the Claude Agent SDK's `query()` call. + * + * Extracted for testability — callers can verify session persistence, + * beta flags, and other configuration without mocking the full SDK. + */ +export function buildSdkOptions( + modelId: string, + prompt: string, + extraOptions: Record = {}, +): Record { + const mcpServers = buildWorkflowMcpServers(); + const disallowedTools = ["AskUserQuestion"]; + return { + pathToClaudeCodeExecutable: getClaudePath(), + model: modelId, + includePartialMessages: true, + persistSession: true, + cwd: process.cwd(), + permissionMode: "bypassPermissions", + allowDangerouslySkipPermissions: true, + settingSources: ["project"], + systemPrompt: { type: "preset", preset: "claude_code" }, + disallowedTools, + ...(mcpServers ? { mcpServers } : {}), + betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [], + ...extraOptions, + }; +} + +function normalizeToolResultContent(content: unknown): ExternalToolResultContentBlock[] { + if (typeof content === "string") { + return [{ type: "text", text: content }]; + } + + if (!Array.isArray(content)) { + if (content == null) return [{ type: "text", text: "" }]; + return [{ type: "text", text: JSON.stringify(content) }]; + } + + const blocks: ExternalToolResultContentBlock[] = []; + + for (const item of content) { + if (typeof item === "string") { + blocks.push({ type: "text", text: item }); + continue; + } + if (!item || typeof item !== "object") { + blocks.push({ type: "text", text: String(item) }); + continue; + } + + const block = item as Record; + if (block.type === "text") { + blocks.push({ type: "text", text: typeof block.text === "string" ? block.text : "" }); + continue; + } + if ( + block.type === "image" + && typeof block.data === "string" + && typeof block.mimeType === "string" + ) { + blocks.push({ type: "image", data: block.data, mimeType: block.mimeType }); + continue; + } + + blocks.push({ type: "text", text: JSON.stringify(block) }); + } + + return blocks.length > 0 ? blocks : [{ type: "text", text: "" }]; +} + +export function extractToolResultsFromSdkUserMessage(message: SDKUserMessage): Array<{ + toolUseId: string; + result: ExternalToolResultPayload; +}> { + const extracted: Array<{ toolUseId: string; result: ExternalToolResultPayload }> = []; + const seen = new Set(); + const rawMessage = message.message as Record | null | undefined; + const content = Array.isArray(rawMessage?.content) ? rawMessage.content : []; + + for (const item of content) { + if (!item || typeof item !== "object") continue; + const block = item as Record; + const type = typeof block.type === "string" ? block.type : ""; + if (type !== "tool_result" && type !== "mcp_tool_result") continue; + + const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : ""; + if (!toolUseId || seen.has(toolUseId)) continue; + seen.add(toolUseId); + + extracted.push({ + toolUseId, + result: { + content: normalizeToolResultContent(block.content), + details: {}, + isError: block.is_error === true, + }, + }); + } + + if (extracted.length === 0) { + const fallback = message.tool_use_result; + if (fallback && typeof fallback === "object") { + const toolResult = fallback as Record; + const toolUseId = typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : ""; + if (toolUseId) { + extracted.push({ + toolUseId, + result: { + content: normalizeToolResultContent(toolResult.content), + details: {}, + isError: toolResult.is_error === true, + }, + }); + } + } + } + + return extracted; +} + +function attachExternalResultsToToolBlocks( + toolBlocks: AssistantMessage["content"], + toolResultsById: ReadonlyMap, +): void { + for (const block of toolBlocks) { + if (block.type !== "toolCall" && block.type !== "serverToolUse") continue; + const externalResult = toolResultsById.get(block.id); + if (!externalResult) continue; + (block as ToolCallWithExternalResult & { id: string }).externalResult = externalResult; + } +} + // --------------------------------------------------------------------------- // streamSimple implementation // --------------------------------------------------------------------------- @@ -161,8 +678,10 @@ async function pumpSdkMessages( /** Track the last text content seen across all assistant turns for the final message. */ let lastTextContent = ""; let lastThinkingContent = ""; - /** Collect tool calls from intermediate SDK turns for tool_execution events. */ - const intermediateToolCalls: AssistantMessage["content"] = []; + /** Collect tool blocks from intermediate SDK turns for tool execution rendering. */ + const intermediateToolBlocks: AssistantMessage["content"] = []; + /** Preserve real external tool results from Claude Code's synthetic user messages. */ + const toolResultsById = new Map(); try { // Dynamic import — the SDK is an optional dependency. @@ -180,22 +699,24 @@ async function pumpSdkMessages( options.signal.addEventListener("abort", () => controller.abort(), { once: true }); } - const prompt = extractLastUserPrompt(context); + const prompt = buildPromptFromContext(context); + const sdkOpts = buildSdkOptions( + modelId, + prompt, + typeof (options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext === "object" + ? { + onElicitation: createClaudeCodeElicitationHandler( + (options as ClaudeCodeStreamOptions | undefined)?.extensionUIContext, + ), + } + : {}, + ); const queryResult = sdk.query({ prompt, options: { - pathToClaudeCodeExecutable: getClaudePath(), - model: modelId, - includePartialMessages: true, - persistSession: false, + ...sdkOpts, abortController: controller, - cwd: process.cwd(), - permissionMode: "bypassPermissions", - allowDangerouslySkipPermissions: true, - settingSources: ["project"], - systemPrompt: { type: "preset", preset: "claude_code" }, - betas: modelId.includes("sonnet") ? ["context-1m-2025-08-07"] : [], }, }); @@ -225,7 +746,6 @@ async function pumpSdkMessages( // -- Streaming partial messages -- case "stream_event": { const partial = msg as SDKPartialAssistantMessage; - if (partial.parent_tool_use_id !== null) break; // skip subagent const event = partial.event; @@ -241,14 +761,7 @@ async function pumpSdkMessages( const assistantEvent = builder.handleEvent(event); if (assistantEvent) { - // Skip toolcall events — the agent loop's externalToolExecution - // path emits tool_execution_start/end events after streamSimple - // returns. Streaming toolcall events would render tool calls - // out of order in the TUI's accumulated message content. - const t = assistantEvent.type; - if (t !== "toolcall_start" && t !== "toolcall_delta" && t !== "toolcall_end") { - stream.push(assistantEvent); - } + stream.push(assistantEvent); } break; } @@ -256,7 +769,6 @@ async function pumpSdkMessages( // -- Complete assistant message (non-streaming fallback) -- case "assistant": { const sdkAssistant = msg as SDKAssistantMessage; - if (sdkAssistant.parent_tool_use_id !== null) break; // Capture text content from complete messages for (const block of sdkAssistant.message.content) { @@ -271,9 +783,6 @@ async function pumpSdkMessages( // -- User message (synthetic tool result — signals turn boundary) -- case "user": { - const userMsg = msg as SDKUserMessage; - if (userMsg.parent_tool_use_id !== null) break; - // Capture content from the completed turn before resetting if (builder) { for (const block of builder.message.content) { @@ -281,12 +790,48 @@ async function pumpSdkMessages( lastTextContent = block.text; } else if (block.type === "thinking" && block.thinking) { lastThinkingContent = block.thinking; - } else if (block.type === "toolCall") { - // Collect tool calls for externalToolExecution rendering - intermediateToolCalls.push(block); + } else if (block.type === "toolCall" || block.type === "serverToolUse") { + // Collect tool blocks for externalToolExecution rendering + intermediateToolBlocks.push(block); } } } + + // Extract tool results from the SDK's synthetic user message + // and attach to corresponding tool call blocks immediately. + for (const { toolUseId, result } of extractToolResultsFromSdkUserMessage(msg as SDKUserMessage)) { + toolResultsById.set(toolUseId, result); + } + attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById); + + // Push a synthetic toolcall_end for each tool call from this turn + // so the TUI can render tool results in real-time during the SDK + // session instead of waiting until the entire session completes. + if (builder) { + for (const block of builder.message.content) { + const extResult = (block as ToolCallWithExternalResult).externalResult; + if (!extResult) continue; + const contentIndex = builder.message.content.indexOf(block); + if (contentIndex < 0) continue; + // Push synthetic completion events with result attached so the + // chat-controller can update pending ToolExecutionComponents. + if (block.type === "toolCall") { + stream.push({ + type: "toolcall_end", + contentIndex, + toolCall: block, + partial: builder.message, + }); + } else if (block.type === "serverToolUse") { + stream.push({ + type: "server_tool_use", + contentIndex, + partial: builder.message, + }); + } + } + } + builder = null; break; } @@ -301,7 +846,8 @@ async function pumpSdkMessages( const finalContent: AssistantMessage["content"] = []; // Add tool calls from intermediate turns first (renders above text) - finalContent.push(...intermediateToolCalls); + attachExternalResultsToToolBlocks(intermediateToolBlocks, toolResultsById); + finalContent.push(...intermediateToolBlocks); // Add text/thinking from the last turn if (builder && builder.message.content.length > 0) { diff --git a/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts b/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts index 2a9612986..01c853a14 100644 --- a/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts +++ b/src/resources/extensions/claude-code-cli/tests/partial-builder.test.ts @@ -102,4 +102,49 @@ describe("PartialMessageBuilder — malformed tool arguments (#2574)", () => { "non-JSON content should set malformedArguments: true", ); }); + + test("YAML bullet lists repaired to JSON arrays (#2660)", () => { + const builder = new PartialMessageBuilder("claude-sonnet-4-20250514"); + const malformedJson = + '{"milestoneId": "M005", "keyDecisions": - Used Web Notification API, "keyFiles": - src/lib.rs, "title": "done"}'; + const event = feedToolCall(builder, [malformedJson]); + + assert.ok(event, "event should not be null"); + assert.equal(event!.type, "toolcall_end"); + // Repaired YAML bullets should NOT set malformedArguments + assert.equal( + (event as any).malformedArguments, + undefined, + "repaired YAML bullets should not set malformedArguments", + ); + if (event!.type === "toolcall_end") { + assert.equal(event!.toolCall.arguments.milestoneId, "M005"); + assert.ok( + Array.isArray(event!.toolCall.arguments.keyDecisions), + "keyDecisions should be repaired to an array", + ); + assert.ok( + Array.isArray(event!.toolCall.arguments.keyFiles), + "keyFiles should be repaired to an array", + ); + assert.equal(event!.toolCall.arguments.title, "done"); + } + }); + + test("XML parameter tags trapped inside valid JSON strings are promoted (#3751)", () => { + const builder = new PartialMessageBuilder("claude-sonnet-4-20250514"); + const malformedJson = + '{"narrative":"text.\\nall tests pass\\n[\\"npm test\\"]","oneLiner":"done"}'; + const event = feedToolCall(builder, [malformedJson]); + + assert.ok(event, "event should not be null"); + assert.equal(event!.type, "toolcall_end"); + assert.equal((event as any).malformedArguments, undefined); + if (event!.type === "toolcall_end") { + assert.equal(event.toolCall.arguments.narrative, "text."); + assert.equal(event.toolCall.arguments.verification, "all tests pass"); + assert.deepEqual(event.toolCall.arguments.verificationEvidence, ["npm test"]); + assert.equal(event.toolCall.arguments.oneLiner, "done"); + } + }); }); diff --git a/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts b/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts index 052823590..082b40da2 100644 --- a/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts +++ b/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts @@ -1,6 +1,26 @@ import { describe, test } from "node:test"; import assert from "node:assert/strict"; -import { makeStreamExhaustedErrorMessage } from "../stream-adapter.ts"; +import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"; +import { join, resolve } from "node:path"; +import { tmpdir } from "node:os"; +import { + makeStreamExhaustedErrorMessage, + buildPromptFromContext, + buildSdkOptions, + createClaudeCodeElicitationHandler, + extractToolResultsFromSdkUserMessage, + getClaudeLookupCommand, + parseAskUserQuestionsElicitation, + parseTextInputElicitation, + parseClaudeLookupOutput, + roundResultToElicitationContent, +} from "../stream-adapter.ts"; +import type { Context, Message } from "@gsd/pi-ai"; +import type { SDKUserMessage } from "../sdk-types.ts"; + +// --------------------------------------------------------------------------- +// Existing tests — exhausted stream fallback (#2575) +// --------------------------------------------------------------------------- describe("stream-adapter — exhausted stream fallback (#2575)", () => { test("generator exhaustion becomes an error message instead of clean completion", () => { @@ -19,3 +39,607 @@ describe("stream-adapter — exhausted stream fallback (#2575)", () => { assert.match(String((message.content[0] as any)?.text ?? ""), /Claude Code error: stream_exhausted_without_result/); }); }); + +// --------------------------------------------------------------------------- +// Bug #2859 — stateless provider regression tests +// --------------------------------------------------------------------------- + +describe("stream-adapter — full context prompt (#2859)", () => { + test("buildPromptFromContext includes all user and assistant messages, not just the last user message", () => { + const context: Context = { + systemPrompt: "You are a helpful assistant.", + messages: [ + { role: "user", content: "What is 2+2?" } as Message, + { + role: "assistant", + content: [{ type: "text", text: "4" }], + api: "anthropic-messages", + provider: "claude-code", + model: "claude-sonnet-4-20250514", + usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } }, + stopReason: "stop", + timestamp: Date.now(), + } as Message, + { role: "user", content: "Now multiply that by 3" } as Message, + ], + }; + + const prompt = buildPromptFromContext(context); + + // Must contain content from BOTH user messages, not just the last + assert.ok(prompt.includes("2+2"), "prompt must include first user message"); + assert.ok(prompt.includes("multiply"), "prompt must include second user message"); + // Must contain assistant response for continuity + assert.ok(prompt.includes("4"), "prompt must include assistant reply for context"); + }); + + test("buildPromptFromContext includes system prompt when present", () => { + const context: Context = { + systemPrompt: "You are a coding assistant.", + messages: [ + { role: "user", content: "Write a function" } as Message, + ], + }; + + const prompt = buildPromptFromContext(context); + assert.ok(prompt.includes("coding assistant"), "prompt must include system prompt"); + }); + + test("buildPromptFromContext handles array content parts in user messages", () => { + const context: Context = { + messages: [ + { + role: "user", + content: [ + { type: "text", text: "First part" }, + { type: "text", text: "Second part" }, + ], + } as Message, + { role: "user", content: "Follow-up" } as Message, + ], + }; + + const prompt = buildPromptFromContext(context); + assert.ok(prompt.includes("First part"), "prompt must include array content parts"); + assert.ok(prompt.includes("Second part"), "prompt must include all text parts"); + assert.ok(prompt.includes("Follow-up"), "prompt must include follow-up message"); + }); + + test("buildPromptFromContext returns empty string for empty messages", () => { + const context: Context = { messages: [] }; + const prompt = buildPromptFromContext(context); + assert.equal(prompt, ""); + }); +}); + +describe("stream-adapter — Claude Code external tool results", () => { + test("extractToolResultsFromSdkUserMessage maps tool_result content to tool payloads", () => { + const message: SDKUserMessage = { + type: "user", + session_id: "sess-1", + parent_tool_use_id: "tool-bash-1", + message: { + role: "user", + content: [ + { + type: "tool_result", + tool_use_id: "tool-bash-1", + content: "line 1\nline 2", + is_error: false, + }, + ], + }, + }; + + const results = extractToolResultsFromSdkUserMessage(message); + assert.deepEqual(results, [ + { + toolUseId: "tool-bash-1", + result: { + content: [{ type: "text", text: "line 1\nline 2" }], + details: {}, + isError: false, + }, + }, + ]); + }); + + test("extractToolResultsFromSdkUserMessage falls back to tool_use_result", () => { + const message: SDKUserMessage = { + type: "user", + session_id: "sess-1", + parent_tool_use_id: "tool-read-1", + message: { role: "user", content: [] }, + tool_use_result: { + tool_use_id: "tool-read-1", + content: "file contents", + is_error: true, + }, + }; + + const results = extractToolResultsFromSdkUserMessage(message); + assert.deepEqual(results, [ + { + toolUseId: "tool-read-1", + result: { + content: [{ type: "text", text: "file contents" }], + details: {}, + isError: true, + }, + }, + ]); + }); +}); + +describe("stream-adapter — session persistence (#2859)", () => { + test("buildSdkOptions enables persistSession by default", () => { + const options = buildSdkOptions("claude-sonnet-4-20250514", "test prompt"); + assert.equal(options.persistSession, true, "persistSession must default to true"); + }); + + test("buildSdkOptions sets model and prompt correctly", () => { + const options = buildSdkOptions("claude-sonnet-4-20250514", "hello world"); + assert.equal(options.model, "claude-sonnet-4-20250514"); + }); + + test("buildSdkOptions enables betas for sonnet models", () => { + const sonnetOpts = buildSdkOptions("claude-sonnet-4-20250514", "test"); + assert.ok( + Array.isArray(sonnetOpts.betas) && sonnetOpts.betas.length > 0, + "sonnet models should have betas enabled", + ); + + const opusOpts = buildSdkOptions("claude-opus-4-20250514", "test"); + assert.ok( + Array.isArray(opusOpts.betas) && opusOpts.betas.length === 0, + "non-sonnet models should have empty betas", + ); + }); + + test("buildSdkOptions includes workflow MCP server config when env is set", () => { + const prev = { + GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND, + GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME, + GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS, + GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV, + GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD, + }; + try { + process.env.GSD_WORKFLOW_MCP_COMMAND = "node"; + process.env.GSD_WORKFLOW_MCP_NAME = "gsd-workflow"; + process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify(["packages/mcp-server/dist/cli.js"]); + process.env.GSD_WORKFLOW_MCP_ENV = JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }); + process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project"; + + const options = buildSdkOptions("claude-sonnet-4-20250514", "test"); + const mcpServers = options.mcpServers as Record; + assert.ok(mcpServers?.["gsd-workflow"], "expected gsd-workflow server config"); + const srv = mcpServers["gsd-workflow"]; + assert.equal(srv.command, "node"); + assert.deepEqual(srv.args, ["packages/mcp-server/dist/cli.js"]); + assert.equal(srv.cwd, "/tmp/project"); + assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd"); + assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project"); + assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]); + } finally { + process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND; + process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME; + process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS; + process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV; + process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD; + } + }); + + test("buildSdkOptions disables AskUserQuestion for custom workflow MCP server names", () => { + const prev = { + GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND, + GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME, + GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS, + GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV, + GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD, + }; + try { + process.env.GSD_WORKFLOW_MCP_COMMAND = "node"; + process.env.GSD_WORKFLOW_MCP_NAME = "custom-workflow"; + process.env.GSD_WORKFLOW_MCP_ARGS = JSON.stringify(["packages/mcp-server/dist/cli.js"]); + process.env.GSD_WORKFLOW_MCP_ENV = JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd" }); + process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project"; + + const options = buildSdkOptions("claude-sonnet-4-20250514", "test"); + const mcpServers = options.mcpServers as Record; + assert.ok(mcpServers?.["custom-workflow"], "expected custom workflow server config"); + assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]); + } finally { + process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND; + process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME; + process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS; + process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV; + process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD; + } + }); + + test("buildSdkOptions auto-discovers bundled MCP server even without env hints", () => { + const prev = { + GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND, + GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME, + GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS, + GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV, + GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD, + }; + try { + delete process.env.GSD_WORKFLOW_MCP_COMMAND; + delete process.env.GSD_WORKFLOW_MCP_NAME; + delete process.env.GSD_WORKFLOW_MCP_ARGS; + delete process.env.GSD_WORKFLOW_MCP_ENV; + delete process.env.GSD_WORKFLOW_MCP_CWD; + + const originalCwd = process.cwd(); + const emptyDir = mkdtempSync(join(tmpdir(), "claude-mcp-none-")); + process.chdir(emptyDir); + const options = buildSdkOptions("claude-sonnet-4-20250514", "test"); + process.chdir(originalCwd); + // The bundled CLI may or may not be discoverable depending on + // whether the build output exists relative to import.meta.url. + // Either outcome is valid — the key invariant is no crash. + const mcpServers = (options as any).mcpServers; + if (mcpServers) { + assert.ok(mcpServers["gsd-workflow"], "if present, must be gsd-workflow"); + assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]); + } else { + assert.deepEqual((options as any).disallowedTools, ["AskUserQuestion"]); + } + rmSync(emptyDir, { recursive: true, force: true }); + } finally { + process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND; + process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME; + process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS; + process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV; + process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD; + } + }); + + test("buildSdkOptions auto-detects local workflow MCP dist CLI when present", () => { + const prev = { + GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND, + GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME, + GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS, + GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV, + GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD, + GSD_CLI_PATH: process.env.GSD_CLI_PATH, + }; + const originalCwd = process.cwd(); + const repoDir = mkdtempSync(join(tmpdir(), "claude-mcp-detect-")); + try { + delete process.env.GSD_WORKFLOW_MCP_COMMAND; + delete process.env.GSD_WORKFLOW_MCP_NAME; + delete process.env.GSD_WORKFLOW_MCP_ARGS; + delete process.env.GSD_WORKFLOW_MCP_ENV; + delete process.env.GSD_WORKFLOW_MCP_CWD; + process.env.GSD_CLI_PATH = "/tmp/gsd"; + + const distDir = join(repoDir, "packages", "mcp-server", "dist"); + mkdirSync(distDir, { recursive: true }); + writeFileSync(join(distDir, "cli.js"), "#!/usr/bin/env node\n"); + process.chdir(repoDir); + const resolvedRepoDir = realpathSync(repoDir); + + const options = buildSdkOptions("claude-sonnet-4-20250514", "test"); + const mcpServers = options.mcpServers as Record; + assert.ok(mcpServers?.["gsd-workflow"], "expected gsd-workflow server config"); + const srv = mcpServers["gsd-workflow"]; + assert.equal(srv.command, process.execPath); + assert.deepEqual(srv.args, [realpathSync(resolve(repoDir, "packages", "mcp-server", "dist", "cli.js"))]); + assert.equal(srv.cwd, resolvedRepoDir); + assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd"); + assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, resolvedRepoDir); + assert.deepEqual(options.disallowedTools, ["AskUserQuestion"]); + } finally { + process.chdir(originalCwd); + rmSync(repoDir, { recursive: true, force: true }); + process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND; + process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME; + process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS; + process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV; + process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD; + process.env.GSD_CLI_PATH = prev.GSD_CLI_PATH; + } + }); + + test("buildSdkOptions preserves runtime callbacks such as onElicitation", () => { + const prev = { + GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND, + GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME, + GSD_WORKFLOW_MCP_ARGS: process.env.GSD_WORKFLOW_MCP_ARGS, + GSD_WORKFLOW_MCP_ENV: process.env.GSD_WORKFLOW_MCP_ENV, + GSD_WORKFLOW_MCP_CWD: process.env.GSD_WORKFLOW_MCP_CWD, + }; + const onElicitation = async () => ({ action: "decline" as const }); + try { + delete process.env.GSD_WORKFLOW_MCP_COMMAND; + delete process.env.GSD_WORKFLOW_MCP_NAME; + delete process.env.GSD_WORKFLOW_MCP_ARGS; + delete process.env.GSD_WORKFLOW_MCP_ENV; + delete process.env.GSD_WORKFLOW_MCP_CWD; + const options = buildSdkOptions("claude-sonnet-4-20250514", "test", { onElicitation }); + assert.equal(options.onElicitation, onElicitation); + } finally { + process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND; + process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME; + process.env.GSD_WORKFLOW_MCP_ARGS = prev.GSD_WORKFLOW_MCP_ARGS; + process.env.GSD_WORKFLOW_MCP_ENV = prev.GSD_WORKFLOW_MCP_ENV; + process.env.GSD_WORKFLOW_MCP_CWD = prev.GSD_WORKFLOW_MCP_CWD; + } + }); +}); + +describe("stream-adapter — MCP elicitation bridge", () => { + const askUserQuestionsRequest = { + serverName: "gsd-workflow", + message: "Please answer the following question(s).", + mode: "form" as const, + requestedSchema: { + type: "object" as const, + properties: { + storage_scope: { + type: "string", + title: "Storage", + description: "Does this app need to sync across devices?", + oneOf: [ + { const: "Local-only (Recommended)", title: "Local-only (Recommended)" }, + { const: "Cloud-synced", title: "Cloud-synced" }, + { const: "None of the above", title: "None of the above" }, + ], + }, + storage_scope__note: { + type: "string", + title: "Storage Note", + description: "Optional note for None of the above.", + }, + platform: { + type: "array", + title: "Platform", + description: "Where should it run?", + items: { + anyOf: [ + { const: "Web", title: "Web" }, + { const: "Desktop", title: "Desktop" }, + { const: "Mobile", title: "Mobile" }, + ], + }, + }, + }, + }, + }; + + test("parseAskUserQuestionsElicitation rebuilds interview questions from the MCP schema", () => { + const questions = parseAskUserQuestionsElicitation(askUserQuestionsRequest); + assert.deepEqual(questions, [ + { + id: "storage_scope", + header: "Storage", + question: "Does this app need to sync across devices?", + options: [ + { label: "Local-only (Recommended)", description: "" }, + { label: "Cloud-synced", description: "" }, + ], + noteFieldId: "storage_scope__note", + }, + { + id: "platform", + header: "Platform", + question: "Where should it run?", + options: [ + { label: "Web", description: "" }, + { label: "Desktop", description: "" }, + { label: "Mobile", description: "" }, + ], + allowMultiple: true, + }, + ]); + }); + + test("roundResultToElicitationContent preserves notes for None of the above", () => { + const questions = parseAskUserQuestionsElicitation(askUserQuestionsRequest); + assert.ok(questions); + + const content = roundResultToElicitationContent(questions, { + endInterview: false, + answers: { + storage_scope: { + selected: "None of the above", + notes: "Needs selective sync later", + }, + platform: { + selected: ["Web", "Desktop"], + notes: "", + }, + }, + }); + + assert.deepEqual(content, { + storage_scope: "None of the above", + storage_scope__note: "Needs selective sync later", + platform: ["Web", "Desktop"], + }); + }); + + test("createClaudeCodeElicitationHandler accepts interview-style answers from custom UI", async () => { + const handler = createClaudeCodeElicitationHandler({ + custom: async (_factory: any) => ({ + endInterview: false, + answers: { + storage_scope: { + selected: "Cloud-synced", + notes: "", + }, + platform: { + selected: ["Web", "Mobile"], + notes: "", + }, + }, + }), + } as any); + + assert.ok(handler); + const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal }); + assert.deepEqual(result, { + action: "accept", + content: { + storage_scope: "Cloud-synced", + platform: ["Web", "Mobile"], + }, + }); + }); + + test("createClaudeCodeElicitationHandler falls back to dialog prompts when custom UI is unavailable", async () => { + const ui = { + custom: async () => undefined, + select: async (_title: string, options: string[], opts?: { allowMultiple?: boolean }) => { + if (opts?.allowMultiple) return ["Desktop", "Mobile"]; + return options.includes("None of the above") ? "None of the above" : options[0]; + }, + input: async () => "CLI-only deployment target", + }; + const handler = createClaudeCodeElicitationHandler(ui as any); + assert.ok(handler); + + const result = await handler!(askUserQuestionsRequest, { signal: new AbortController().signal }); + assert.deepEqual(result, { + action: "accept", + content: { + storage_scope: "None of the above", + storage_scope__note: "CLI-only deployment target", + platform: ["Desktop", "Mobile"], + }, + }); + }); + + test("parseTextInputElicitation recognizes secure free-text MCP forms", () => { + const request = { + serverName: "gsd-workflow", + message: "Enter values for environment variables.", + mode: "form" as const, + requestedSchema: { + type: "object" as const, + properties: { + TEST_PASSWORD: { + type: "string", + title: "TEST_PASSWORD", + description: "Format: min 8 characters\nLeave empty to skip.", + }, + PROJECT_NAME: { + type: "string", + title: "PROJECT_NAME", + description: "Human-readable project name.", + }, + }, + }, + }; + + const parsed = parseTextInputElicitation(request as any); + assert.deepEqual(parsed, [ + { + id: "TEST_PASSWORD", + title: "TEST_PASSWORD", + description: "Format: min 8 characters\nLeave empty to skip.", + required: false, + secure: true, + }, + { + id: "PROJECT_NAME", + title: "PROJECT_NAME", + description: "Human-readable project name.", + required: false, + secure: false, + }, + ]); + }); + + test("parseTextInputElicitation accepts legacy keys schema and skips unsupported fields", () => { + const request = { + serverName: "gsd-workflow", + message: "Enter secure values", + mode: "form" as const, + requestedSchema: { + type: "object" as const, + keys: { + API_TOKEN: { + type: "string", + title: "API_TOKEN", + description: "Leave empty to skip.", + }, + META: { + type: "object", + title: "metadata", + }, + }, + }, + }; + + const parsed = parseTextInputElicitation(request as any); + assert.deepEqual(parsed, [ + { + id: "API_TOKEN", + title: "API_TOKEN", + description: "Leave empty to skip.", + required: false, + secure: true, + }, + ]); + }); + + test("createClaudeCodeElicitationHandler collects secure_env_collect fields through input dialogs", async () => { + const secureRequest = { + serverName: "gsd-workflow", + message: "Enter values for environment variables.", + mode: "form" as const, + requestedSchema: { + type: "object" as const, + properties: { + TEST_PASSWORD: { + type: "string", + title: "TEST_PASSWORD", + description: "Format: Your secure testing password\nLeave empty to skip.", + }, + }, + }, + }; + + const inputCalls: Array<{ opts?: { secure?: boolean } }> = []; + const handler = createClaudeCodeElicitationHandler({ + input: async (_title: string, _placeholder?: string, opts?: { secure?: boolean }) => { + inputCalls.push({ opts }); + return "super-secret"; + }, + } as any); + assert.ok(handler); + + const result = await handler!(secureRequest as any, { signal: new AbortController().signal }); + assert.deepEqual(result, { + action: "accept", + content: { + TEST_PASSWORD: "super-secret", + }, + }); + assert.equal(inputCalls.length, 1); + assert.equal(inputCalls[0]?.opts?.secure, true, "secure_env_collect fields should request secure input"); + }); +}); + +describe("stream-adapter — Windows Claude path lookup (#3770)", () => { + test("getClaudeLookupCommand uses where on Windows", () => { + assert.equal(getClaudeLookupCommand("win32"), "where claude"); + }); + + test("getClaudeLookupCommand uses which on non-Windows platforms", () => { + assert.equal(getClaudeLookupCommand("darwin"), "which claude"); + assert.equal(getClaudeLookupCommand("linux"), "which claude"); + }); + + test("parseClaudeLookupOutput keeps the first native path from multi-line lookup output", () => { + const output = "C:\\Users\\Binoy\\.local\\bin\\claude.exe\r\nC:\\Program Files\\Claude\\claude.exe\r\n"; + assert.equal(parseClaudeLookupOutput(output), "C:\\Users\\Binoy\\.local\\bin\\claude.exe"); + }); +}); diff --git a/src/resources/extensions/cmux/index.ts b/src/resources/extensions/cmux/index.ts index 9843b710e..9c6d01819 100644 --- a/src/resources/extensions/cmux/index.ts +++ b/src/resources/extensions/cmux/index.ts @@ -1,12 +1,9 @@ -import { execFile, execFileSync } from "node:child_process"; +import { execFileSync, spawn } from "node:child_process"; import { existsSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { promisify } from "node:util"; import type { GSDPreferences } from "../gsd/preferences.js"; import type { GSDState, Phase } from "../gsd/types.js"; - -const execFileAsync = promisify(execFile); const DEFAULT_SOCKET_PATH = "/tmp/cmux.sock"; const STATUS_KEY = "gsd"; const lastSidebarSnapshots = new Map(); @@ -200,6 +197,7 @@ export class CmuxClient { return execFileSync("cmux", args, { encoding: "utf-8", timeout: 3000, + stdio: ["ignore", "pipe", "pipe"], env: process.env, }); } catch { @@ -209,16 +207,24 @@ export class CmuxClient { private async runAsync(args: string[]): Promise { if (!this.canRun()) return null; - try { - const result = await execFileAsync("cmux", args, { - encoding: "utf-8", - timeout: 5000, + return new Promise((resolve) => { + const child = spawn("cmux", args, { + stdio: ["ignore", "pipe", "pipe"], env: process.env, }); - return result.stdout; - } catch { - return null; - } + const chunks: Buffer[] = []; + let settled = false; + const done = (result: string | null) => { + if (!settled) { settled = true; resolve(result); } + }; + const timer = setTimeout(() => { child.kill(); done(null); }, 5000); + child.stdout!.on("data", (chunk: Buffer) => chunks.push(chunk)); + child.on("close", (code) => { + clearTimeout(timer); + done(code === 0 ? Buffer.concat(chunks).toString("utf-8") : null); + }); + child.on("error", () => { clearTimeout(timer); done(null); }); + }); } getCapabilities(): unknown | null { diff --git a/src/resources/extensions/context7/extension-manifest.json b/src/resources/extensions/context7/extension-manifest.json index e95788267..d5bf3098e 100644 --- a/src/resources/extensions/context7/extension-manifest.json +++ b/src/resources/extensions/context7/extension-manifest.json @@ -7,6 +7,6 @@ "requires": { "platform": ">=2.29.0" }, "provides": { "tools": ["resolve_library", "get_library_docs"], - "hooks": ["session_start"] + "hooks": ["session_start", "session_shutdown"] } } diff --git a/src/resources/extensions/get-secrets-from-user.ts b/src/resources/extensions/get-secrets-from-user.ts index 300852305..967752048 100644 --- a/src/resources/extensions/get-secrets-from-user.ts +++ b/src/resources/extensions/get-secrets-from-user.ts @@ -47,6 +47,14 @@ function shellEscapeSingle(value: string): string { return `'${value.replace(/'/g, `'\\''`)}'`; } +function isSafeEnvVarKey(key: string): boolean { + return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key); +} + +function isSupportedDeploymentEnvironment(env: string): boolean { + return env === "development" || env === "preview" || env === "production"; +} + function hydrateProcessEnv(key: string, value: string): void { // Make newly collected secrets immediately visible to the current session. // Some extensions read process.env directly and do not reload .env on every call. @@ -54,6 +62,9 @@ function hydrateProcessEnv(key: string, value: string): void { } async function writeEnvKey(filePath: string, key: string, value: string): Promise { + if (typeof value !== "string") { + throw new TypeError(`writeEnvKey expects a string value for key "${key}", got ${typeof value}`); + } let content = ""; try { content = await readFile(filePath, "utf8"); @@ -115,7 +126,7 @@ async function collectOneSecret( ): Promise { if (!ctx.hasUI) return null; - return ctx.ui.custom((tui: any, theme: any, _kb: any, done: (r: string | null) => void) => { + const customResult = await ctx.ui.custom((tui: any, theme: any, _kb: any, done: (r: string | null) => void) => { let value = ""; let cachedLines: string[] | undefined; @@ -212,6 +223,29 @@ async function collectOneSecret( handleInput, }; }); + + // RPC/web surfaces may not implement ctx.ui.custom(). Fall back to a + // standard input prompt so users can still provide the secret. + if (customResult !== undefined) { + return customResult; + } + + if (typeof ctx.ui?.input !== "function") { + return null; + } + + const inputTitle = `Secure value for ${keyName} (${pageIndex + 1}/${totalPages})`; + const inputPlaceholder = hint || "Enter secret value"; + const inputResult = await ctx.ui.input( + inputTitle, + inputPlaceholder, + { secure: true }, + ); + if (typeof inputResult !== "string") { + return null; + } + const trimmed = inputResult.trim(); + return trimmed.length > 0 ? trimmed : null; } /** @@ -327,12 +361,22 @@ async function applySecrets( if ((destination === "vercel" || destination === "convex") && opts.exec) { const env = opts.environment ?? "development"; + if (!isSupportedDeploymentEnvironment(env)) { + errors.push(`environment: unsupported target environment "${env}"`); + return { applied, errors }; + } for (const { key, value } of provided) { + if (!isSafeEnvVarKey(key)) { + errors.push(`${key}: invalid environment variable name`); + continue; + } const cmd = destination === "vercel" ? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}` - : `npx convex env set ${key} ${shellEscapeSingle(value)}`; + : ""; try { - const result = await opts.exec("sh", ["-c", cmd]); + const result = destination === "vercel" + ? await opts.exec("sh", ["-c", cmd]) + : await opts.exec("npx", ["convex", "env", "set", key, value]); if (result.code !== 0) { errors.push(`${key}: ${result.stderr.slice(0, 200)}`); } else { @@ -419,7 +463,7 @@ export async function collectSecretsFromManifest( for (const { key, value } of collected) { const entry = manifest.entries.find((e) => e.key === key); if (entry) { - entry.status = value !== null ? "collected" : "skipped"; + entry.status = value != null ? "collected" : "skipped"; } } @@ -427,14 +471,14 @@ export async function collectSecretsFromManifest( await writeFile(manifestPath, formatSecretsManifest(manifest), "utf8"); // (j) Apply collected values to destination - const provided = collected.filter((c) => c.value !== null) as Array<{ key: string; value: string }>; + const provided = collected.filter((c) => c.value != null) as Array<{ key: string; value: string }>; const { applied } = await applySecrets(provided, destination, { envFilePath: resolve(ctx.cwd, ".env"), }); const skipped = [ ...alreadySkipped, - ...collected.filter((c) => c.value === null).map((c) => c.key), + ...collected.filter((c) => c.value == null).map((c) => c.key), ]; return { applied, skipped, existingSkipped }; @@ -505,8 +549,8 @@ export default function secureEnv(pi: ExtensionAPI) { collected.push({ key: item.key, value }); } - const provided = collected.filter((c) => c.value !== null) as Array<{ key: string; value: string }>; - const skipped = collected.filter((c) => c.value === null).map((c) => c.key); + const provided = collected.filter((c) => c.value != null) as Array<{ key: string; value: string }>; + const skipped = collected.filter((c) => c.value == null).map((c) => c.key); // Apply to destination via shared helper const { applied, errors } = await applySecrets(provided, destination, { diff --git a/src/resources/extensions/google-search/extension-manifest.json b/src/resources/extensions/google-search/extension-manifest.json index b2938627d..c4a775a4d 100644 --- a/src/resources/extensions/google-search/extension-manifest.json +++ b/src/resources/extensions/google-search/extension-manifest.json @@ -7,6 +7,6 @@ "requires": { "platform": ">=2.29.0" }, "provides": { "tools": ["google_search"], - "hooks": ["session_start"] + "hooks": ["session_start", "session_shutdown"] } } diff --git a/src/resources/extensions/google-search/index.ts b/src/resources/extensions/google-search/index.ts index 4f4f0fff6..a4f9818f4 100644 --- a/src/resources/extensions/google-search/index.ts +++ b/src/resources/extensions/google-search/index.ts @@ -79,7 +79,7 @@ async function searchWithOAuth( signal?: AbortSignal, ): Promise { const model = process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash"; - const url = `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent`; + const url = `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse`; const GEMINI_CLI_HEADERS = { ideType: "IDE_UNSPECIFIED", @@ -104,6 +104,7 @@ async function searchWithOAuth( contents: [{ parts: [{ text: query }] }], tools: [{ googleSearch: {} }], }, + userAgent: "pi-coding-agent", }), signal, }); diff --git a/src/resources/extensions/gsd/auto-artifact-paths.ts b/src/resources/extensions/gsd/auto-artifact-paths.ts index df8b52ad2..6e54f5b07 100644 --- a/src/resources/extensions/gsd/auto-artifact-paths.ts +++ b/src/resources/extensions/gsd/auto-artifact-paths.ts @@ -56,7 +56,7 @@ export function resolveExpectedArtifactPath( } case "run-uat": { const dir = resolveSlicePath(base, mid, sid!); - return dir ? join(dir, buildSliceFileName(sid!, "UAT")) : null; + return dir ? join(dir, buildSliceFileName(sid!, "ASSESSMENT")) : null; } case "execute-task": { const dir = resolveSlicePath(base, mid, sid!); @@ -124,7 +124,7 @@ export function diagnoseExpectedArtifact( case "reassess-roadmap": return `${relSliceFile(base, mid, sid!, "ASSESSMENT")} (roadmap reassessment)`; case "run-uat": - return `${relSliceFile(base, mid, sid!, "UAT")} (UAT result)`; + return `${relSliceFile(base, mid, sid!, "ASSESSMENT")} (UAT assessment result)`; case "validate-milestone": return `${relMilestoneFile(base, mid, "VALIDATION")} (milestone validation report)`; case "complete-milestone": diff --git a/src/resources/extensions/gsd/auto-dashboard.ts b/src/resources/extensions/gsd/auto-dashboard.ts index 98a6ff052..e69cb78ad 100644 --- a/src/resources/extensions/gsd/auto-dashboard.ts +++ b/src/resources/extensions/gsd/auto-dashboard.ts @@ -11,11 +11,13 @@ import type { GSDState } from "./types.js"; import { getCurrentBranch } from "./worktree.js"; import { getActiveHook } from "./post-unit-hooks.js"; import { getLedger, getProjectTotals } from "./metrics.js"; +import { getErrorMessage } from "./error-utils.js"; import { resolveMilestoneFile, resolveSliceFile, } from "./paths.js"; import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js"; +import { formatShortcut } from "./files.js"; import { readFileSync, writeFileSync, existsSync } from "node:fs"; import { execFileSync } from "node:child_process"; import { truncateToWidth, visibleWidth } from "@gsd/pi-tui"; @@ -23,7 +25,11 @@ import { makeUI } from "../shared/tui.js"; import { GLYPH, INDENT } from "../shared/mod.js"; import { computeProgressScore } from "./progress-score.js"; import { getActiveWorktreeName } from "./worktree-command.js"; -import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js"; +import { + getGlobalGSDPreferencesPath, + getProjectGSDPreferencesPath, + parsePreferencesMarkdown, +} from "./preferences.js"; import { resolveServiceTierIcon, getEffectiveServiceTier } from "./service-tier.js"; import { parseUnitId } from "./unit-id.js"; import { @@ -31,6 +37,7 @@ import { getRtkSessionSavings, type RtkSessionSavings, } from "../shared/rtk-session-stats.js"; +import { logWarning } from "./workflow-logger.js"; // ─── UAT Slice Extraction ───────────────────────────────────────────────────── @@ -285,8 +292,9 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?: taskDetails = dbTasks.map(t => ({ id: t.id, title: t.title, done: t.status === "complete" || t.status === "done" })); } } - } catch { + } catch (err) { // Non-fatal — just omit task count + logWarning("dashboard", `operation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -297,8 +305,9 @@ export function updateSliceProgressCache(base: string, mid: string, activeSid?: activeSliceTasks, taskDetails, }; - } catch { + } catch (err) { // Non-fatal — widget just won't show progress bar + logWarning("dashboard", `operation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -332,8 +341,9 @@ function refreshLastCommit(basePath: string): void { }; } lastCommitFetchedAt = Date.now(); - } catch { + } catch (err) { // Non-fatal — just skip last commit display + logWarning("dashboard", `operation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -365,24 +375,74 @@ export type WidgetMode = "full" | "small" | "min" | "off"; const WIDGET_MODES: WidgetMode[] = ["full", "small", "min", "off"]; let widgetMode: WidgetMode = "full"; let widgetModeInitialized = false; +let widgetModePreferencePath: string | null = null; + +function safeReadTextFile(path: string): string | null { + try { + if (!existsSync(path)) return null; + return readFileSync(path, "utf-8"); + } catch { + return null; + } +} + +function readWidgetModeFromFile(path: string): WidgetMode | undefined { + const raw = safeReadTextFile(path); + if (!raw) return undefined; + const prefs = parsePreferencesMarkdown(raw); + const saved = prefs?.widget_mode; + if (saved && WIDGET_MODES.includes(saved as WidgetMode)) { + return saved as WidgetMode; + } + return undefined; +} + +function resolveWidgetModePreferencePath( + projectPath = getProjectGSDPreferencesPath(), + globalPath = getGlobalGSDPreferencesPath(), +): string { + if (readWidgetModeFromFile(projectPath)) { + return projectPath; + } + + if (readWidgetModeFromFile(globalPath)) { + return globalPath; + } + + if (safeReadTextFile(projectPath) !== null) return projectPath; + if (safeReadTextFile(globalPath) !== null) return globalPath; + return getGlobalGSDPreferencesPath(); +} /** Load widget mode from preferences (once). */ -function ensureWidgetModeLoaded(): void { +function ensureWidgetModeLoaded(projectPath?: string, globalPath?: string): void { if (widgetModeInitialized) return; widgetModeInitialized = true; try { - const loaded = loadEffectiveGSDPreferences(); - const saved = loaded?.preferences?.widget_mode; + const resolvedProjectPath = projectPath ?? getProjectGSDPreferencesPath(); + const resolvedGlobalPath = globalPath ?? getGlobalGSDPreferencesPath(); + const saved = readWidgetModeFromFile(resolvedProjectPath) ?? readWidgetModeFromFile(resolvedGlobalPath); if (saved && WIDGET_MODES.includes(saved as WidgetMode)) { widgetMode = saved as WidgetMode; } - } catch { /* non-fatal — use default */ } + widgetModePreferencePath = resolveWidgetModePreferencePath(resolvedProjectPath, resolvedGlobalPath); + } catch (err) { /* non-fatal — use default */ + logWarning("dashboard", `operation failed: ${getErrorMessage(err)}`); + widgetModePreferencePath = getGlobalGSDPreferencesPath(); + } } -/** Persist widget mode to global preferences YAML. */ -function persistWidgetMode(mode: WidgetMode): void { +/** + * Persist widget mode to the preference file that owns the effective value. + * Project-scoped widget_mode wins over global; if neither scope defines it, + * we prefer an existing project preferences file and otherwise fall back to + * the global preferences file. + */ +function persistWidgetMode( + mode: WidgetMode, + prefsPath = widgetModePreferencePath ?? resolveWidgetModePreferencePath(), +): void { try { - const prefsPath = getGlobalGSDPreferencesPath(); let content = ""; if (existsSync(prefsPath)) { content = readFileSync(prefsPath, "utf-8"); @@ -395,30 +455,40 @@ function persistWidgetMode(mode: WidgetMode): void { content = content.trimEnd() + "\n" + line + "\n"; } writeFileSync(prefsPath, content, "utf-8"); - } catch { /* non-fatal — mode still set in memory */ } + } catch (err) { /* non-fatal — mode still set in memory */ + logWarning("dashboard", `file write failed: ${err instanceof Error ? err.message : String(err)}`); + } } /** Cycle to the next widget mode. Returns the new mode. */ -export function cycleWidgetMode(): WidgetMode { - ensureWidgetModeLoaded(); +export function cycleWidgetMode(projectPath?: string, globalPath?: string): WidgetMode { + ensureWidgetModeLoaded(projectPath, globalPath); const idx = WIDGET_MODES.indexOf(widgetMode); widgetMode = WIDGET_MODES[(idx + 1) % WIDGET_MODES.length]; - persistWidgetMode(widgetMode); + persistWidgetMode(widgetMode, widgetModePreferencePath ?? resolveWidgetModePreferencePath(projectPath, globalPath)); return widgetMode; } /** Set widget mode directly. */ -export function setWidgetMode(mode: WidgetMode): void { +export function setWidgetMode(mode: WidgetMode, projectPath?: string, globalPath?: string): void { + ensureWidgetModeLoaded(projectPath, globalPath); widgetMode = mode; - persistWidgetMode(widgetMode); + persistWidgetMode(widgetMode, widgetModePreferencePath ?? resolveWidgetModePreferencePath(projectPath, globalPath)); } /** Get current widget mode. */ -export function getWidgetMode(): WidgetMode { - ensureWidgetModeLoaded(); +export function getWidgetMode(projectPath?: string, globalPath?: string): WidgetMode { + ensureWidgetModeLoaded(projectPath, globalPath); return widgetMode; } +/** Test-only reset for widget mode caching. */ +export function _resetWidgetModeForTests(): void { + widgetMode = "full"; + widgetModeInitialized = false; + widgetModePreferencePath = null; +} + // ─── Progress Widget ────────────────────────────────────────────────────────── /** State accessors passed to updateProgressWidget to avoid direct global access */ @@ -430,6 +500,8 @@ export interface WidgetStateAccessors { isVerbose(): boolean; /** True while newSession() is in-flight — render must not access session state. */ isSessionSwitching(): boolean; + /** Fully-qualified dispatched model ID (provider/id) set after model selection + hook overrides (#2899). */ + getCurrentDispatchedModelId(): string | null; } export function updateProgressWidget( @@ -458,7 +530,9 @@ export function updateProgressWidget( // Cache git branch at widget creation time (not per render) let cachedBranch: string | null = null; - try { cachedBranch = getCurrentBranch(accessors.getBasePath()); } catch { /* not in git repo */ } + try { cachedBranch = getCurrentBranch(accessors.getBasePath()); } catch (err) { /* not in git repo */ + logWarning("dashboard", `git branch detection failed: ${err instanceof Error ? err.message : String(err)}`); + } // Cache short pwd (last 2 path segments only) + worktree/branch info let widgetPwd: string; @@ -495,7 +569,8 @@ export function updateProgressWidget( const sessionId = ctx.sessionManager.getSessionId(); const savings = sessionId ? getRtkSessionSavings(accessors.getBasePath(), sessionId) : null; cachedRtkLabel = formatRtkSavingsLabel(savings); - } catch { + } catch (err) { + logWarning("dashboard", `RTK savings lookup failed: ${err instanceof Error ? (err as Error).message : String(err)}`); cachedRtkLabel = null; } }; @@ -519,7 +594,9 @@ export function updateProgressWidget( } refreshRtkLabel(); cachedLines = undefined; - } catch { /* non-fatal */ } + } catch (err) { /* non-fatal */ + logWarning("dashboard", `DB status update failed: ${err instanceof Error ? err.message : String(err)}`); + } }, 15_000); return { @@ -569,6 +646,14 @@ export function updateProgressWidget( : ""; lines.push(rightAlign(headerLeft, headerRight, width)); + // Worktree/branch right-aligned below header + const branchLabel = worktreeName && cachedBranch + ? `${worktreeName} (${cachedBranch})` + : cachedBranch ?? ""; + if (branchLabel) { + lines.push(rightAlign("", theme.fg("dim", branchLabel), width)); + } + // Show health signal details when degraded (yellow/red) if (score.level !== "green" && score.signals.length > 0 && widgetMode !== "min") { // Show up to 3 most relevant signals in compact form @@ -609,9 +694,15 @@ export function updateProgressWidget( const cxPctVal = cxUsage?.percent ?? 0; const cxPct = cxUsage?.percent !== null ? cxPctVal.toFixed(1) : "?"; - // Model display — shown in context section, not stats - const modelId = cmdCtx?.model?.id ?? ""; - const modelProvider = cmdCtx?.model?.provider ?? ""; + // Model display — prefer dispatched model ID (set after selectAndApplyModel + // + hook overrides) over cmdCtx?.model which can be stale (#2899). + const dispatchedModelId = accessors.getCurrentDispatchedModelId(); + const modelId = dispatchedModelId + ? dispatchedModelId.split("/").slice(1).join("/") || dispatchedModelId + : (cmdCtx?.model?.id ?? ""); + const modelProvider = dispatchedModelId + ? dispatchedModelId.split("/")[0] || "" + : (cmdCtx?.model?.provider ?? ""); const tierIcon = resolveServiceTierIcon(effectiveServiceTier, modelId); const modelDisplay = (modelProvider && modelId ? `${modelProvider}/${modelId}` @@ -682,12 +773,12 @@ export function updateProgressWidget( const hasContext = !!(mid || (slice && unitType !== "research-milestone" && unitType !== "plan-milestone")); if (mid) { const modelTag = modelDisplay ? theme.fg("muted", ` ${modelDisplay}`) : ""; - lines.push(truncateToWidth(`${pad}${theme.fg("dim", mid.title)}${modelTag}`, width)); + lines.push(truncateToWidth(`${pad}${theme.fg("dim", mid.title)}${modelTag}`, width, "…")); } if (slice && unitType !== "research-milestone" && unitType !== "plan-milestone") { lines.push(truncateToWidth( `${pad}${theme.fg("text", theme.bold(`${slice.id}: ${slice.title}`))}`, - width, + width, "…", )); } if (hasContext) lines.push(""); @@ -733,6 +824,12 @@ export function updateProgressWidget( const rightLines: string[] = []; const maxVisibleTasks = 8; + // Max visible chars for task title text (before ANSI theming) + const maxTaskTitleLen = 45; + function truncTitle(s: string): string { + return s.length > maxTaskTitleLen ? s.slice(0, maxTaskTitleLen - 1) + "…" : s; + } + function formatTaskLine(t: { id: string; title: string; done: boolean }, isCurrent: boolean): string { const glyph = t.done ? theme.fg("success", "*") @@ -744,11 +841,12 @@ export function updateProgressWidget( : t.done ? theme.fg("muted", t.id) : theme.fg("dim", t.id); + const short = truncTitle(t.title); const title = isCurrent - ? theme.fg("text", t.title) + ? theme.fg("text", short) : t.done - ? theme.fg("muted", t.title) - : theme.fg("text", t.title); + ? theme.fg("muted", short) + : theme.fg("text", short); return `${glyph} ${id}: ${title}`; } @@ -771,7 +869,7 @@ export function updateProgressWidget( if (maxRows > 0) { lines.push(""); for (let i = 0; i < maxRows; i++) { - const left = padToWidth(truncateToWidth(leftLines[i] ?? "", leftColWidth), leftColWidth); + const left = padToWidth(truncateToWidth(leftLines[i] ?? "", leftColWidth, "…"), leftColWidth); const right = rightLines[i] ?? ""; lines.push(`${left}${right}`); } @@ -779,7 +877,7 @@ export function updateProgressWidget( } else { if (leftLines.length > 0) { lines.push(""); - for (const l of leftLines) lines.push(truncateToWidth(l, width)); + for (const l of leftLines) lines.push(truncateToWidth(l, width, "…")); } } @@ -808,23 +906,27 @@ export function updateProgressWidget( lines.push(rightAlign("", theme.fg("dim", cachedRtkLabel), width)); } } - // PWD line with last commit info right-aligned + // Last commit info const lastCommit = getLastCommit(accessors.getBasePath()); - const commitStr = lastCommit - ? theme.fg("dim", `${lastCommit.timeAgo} ago: ${lastCommit.message}`) + const maxCommitLen = 65; + const commitMsg = lastCommit + ? lastCommit.message.length > maxCommitLen + ? lastCommit.message.slice(0, maxCommitLen - 1) + "…" + : lastCommit.message : ""; - const pwdStr = theme.fg("dim", widgetPwd); - if (commitStr) { - lines.push(rightAlign(`${pad}${pwdStr}`, truncateToWidth(commitStr, Math.floor(width * 0.45)), width)); - } else { - lines.push(`${pad}${pwdStr}`); - } // Hints line const hintParts: string[] = []; hintParts.push("esc pause"); - hintParts.push(process.platform === "darwin" ? "⌃⌥G dashboard" : "Ctrl+Alt+G dashboard"); + hintParts.push(`${formatShortcut("Ctrl+Alt+G")} dashboard`); const hintStr = theme.fg("dim", hintParts.join(" | ")); - lines.push(rightAlign("", hintStr, width)); + const commitStr = lastCommit + ? theme.fg("dim", `${lastCommit.timeAgo} ago: ${commitMsg}`) + : ""; + if (commitStr) { + lines.push(rightAlign(`${pad}${commitStr}`, hintStr, width)); + } else { + lines.push(rightAlign("", hintStr, width)); + } lines.push(...ui.bar()); @@ -851,12 +953,12 @@ function rightAlign(left: string, right: string, width: number): string { const leftVis = visibleWidth(left); const rightVis = visibleWidth(right); const gap = Math.max(1, width - leftVis - rightVis); - return truncateToWidth(left + " ".repeat(gap) + right, width); + return truncateToWidth(left + " ".repeat(gap) + right, width, "…"); } /** Pad a string with trailing spaces to fill exactly `colWidth` (ANSI-aware). */ function padToWidth(s: string, colWidth: number): string { const vis = visibleWidth(s); - if (vis >= colWidth) return truncateToWidth(s, colWidth); + if (vis >= colWidth) return truncateToWidth(s, colWidth, "…"); return s + " ".repeat(colWidth - vis); } diff --git a/src/resources/extensions/gsd/auto-direct-dispatch.ts b/src/resources/extensions/gsd/auto-direct-dispatch.ts index ab89687be..306bca441 100644 --- a/src/resources/extensions/gsd/auto-direct-dispatch.ts +++ b/src/resources/extensions/gsd/auto-direct-dispatch.ts @@ -29,6 +29,10 @@ import { } from "./auto-prompts.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; import { pauseAuto } from "./auto.js"; +import { + getWorkflowTransportSupportError, + getRequiredWorkflowToolsForAutoUnit, +} from "./workflow-mcp.js"; export async function dispatchDirectPhase( ctx: ExtensionCommandContext, @@ -243,6 +247,22 @@ export async function dispatchDirectPhase( return; } + const compatibilityError = getWorkflowTransportSupportError( + ctx.model?.provider, + getRequiredWorkflowToolsForAutoUnit(unitType), + { + projectRoot: base, + surface: "direct phase dispatch", + unitType, + authMode: ctx.model?.provider ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) : undefined, + baseUrl: ctx.model?.baseUrl, + }, + ); + if (compatibilityError) { + ctx.ui.notify(compatibilityError, "error"); + return; + } + ctx.ui.notify(`Dispatching ${unitType} for ${unitId}...`, "info"); const result = await ctx.newSession(); if (result.cancelled) { diff --git a/src/resources/extensions/gsd/auto-dispatch.ts b/src/resources/extensions/gsd/auto-dispatch.ts index 91918938f..1b495c417 100644 --- a/src/resources/extensions/gsd/auto-dispatch.ts +++ b/src/resources/extensions/gsd/auto-dispatch.ts @@ -27,7 +27,9 @@ import { buildMilestoneFileName, buildSliceFileName, } from "./paths.js"; +import { parseRoadmap } from "./parsers-legacy.js"; import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { logWarning, logError } from "./workflow-logger.js"; import { join } from "node:path"; import { hasImplementationArtifacts } from "./auto-recovery.js"; import { @@ -46,6 +48,7 @@ import { buildRewriteDocsPrompt, buildReactiveExecutePrompt, buildGateEvaluatePrompt, + buildParallelResearchSlicesPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js"; @@ -92,14 +95,22 @@ function missingSliceStop(mid: string, phase: string): DispatchAction { /** * Check for milestone slices missing SUMMARY files. * Returns array of missing slice IDs, or empty array if all present or DB unavailable. + * + * Excludes skipped slices (intentionally summary-less) and legacy-complete + * slices whose DB status is authoritative even without on-disk SUMMARY (#3620). */ function findMissingSummaries(basePath: string, mid: string): string[] { if (!isDbAvailable()) return []; - const sliceIds = getMilestoneSlices(mid).map(s => s.id); - return sliceIds.filter(sid => { - const summaryPath = resolveSliceFile(basePath, mid, sid, "SUMMARY"); - return !summaryPath || !existsSync(summaryPath); - }); + const slices = getMilestoneSlices(mid); + // Skipped slices never produce SUMMARYs; legacy-complete slices may lack them + const CLOSED_STATUSES = new Set(["skipped", "complete", "done"]); + return slices + .filter(s => !CLOSED_STATUSES.has(s.status)) + .filter(s => { + const summaryPath = resolveSliceFile(basePath, mid, s.id, "SUMMARY"); + return !summaryPath || !existsSync(summaryPath); + }) + .map(s => s.id); } // ─── Rewrite Circuit Breaker ────────────────────────────────────────────── @@ -129,6 +140,47 @@ export function setRewriteCount(basePath: string, count: number): void { writeFileSync(filePath, JSON.stringify({ count, updatedAt: new Date().toISOString() }) + "\n"); } +// ─── Run-UAT dispatch counter (per-slice) ──────────────────────────────── +// Caps run-uat dispatches to prevent infinite replay when verification +// commands fail before writing a verdict (#3624). +const MAX_UAT_ATTEMPTS = 3; + +function uatCountPath(basePath: string, mid: string, sid: string): string { + return join(gsdRoot(basePath), "runtime", `uat-count-${mid}-${sid}.json`); +} + +export function getUatCount(basePath: string, mid: string, sid: string): number { + try { + const data = JSON.parse(readFileSync(uatCountPath(basePath, mid, sid), "utf-8")); + return typeof data.count === "number" ? data.count : 0; + } catch { + return 0; + } +} + +export function incrementUatCount(basePath: string, mid: string, sid: string): number { + const count = getUatCount(basePath, mid, sid) + 1; + const filePath = uatCountPath(basePath, mid, sid); + mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true }); + writeFileSync(filePath, JSON.stringify({ count, updatedAt: new Date().toISOString() }) + "\n"); + return count; +} + +// ─── Helpers ───────────────────────────────────────────────────────────── + +/** + * Returns true when the verification_operational value indicates that no + * operational verification is needed. Covers common phrasings the planning + * agent may use: "None", "None required", "N/A", "Not applicable", etc. + * + * @see https://github.com/gsd-build/gsd-2/issues/2931 + */ +export function isVerificationNotApplicable(value: string): boolean { + const v = (value ?? "").toLowerCase().trim().replace(/[.\s]+$/, ""); + if (!v || v === "none") return true; + return /^(?:none(?:[\s._\u2014-]+[\s\S]*)?|n\/?a|not[\s._-]+(?:applicable|required|needed|provided)|no[\s._-]+operational[\s\S]*)$/i.test(v); +} + // ─── Rules ──────────────────────────────────────────────────────────────── export const DISPATCH_RULES: DispatchRule[] = [ @@ -187,6 +239,16 @@ export const DISPATCH_RULES: DispatchRule[] = [ const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs); if (!needsRunUat) return null; const { sliceId, uatType } = needsRunUat; + + // Cap run-uat dispatch attempts to prevent infinite replay (#3624) + const attempts = incrementUatCount(basePath, mid, sliceId); + if (attempts > MAX_UAT_ATTEMPTS) { + return { + action: "stop" as const, + reason: `run-uat for ${mid}/${sliceId} has been dispatched ${attempts - 1} times without producing a verdict. Verification commands may be broken — fix the UAT spec or manually write an ASSESSMENT verdict.`, + level: "warning" as const, + }; + } const uatFile = resolveSliceFile(basePath, mid, sliceId, "UAT")!; const uatContent = await loadFile(uatFile); return { @@ -316,6 +378,55 @@ export const DISPATCH_RULES: DispatchRule[] = [ }; }, }, + { + // Keep this rule before the single-slice research rule so the multi-slice + // path wins whenever 2+ slices are ready. + name: "planning (multiple slices need research) → parallel-research-slices", + match: async ({ state, mid, midTitle, basePath, prefs }) => { + if (state.phase !== "planning") return null; + if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research) return null; + + // Load roadmap to find all slices + const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP"); + const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null; + if (!roadmapContent) return null; + const roadmap = parseRoadmap(roadmapContent); + + // Find slices that need research (no RESEARCH file, dependencies done) + const milestoneResearchFile = resolveMilestoneFile(basePath, mid, "RESEARCH"); + const researchReadySlices: Array<{ id: string; title: string }> = []; + + for (const slice of roadmap.slices) { + if (slice.done) continue; + // Skip S01 when milestone research exists + if (milestoneResearchFile && slice.id === "S01") continue; + // Skip if already has research + if (resolveSliceFile(basePath, mid, slice.id, "RESEARCH")) continue; + // Skip if dependencies aren't done (check for SUMMARY files) + const depsComplete = (slice.depends ?? []).every((depId) => + !!resolveSliceFile(basePath, mid, depId, "SUMMARY"), + ); + if (!depsComplete) continue; + + researchReadySlices.push({ id: slice.id, title: slice.title }); + } + + // Only dispatch parallel if 2+ slices are ready + if (researchReadySlices.length < 2) return null; + + return { + action: "dispatch", + unitType: "research-slice", + unitId: `${mid}/parallel-research`, + prompt: await buildParallelResearchSlicesPrompt( + mid, + midTitle, + researchReadySlices, + basePath, + ), + }; + }, + }, { name: "planning (no research, not S01) → research-slice", match: async ({ state, mid, midTitle, basePath, prefs }) => { @@ -511,7 +622,7 @@ export const DISPATCH_RULES: DispatchRule[] = [ }; } catch (err) { // Non-fatal — fall through to sequential execution - process.stderr.write(`gsd-reactive: graph derivation failed: ${(err as Error).message}\n`); + logError("dispatch", "reactive graph derivation failed", { error: (err as Error).message }); return null; } }, @@ -658,13 +769,17 @@ export const DISPATCH_RULES: DispatchRule[] = [ // Safety guard (#1703): verify the milestone produced implementation // artifacts (non-.gsd/ files). A milestone with only plan files and // zero implementation code should not be marked complete. - if (!hasImplementationArtifacts(basePath)) { + const artifactCheck = hasImplementationArtifacts(basePath); + if (artifactCheck === "absent") { return { action: "stop", reason: `Cannot complete milestone ${mid}: no implementation files found outside .gsd/. The milestone has only plan files — actual code changes are required.`, level: "error", }; } + if (artifactCheck === "unknown") { + logWarning("dispatch", `Implementation artifact check inconclusive for ${mid} — proceeding (git context unavailable)`); + } // Verification class compliance: if operational verification was planned, // ensure the validation output documents it before allowing completion. @@ -672,11 +787,15 @@ export const DISPATCH_RULES: DispatchRule[] = [ if (isDbAvailable()) { const milestone = getMilestone(mid); if (milestone?.verification_operational && - milestone.verification_operational.toLowerCase() !== "none") { + !isVerificationNotApplicable(milestone.verification_operational)) { const validationPath = resolveMilestoneFile(basePath, mid, "VALIDATION"); if (validationPath) { const validationContent = await loadFile(validationPath); if (validationContent) { + // Allow completion when validation was intentionally skipped by + // preference/budget profile (#3399, #3344). + const skippedByPreference = /skip(?:ped)?[\s\-]+(?:by|per|due to)\s+(?:preference|budget|profile)/i.test(validationContent); + // Accept either the structured template format (table with MET/N/A/SATISFIED) // or prose evidence patterns the validation agent may emit. const structuredMatch = @@ -684,7 +803,7 @@ export const DISPATCH_RULES: DispatchRule[] = [ (validationContent.includes("MET") || validationContent.includes("N/A") || validationContent.includes("SATISFIED")); const proseMatch = /[Oo]perational[\s\S]{0,500}?(?:✅|pass|verified|confirmed|met|complete|true|yes|addressed|covered|satisfied|partially|n\/a|not[\s-]+applicable)/i.test(validationContent); - const hasOperationalCheck = structuredMatch || proseMatch; + const hasOperationalCheck = skippedByPreference || structuredMatch || proseMatch; if (!hasOperationalCheck) { return { action: "stop" as const, @@ -696,7 +815,9 @@ export const DISPATCH_RULES: DispatchRule[] = [ } } } - } catch { /* fall through — don't block on DB errors */ } + } catch (err) { /* fall through — don't block on DB errors */ + logWarning("dispatch", `verification class check failed: ${err instanceof Error ? err.message : String(err)}`); + } return { action: "dispatch", @@ -738,8 +859,9 @@ export async function resolveDispatch( try { const registry = getRegistry(); return await registry.evaluateDispatch(ctx); - } catch { + } catch (err) { // Registry not initialized — fall back to inline loop + logWarning("dispatch", `registry dispatch failed, falling back to inline rules: ${err instanceof Error ? err.message : String(err)}`); } for (const rule of DISPATCH_RULES) { diff --git a/src/resources/extensions/gsd/auto-model-selection.ts b/src/resources/extensions/gsd/auto-model-selection.ts index c79ab55b2..ce33bda61 100644 --- a/src/resources/extensions/gsd/auto-model-selection.ts +++ b/src/resources/extensions/gsd/auto-model-selection.ts @@ -5,12 +5,13 @@ */ import type { Api, Model } from "@gsd/pi-ai"; +import { getProviderCapabilities } from "@gsd/pi-ai"; import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent"; import type { GSDPreferences } from "./preferences.js"; import { resolveModelWithFallbacksForUnit, resolveDynamicRoutingConfig } from "./preferences.js"; import type { ComplexityTier } from "./complexity-classifier.js"; import { classifyUnitComplexity, tierLabel } from "./complexity-classifier.js"; -import { resolveModelForComplexity, escalateTier } from "./model-router.js"; +import { resolveModelForComplexity, escalateTier, getEligibleModels, loadCapabilityOverrides, adjustToolSet, filterToolsForProvider } from "./model-router.js"; import { getLedger, getProjectTotals } from "./metrics.js"; import { unitPhaseLabel } from "./auto-dashboard.js"; @@ -24,13 +25,23 @@ export interface ModelSelectionResult { export function resolvePreferredModelConfig( unitType: string, autoModeStartModel: { provider: string; id: string } | null, + /** When false, only return explicit per-phase model configs — do not + * synthesize a routing ceiling from dynamic_routing.tier_models (#3962). */ + isAutoMode = true, ) { const explicitConfig = resolveModelWithFallbacksForUnit(unitType); if (explicitConfig) return explicitConfig; + // In interactive mode, don't synthesize a routing-based model config. + // The user's session model (/model) should be used as-is (#3962). + if (!isAutoMode) return undefined; + const routingConfig = resolveDynamicRoutingConfig(); if (!routingConfig.enabled || !routingConfig.tier_models) return undefined; + // Don't synthesize a routing config for flat-rate providers (#3453). + if (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider)) return undefined; + const ceilingModel = routingConfig.tier_models.heavy ?? (autoModeStartModel ? `${autoModeStartModel.provider}/${autoModeStartModel.id}` : undefined); if (!ceilingModel) return undefined; @@ -58,8 +69,11 @@ export async function selectAndApplyModel( verbose: boolean, autoModeStartModel: { provider: string; id: string } | null, retryContext?: { isRetry: boolean; previousTier?: string }, + /** When false (interactive/guided-flow), skip dynamic routing and use the session model. + * Dynamic routing only applies in auto-mode where cost optimization is expected. (#3962) */ + isAutoMode = true, ): Promise { - const modelConfig = resolvePreferredModelConfig(unitType, autoModeStartModel); + const modelConfig = resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode); let routing: { tier: string; modelDowngraded: boolean } | null = null; let appliedModel: Model | null = null; @@ -67,10 +81,37 @@ export async function selectAndApplyModel( const availableModels = ctx.modelRegistry.getAvailable(); // ─── Dynamic Model Routing ───────────────────────────────────────── + // Dynamic routing (complexity-based downgrading) only applies in auto-mode. + // Interactive/guided-flow dispatches use the user's session model directly, + // respecting their /model selection without silent downgrades (#3962). const routingConfig = resolveDynamicRoutingConfig(); + if (!isAutoMode) { + routingConfig.enabled = false; + } let effectiveModelConfig = modelConfig; let routingTierLabel = ""; + // Disable routing for flat-rate providers like GitHub Copilot (#3453). + // All models cost the same per request, so downgrading to a cheaper + // model provides no cost benefit — it only degrades quality. + // Fail-closed: if primary model can't be resolved, fall back to + // provider-level signals rather than allowing unwanted downgrades. + if (routingConfig.enabled) { + const primaryModel = resolveModelId(modelConfig.primary, availableModels, ctx.model?.provider); + if (primaryModel) { + if (isFlatRateProvider(primaryModel.provider)) { + routingConfig.enabled = false; + } + } else if ( + (autoModeStartModel && isFlatRateProvider(autoModeStartModel.provider)) + || (ctx.model?.provider && isFlatRateProvider(ctx.model.provider)) + ) { + // Primary model unresolvable but provider signals indicate flat-rate — + // disable routing to prevent quality degradation. + routingConfig.enabled = false; + } + } + if (routingConfig.enabled) { let budgetPct: number | undefined; if (routingConfig.budget_pressure !== false) { @@ -98,23 +139,90 @@ export async function selectAndApplyModel( const escalated = escalateTier(retryContext.previousTier as ComplexityTier); if (escalated) { classification = { ...classification, tier: escalated, reason: "escalated after failure" }; - if (verbose) { - ctx.ui.notify( - `Tier escalation: ${retryContext.previousTier} → ${escalated} (retry after failure)`, - "info", - ); - } + // Always notify on tier escalation — model changes should be visible (#3962) + ctx.ui.notify( + `Tier escalation: ${retryContext.previousTier} → ${escalated} (retry after failure)`, + "info", + ); } } - const routingResult = resolveModelForComplexity(classification, modelConfig, routingConfig, availableModelIds); + // Load user capability overrides from preferences (D-17: deep-merged with built-in profiles) + const capabilityOverrides = loadCapabilityOverrides(prefs ?? {}); + + // Fire before_model_select hook (ADR-004, D-03) + // Hook can override model selection entirely by returning { modelId } + let hookOverride: string | undefined; + if (routingConfig.hooks !== false) { + const eligible = getEligibleModels( + classification.tier, + availableModelIds, + routingConfig, + ); + const hookResult = await pi.emitBeforeModelSelect({ + unitType, + unitId, + classification: { + tier: classification.tier, + reason: classification.reason, + downgraded: classification.downgraded, + }, + taskMetadata: classification.taskMetadata as Record | undefined, + eligibleModels: eligible, + phaseConfig: modelConfig ? { + primary: modelConfig.primary, + fallbacks: modelConfig.fallbacks ?? [], + } : undefined, + }); + if (hookResult?.modelId) { + hookOverride = hookResult.modelId; + } + } + + let routingResult: ReturnType; + if (hookOverride) { + // Hook override bypasses capability scoring entirely + routingResult = { + modelId: hookOverride, + fallbacks: [ + ...(modelConfig?.fallbacks ?? []).filter(f => f !== hookOverride), + ...(modelConfig?.primary && modelConfig.primary !== hookOverride ? [modelConfig.primary] : []), + ], + tier: classification.tier, + wasDowngraded: hookOverride !== modelConfig?.primary, + reason: `hook override: ${hookOverride}`, + selectionMethod: "tier-only", + }; + } else { + routingResult = resolveModelForComplexity( + classification, + modelConfig, + routingConfig, + availableModelIds, + unitType, + classification.taskMetadata, + capabilityOverrides, + ); + } if (routingResult.wasDowngraded) { effectiveModelConfig = { primary: routingResult.modelId, fallbacks: routingResult.fallbacks, }; - if (verbose) { + // Always notify on model downgrade — users should see when their + // model selection is overridden, not just in verbose mode (#3962). + if (routingResult.selectionMethod === "capability-scored" && routingResult.capabilityScores) { + const tierLbl = tierLabel(classification.tier); + const scores = Object.entries(routingResult.capabilityScores) + .sort(([, a], [, b]) => b - a) + .map(([id, score]) => `${id}: ${score.toFixed(1)}`) + .join(", "); + ctx.ui.notify( + `Dynamic routing [${tierLbl}]: ${routingResult.modelId} (capability-scored) — ${scores}`, + "info", + ); + } else { ctx.ui.notify( `Dynamic routing [${tierLabel(classification.tier)}]: ${routingResult.modelId} (${classification.reason})`, "info", @@ -151,11 +259,46 @@ export async function selectAndApplyModel( const ok = await pi.setModel(model, { persist: false }); if (ok) { appliedModel = model; - const fallbackNote = modelId === effectiveModelConfig.primary - ? "" - : ` (fallback from ${effectiveModelConfig.primary})`; - const phase = unitPhaseLabel(unitType); - ctx.ui.notify(`Model [${phase}]${routingTierLabel}: ${model.provider}/${model.id}${fallbackNote}`, "info"); + + // ADR-005: Adjust active tool set for the selected model's provider capabilities. + // Hard-filter incompatible tools, then let extensions override via adjust_tool_set hook. + const activeToolNames = pi.getActiveTools(); + const { toolNames: compatibleTools, removedTools } = adjustToolSet(activeToolNames, model.api); + let finalToolNames = compatibleTools; + + // Fire adjust_tool_set hook — extensions can override the filtered tool set + if (routingConfig.hooks !== false) { + const hookResult = await pi.emitAdjustToolSet({ + selectedModelApi: model.api, + selectedModelProvider: model.provider, + selectedModelId: model.id, + activeToolNames, + filteredTools: removedTools, + }); + if (hookResult?.toolNames) { + finalToolNames = hookResult.toolNames; + } + } + + // Apply the filtered tool set if any tools were removed + if (removedTools.length > 0 || finalToolNames.length !== activeToolNames.length) { + pi.setActiveTools(finalToolNames); + } + + if (verbose) { + const fallbackNote = modelId === effectiveModelConfig.primary + ? "" + : ` (fallback from ${effectiveModelConfig.primary})`; + const phase = unitPhaseLabel(unitType); + ctx.ui.notify(`Model [${phase}]${routingTierLabel}: ${model.provider}/${model.id}${fallbackNote}`, "info"); + // ADR-005: Report tools filtered due to provider incompatibility + if (removedTools.length > 0) { + ctx.ui.notify( + `Tool compatibility: ${removedTools.length} tools filtered for ${model.api} — ${removedTools.join(", ")}`, + "info", + ); + } + } break; } else { const nextModel = modelsToTry[modelsToTry.indexOf(modelId) + 1]; @@ -222,9 +365,51 @@ export function resolveModelId( ); } - // Bare ID — prefer current provider, then first available - const exactProviderMatch = availableModels.find( - m => m.id === modelId && m.provider === currentProvider, - ); - return exactProviderMatch ?? availableModels.find(m => m.id === modelId); + // Bare ID — resolve with provider precedence to avoid silent misrouting. + // Extension providers (e.g. claude-code) expose the same model IDs as their + // upstream API providers but route through a subprocess with different + // context, tool visibility, and cost characteristics (#2905). Bare IDs in + // PREFERENCES.md must resolve to the canonical API provider, not to an + // extension wrapper that happens to be the current session provider. + const candidates = availableModels.filter(m => m.id === modelId); + if (candidates.length === 0) return undefined; + if (candidates.length === 1) return candidates[0]; + + // When the user's current provider is claude-code (set by startup migration + // or explicit selection), honour it for bare IDs. Routing back to anthropic + // would undo the migration and hit the third-party subscription block (#3772). + if (currentProvider === "claude-code") { + const ccMatch = candidates.find(m => m.provider === "claude-code"); + if (ccMatch) return ccMatch; + } + + // Extension / CLI-wrapper providers that should not win bare-ID resolution + // when a first-class API provider also offers the same model AND the user + // has not explicitly chosen the extension provider. + const EXTENSION_PROVIDERS = new Set(["claude-code"]); + + // Prefer currentProvider only when it is a first-class API provider + if (currentProvider && !EXTENSION_PROVIDERS.has(currentProvider)) { + const providerMatch = candidates.find(m => m.provider === currentProvider); + if (providerMatch) return providerMatch; + } + + // Prefer "anthropic" as the canonical provider for Anthropic models + const anthropicMatch = candidates.find(m => m.provider === "anthropic"); + if (anthropicMatch) return anthropicMatch; + + // Fall back to first non-extension candidate, or any candidate + return candidates.find(m => !EXTENSION_PROVIDERS.has(m.provider)) ?? candidates[0]; +} + +/** + * Flat-rate providers charge the same per request regardless of model. + * Dynamic routing provides no cost benefit — it only degrades quality (#3453). + * Uses case-insensitive matching with alias support to prevent fail-open on + * provider naming variations (e.g. "copilot" vs "github-copilot"). + */ +const FLAT_RATE_PROVIDERS = new Set(["github-copilot", "copilot", "claude-code"]); + +export function isFlatRateProvider(provider: string): boolean { + return FLAT_RATE_PROVIDERS.has(provider.toLowerCase()); } diff --git a/src/resources/extensions/gsd/auto-post-unit.ts b/src/resources/extensions/gsd/auto-post-unit.ts index 3083a20fa..b0bd77dd2 100644 --- a/src/resources/extensions/gsd/auto-post-unit.ts +++ b/src/resources/extensions/gsd/auto-post-unit.ts @@ -13,10 +13,12 @@ import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent"; import { deriveState } from "./state.js"; +import { logWarning, logError } from "./workflow-logger.js"; import { loadFile, parseSummary, resolveAllOverrides } from "./files.js"; import { loadPrompt } from "./prompt-loader.js"; import { resolveSliceFile, + resolveSlicePath, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, @@ -32,10 +34,12 @@ import { import { verifyExpectedArtifact, resolveExpectedArtifactPath, + writeBlockerPlaceholder, + diagnoseExpectedArtifact, } from "./auto-recovery.js"; import { regenerateIfMissing } from "./workflow-projections.js"; import { syncStateToProjectRoot } from "./auto-worktree.js"; -import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter } from "./gsd-db.js"; +import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, updateSliceStatus, _getAdapter } from "./gsd-db.js"; import { renderPlanCheckboxes } from "./markdown-renderer.js"; import { consumeSignal } from "./session-status-io.js"; import { @@ -45,10 +49,25 @@ import { persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js"; -import { hasPendingCaptures, loadPendingCaptures } from "./captures.js"; +import { hasPendingCaptures, loadPendingCaptures, revertExecutorResolvedCaptures } from "./captures.js"; import { debugLog } from "./debug-logger.js"; import { runSafely } from "./auto-utils.js"; import type { AutoSession, SidecarItem } from "./auto/session.js"; +import { getEvidence } from "./safety/evidence-collector.js"; +import { validateFileChanges } from "./safety/file-change-validator.js"; +// crossReferenceEvidence available for future use when verification_evidence is stored in DB +// import { crossReferenceEvidence, type ClaimedEvidence } from "./safety/evidence-cross-ref.js"; +import { validateContent } from "./safety/content-validator.js"; +import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js"; +import { resolveExpectedArtifactPath as resolveArtifactForContent } from "./auto-artifact-paths.js"; +import { loadEffectiveGSDPreferences } from "./preferences.js"; +import { getSliceTasks } from "./gsd-db.js"; +import { runPreExecutionChecks, type PreExecutionResult } from "./pre-execution-checks.js"; +import { writePreExecutionEvidence } from "./verification-evidence.js"; +import { ensureCodebaseMapFresh } from "./codebase-generator.js"; + +/** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */ +const MAX_VERIFICATION_RETRIES = 3; /** Enqueue a sidecar item (hook, triage, or quick-task) for the main loop to @@ -143,7 +162,14 @@ export function detectRogueFileWrites( const dbRow = getSlice(mid, sid); if (!dbRow || dbRow.status !== "complete") { - rogues.push({ path: summaryPath, unitType, unitId }); + // Auto-remediate: SUMMARY exists on disk but DB is stale — sync DB to + // match filesystem instead of reporting as rogue (#3633). + try { + updateSliceStatus(mid, sid, "complete", new Date().toISOString()); + } catch { + // If DB update fails, fall back to rogue detection so the issue is visible + rogues.push({ path: summaryPath, unitType, unitId }); + } } } else if (unitType === "plan-milestone") { if (!mid) return []; @@ -278,8 +304,9 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV try { const { getTaskIssueNumberForCommit } = await import("../github-sync/sync.js"); ghIssueNumber = getTaskIssueNumberForCommit(s.basePath, mid, sid, tid) ?? undefined; - } catch { + } catch (err) { // GitHub sync not available — skip + logWarning("engine", `GitHub issue lookup failed: ${err instanceof Error ? err.message : String(err)}`); } taskContext = { @@ -412,10 +439,10 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV ); } for (const action of triageResult.actions) { - process.stderr.write(`gsd-triage: ${action}\n`); + logWarning("engine", `triage resolution: ${action}`); } } catch (err) { - process.stderr.write(`gsd-triage: resolution execution failed: ${(err as Error).message}\n`); + logError("engine", "triage resolution failed", { error: (err as Error).message }); } } @@ -423,13 +450,94 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV try { const rogueFiles = detectRogueFileWrites(s.currentUnit.type, s.currentUnit.id, s.basePath); for (const rogue of rogueFiles) { - process.stderr.write(`gsd-rogue: detected rogue file write: ${rogue.path} (unit: ${rogue.unitId})\n`); + logWarning("engine", "rogue file write detected", { path: rogue.path, unitId: rogue.unitId }); ctx.ui.notify(`Rogue file write detected: ${rogue.path}`, "warning"); } } catch (e) { debugLog("postUnit", { phase: "rogue-detection", error: String(e) }); } + // ── Safety harness: post-unit validation ── + try { + const { loadEffectiveGSDPreferences } = await import("./preferences.js"); + const prefs = loadEffectiveGSDPreferences()?.preferences; + const safetyConfig = resolveSafetyHarnessConfig( + prefs?.safety_harness as Record | undefined, + ); + + if (safetyConfig.enabled) { + const { milestone: sMid, slice: sSid, task: sTid } = parseUnitId(s.currentUnit.id); + + // File change validation (execute-task only, after auto-commit) + if (safetyConfig.file_change_validation && s.currentUnit.type === "execute-task" && sMid && sSid && sTid && isDbAvailable()) { + try { + const taskRow = getTask(sMid, sSid, sTid); + if (taskRow) { + const expectedOutput = taskRow.expected_output ?? []; + const plannedFiles = taskRow.files ?? []; + const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles); + if (audit && audit.violations.length > 0) { + const warnings = audit.violations.filter(v => v.severity === "warning"); + for (const v of warnings) { + logWarning("safety", `file-change: ${v.file} — ${v.reason}`); + } + if (warnings.length > 0) { + ctx.ui.notify( + `Safety: ${warnings.length} unexpected file change(s) outside task plan`, + "warning", + ); + } + } + } + } catch (e) { + debugLog("postUnit", { phase: "safety-file-change", error: String(e) }); + } + } + + // Evidence cross-reference (execute-task only) + // Verification evidence is passed via the complete-task tool call and + // stored in the SUMMARY.md on disk — not available as structured data + // in the DB. The evidence collector tracks actual bash tool calls, so + // we can still detect units that claimed success but ran no commands. + if (safetyConfig.evidence_cross_reference && s.currentUnit.type === "execute-task") { + try { + const actual = getEvidence(); + const bashCalls = actual.filter(e => e.kind === "bash"); + // If the task is marked complete but zero bash commands were run, + // it's suspicious — the LLM may have fabricated results. + if (sMid && sSid && sTid && isDbAvailable()) { + const taskRow = getTask(sMid, sSid, sTid); + if (taskRow?.status === "complete" && taskRow.verify && bashCalls.length === 0) { + logWarning("safety", "task marked complete with verification commands but no bash calls were executed"); + ctx.ui.notify( + `Safety: task ${sTid} has verification commands but no bash calls were recorded`, + "warning", + ); + } + } + } catch (e) { + debugLog("postUnit", { phase: "safety-evidence-xref", error: String(e) }); + } + } + + // Content validation (plan-slice, plan-milestone) + if (safetyConfig.content_validation) { + try { + const artifactPath = resolveArtifactForContent(s.currentUnit.type, s.currentUnit.id, s.basePath); + const contentViolations = validateContent(s.currentUnit.type, artifactPath); + for (const v of contentViolations) { + logWarning("safety", `content: ${v.reason}`); + ctx.ui.notify(`Content validation: ${v.reason}`, "warning"); + } + } catch (e) { + debugLog("postUnit", { phase: "safety-content-validation", error: String(e) }); + } + } + } + } catch (e) { + debugLog("postUnit", { phase: "safety-harness", error: String(e) }); + } + // Artifact verification let triggerArtifactVerified = false; if (!s.currentUnit.type.startsWith("hook/")) { @@ -465,23 +573,78 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV // When artifact verification fails for a unit type that has a known expected // artifact, return "retry" so the caller re-dispatches with failure context // instead of blindly re-dispatching the same unit (#1571). - if (!triggerArtifactVerified) { + // After MAX_VERIFICATION_RETRIES, escalate to writeBlockerPlaceholder so the + // pipeline can advance instead of looping forever (#2653). + // + // HOWEVER, if the DB is unavailable (db_unavailable), the artifact was never + // written because the completion tool failed at the infra level. Retrying + // can never succeed and produces a costly re-dispatch loop (#2517). + if (!triggerArtifactVerified && !isDbAvailable()) { + // DB infra failure — do NOT retry; the completion tool returned + // db_unavailable so the artifact was never written. Retrying would + // produce an infinite re-dispatch loop (#2517). + debugLog("postUnit", { phase: "artifact-verify-skip-db-unavailable", unitType: s.currentUnit.type, unitId: s.currentUnit.id }); + const dbSkipDiag = diagnoseExpectedArtifact(s.currentUnit.type, s.currentUnit.id, s.basePath); + ctx.ui.notify( + `Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — DB unavailable, skipping retry.${dbSkipDiag ? ` Expected: ${dbSkipDiag}` : ""}`, + "error", + ); + } else if (!triggerArtifactVerified) { + // #2883/#3595: If the artifact is missing because the tool invocation + // failed (malformed JSON) or was skipped (queued user message), retrying + // will produce the same failure. Pause auto-mode instead of looping. + if (s.lastToolInvocationError) { + const isUserSkip = /queued user message/i.test(s.lastToolInvocationError); + const errMsg = isUserSkip + ? `Tool skipped for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Queued user message interrupted the turn — pausing auto-mode.` + : `Tool invocation failed for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Structured argument generation failed — pausing auto-mode.`; + debugLog("postUnit", { phase: "tool-invocation-error-pause", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError }); + ctx.ui.notify(errMsg, "error"); + s.lastToolInvocationError = null; + await pauseAuto(ctx, pi); + return "dispatched"; + } + const hasExpectedArtifact = resolveExpectedArtifactPath(s.currentUnit.type, s.currentUnit.id, s.basePath) !== null; if (hasExpectedArtifact) { const retryKey = `${s.currentUnit.type}:${s.currentUnit.id}`; const attempt = (s.verificationRetryCount.get(retryKey) ?? 0) + 1; s.verificationRetryCount.set(retryKey, attempt); - s.pendingVerificationRetry = { - unitId: s.currentUnit.id, - failureContext: `Artifact verification failed: expected artifact for ${s.currentUnit.type} "${s.currentUnit.id}" was not found on disk after unit execution (attempt ${attempt}).`, - attempt, - }; - debugLog("postUnit", { phase: "artifact-verify-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt }); - ctx.ui.notify( - `Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — retrying (attempt ${attempt})`, - "warning", - ); - return "retry"; + + if (attempt > MAX_VERIFICATION_RETRIES) { + // Retries exhausted — write a blocker placeholder so the pipeline + // can advance past this stuck unit (#2653). + debugLog("postUnit", { + phase: "artifact-verify-escalate", + unitType: s.currentUnit.type, + unitId: s.currentUnit.id, + attempt, + maxRetries: MAX_VERIFICATION_RETRIES, + }); + const reason = `Artifact verification failed after ${MAX_VERIFICATION_RETRIES} retries for ${s.currentUnit.type} "${s.currentUnit.id}".`; + writeBlockerPlaceholder(s.currentUnit.type, s.currentUnit.id, s.basePath, reason); + ctx.ui.notify( + `${s.currentUnit.type} ${s.currentUnit.id} — verification retries exhausted (${MAX_VERIFICATION_RETRIES}), wrote blocker placeholder to advance pipeline`, + "warning", + ); + // Reset retry count and fall through to "continue" so the loop + // re-derives state with the placeholder in place. + s.verificationRetryCount.delete(retryKey); + s.pendingVerificationRetry = null; + // Do NOT return "retry" — fall through to "continue" below. + } else { + s.pendingVerificationRetry = { + unitId: s.currentUnit.id, + failureContext: `Artifact verification failed: expected artifact for ${s.currentUnit.type} "${s.currentUnit.id}" was not found on disk after unit execution (attempt ${attempt}).`, + attempt, + }; + debugLog("postUnit", { phase: "artifact-verify-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt }); + ctx.ui.notify( + `Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — retrying (attempt ${attempt})`, + "warning", + ); + return "retry"; + } } } } else { @@ -507,6 +670,35 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"continue" | "step-wizard" | "stopped"> { const { s, ctx, pi, buildSnapshotOpts, lockBase, stopAuto, pauseAuto, updateProgressWidget } = pctx; + if (s.currentUnit) { + try { + const codebasePrefs = loadEffectiveGSDPreferences()?.preferences?.codebase; + const refresh = ensureCodebaseMapFresh( + s.basePath, + codebasePrefs + ? { + excludePatterns: codebasePrefs.exclude_patterns, + maxFiles: codebasePrefs.max_files, + collapseThreshold: codebasePrefs.collapse_threshold, + } + : undefined, + { force: true, ttlMs: 0 }, + ); + if (refresh.status === "generated" || refresh.status === "updated") { + debugLog("postUnit", { + phase: "codebase-refresh", + unitType: s.currentUnit.type, + unitId: s.currentUnit.id, + status: refresh.status, + fileCount: refresh.fileCount, + reason: refresh.reason, + }); + } + } catch (e) { + logWarning("engine", `CODEBASE refresh failed: ${(e as Error).message}`); + } + } + // ── Post-unit hooks ── if (s.currentUnit && !s.stepMode) { const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath); @@ -544,9 +736,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<" } catch (dbErr) { // DB unavailable — fail explicitly rather than silently reverting to markdown mutation. // Use 'gsd recover' to rebuild DB state from disk if needed. - process.stderr.write( - `gsd: retry state-reset failed (DB unavailable): ${(dbErr as Error).message}. Run 'gsd recover' to reconcile.\n`, - ); + logError("engine", `retry state-reset failed (DB unavailable): ${(dbErr as Error).message}. Run 'gsd recover' to reconcile.`); } } @@ -580,6 +770,170 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<" } } + // ── Fast-path stop detection (#3487) ── + // Before waiting for triage, check if any PENDING captures contain explicit + // stop/halt language. If so, pause immediately — don't wait for triage. + if (s.currentUnit && s.currentUnit.type !== "triage-captures") { + try { + const pending = loadPendingCaptures(s.basePath); + // Match only when the capture text starts with a stop/halt directive word, + // or the entire text is short and dominated by such a word. This avoids + // false positives on captures like "add a pause button" or "stop the timer + // from re-rendering" — those are feature descriptions, not halt directives. + const STOP_PATTERN = /^(stop|halt|abort|don'?t continue|pause|cease)\b/i; + const stopCapture = pending.find(c => STOP_PATTERN.test(c.text.trim())); + if (stopCapture) { + ctx.ui.notify( + `Stop directive detected in pending capture ${stopCapture.id}: "${stopCapture.text}" — pausing auto-mode.`, + "warning", + ); + debugLog("postUnit", { phase: "fast-stop", captureId: stopCapture.id }); + await pauseAuto(ctx, pi); + return "stopped"; + } + } catch (e) { + debugLog("postUnit", { phase: "fast-stop-error", error: String(e) }); + } + } + + // ── Capture protection: revert executor-silenced captures (#3487) ── + // Non-triage agents can write **Status:** resolved to CAPTURES.md, bypassing + // the triage pipeline. Revert those to pending before the triage check. + if ( + s.currentUnit && + s.currentUnit.type !== "triage-captures" + ) { + try { + const reverted = revertExecutorResolvedCaptures(s.basePath); + if (reverted > 0) { + debugLog("postUnit", { phase: "capture-protection", reverted }); + ctx.ui.notify( + `Reverted ${reverted} capture${reverted === 1 ? "" : "s"} silenced by executor — re-queuing for triage.`, + "warning", + ); + } + } catch (e) { + debugLog("postUnit", { phase: "capture-protection-error", error: String(e) }); + } + } + + // ── Pre-execution checks (after plan-slice completes) ── + if ( + s.currentUnit && + s.currentUnit.type === "plan-slice" + ) { + let preExecPauseNeeded = false; + await runSafely("postUnitPostVerification", "pre-execution-checks", async () => { + try { + // Check preferences — respect enhanced_verification and enhanced_verification_pre + const prefs = loadEffectiveGSDPreferences()?.preferences; + const enhancedEnabled = prefs?.enhanced_verification !== false; // default true + const preEnabled = prefs?.enhanced_verification_pre !== false; // default true + + if (!enhancedEnabled || !preEnabled) { + debugLog("postUnitPostVerification", { + phase: "pre-execution-checks", + skipped: true, + reason: "disabled by preferences", + }); + return; + } + + // Parse the unit ID to get milestone/slice IDs + const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit!.id); + if (!mid || !sid) { + debugLog("postUnitPostVerification", { + phase: "pre-execution-checks", + skipped: true, + reason: "could not parse milestone/slice from unit ID", + }); + return; + } + + // Get tasks for this slice from DB + const tasks = getSliceTasks(mid, sid); + if (tasks.length === 0) { + debugLog("postUnitPostVerification", { + phase: "pre-execution-checks", + skipped: true, + reason: "no tasks found for slice", + }); + return; + } + + // Run pre-execution checks + const result: PreExecutionResult = await runPreExecutionChecks(tasks, s.basePath); + + // Log summary to stderr in existing verification output format + const emoji = result.status === "pass" ? "✅" : result.status === "warn" ? "⚠️" : "❌"; + process.stderr.write( + `gsd-pre-exec: ${emoji} Pre-execution checks ${result.status} for ${mid}/${sid} (${result.durationMs}ms)\n`, + ); + + // Log individual check results + for (const check of result.checks) { + const checkEmoji = check.passed ? "✓" : check.blocking ? "✗" : "⚠"; + process.stderr.write( + `gsd-pre-exec: ${checkEmoji} [${check.category}] ${check.target}: ${check.message}\n`, + ); + } + + // Write evidence JSON to slice artifacts directory + const slicePath = resolveSlicePath(s.basePath, mid, sid); + if (slicePath) { + writePreExecutionEvidence(result, slicePath, mid, sid); + } + + // Notify UI + if (result.status === "fail") { + const blockingCount = result.checks.filter(c => !c.passed && c.blocking).length; + ctx.ui.notify( + `Pre-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`, + "error", + ); + preExecPauseNeeded = true; + } else if (result.status === "warn") { + ctx.ui.notify( + `Pre-execution checks passed with warnings`, + "warning", + ); + // Strict mode: treat warnings as blocking + if (prefs?.enhanced_verification_strict === true) { + preExecPauseNeeded = true; + } + } + + debugLog("postUnitPostVerification", { + phase: "pre-execution-checks", + status: result.status, + checkCount: result.checks.length, + durationMs: result.durationMs, + }); + } catch (preExecError) { + // Fail-closed: if runPreExecutionChecks throws, pause auto-mode instead of silently continuing + const errorMessage = preExecError instanceof Error ? preExecError.message : String(preExecError); + debugLog("postUnitPostVerification", { + phase: "pre-execution-checks", + error: errorMessage, + failClosed: true, + }); + logError("engine", `gsd-pre-exec: Pre-execution checks threw an error: ${errorMessage}`); + ctx.ui.notify( + `Pre-execution checks error: ${errorMessage} — pausing for human review`, + "error", + ); + preExecPauseNeeded = true; + } + }); + + // Check for blocking failures after runSafely completes + if (preExecPauseNeeded) { + debugLog("postUnitPostVerification", { phase: "pre-execution-checks", pausing: true, reason: "blocking failures detected" }); + await pauseAuto(ctx, pi); + return "stopped"; + } + } + // ── Triage check ── if ( !s.stepMode && diff --git a/src/resources/extensions/gsd/auto-prompts.ts b/src/resources/extensions/gsd/auto-prompts.ts index 1ea0e3366..1c6f622f3 100644 --- a/src/resources/extensions/gsd/auto-prompts.ts +++ b/src/resources/extensions/gsd/auto-prompts.ts @@ -26,6 +26,8 @@ import { existsSync } from "node:fs"; import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary } from "./context-budget.js"; import { getPendingGates } from "./gsd-db.js"; import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js"; +import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js"; +import { logWarning } from "./workflow-logger.js"; // ─── Preamble Cap ───────────────────────────────────────────────────────────── @@ -48,7 +50,8 @@ function formatExecutorConstraints(): string { try { const prefs = loadEffectiveGSDPreferences(); windowTokens = resolveExecutorContextWindow(undefined, prefs?.preferences); - } catch { + } catch (e) { + logWarning("prompt", `resolveExecutorContextWindow failed: ${(e as Error).message}`); windowTokens = 200_000; // safe default } const budgets = computeBudgets(windowTokens); @@ -197,7 +200,9 @@ export async function inlineDependencySummaries( } // If slice not found in DB, fall through to file-based parsing } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `inlineDependencySummaries DB lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } // If DB didn't provide depends, fall back to roadmap parsing if (!depends) { @@ -256,7 +261,12 @@ export async function inlineGsdRootFile( /** * Inline decisions with optional milestone scoping from the DB. - * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty. + * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable. + * + * Cascade logic (R005): + * 1. Query with { milestoneId, scope } if scope provided + * 2. If empty AND scope was provided, retry with { milestoneId } only (drop scope) + * 3. If still empty, return null (intentional per D020) */ export async function inlineDecisionsFromDb( base: string, milestoneId?: string, scope?: string, level?: InlineLevel, @@ -266,7 +276,15 @@ export async function inlineDecisionsFromDb( const { isDbAvailable } = await import("./gsd-db.js"); if (isDbAvailable()) { const { queryDecisions, formatDecisionsForPrompt } = await import("./context-store.js"); - const decisions = queryDecisions({ milestoneId, scope }); + + // First query: try with both milestoneId and scope (if scope provided) + let decisions = queryDecisions({ milestoneId, scope }); + + // Cascade: if empty AND scope was provided, retry without scope + if (decisions.length === 0 && scope) { + decisions = queryDecisions({ milestoneId }); + } + if (decisions.length > 0) { // Use compact format for non-full levels to save ~35% tokens const formatted = inlineLevel !== "full" @@ -274,26 +292,29 @@ export async function inlineDecisionsFromDb( : formatDecisionsForPrompt(decisions); return `### Decisions\nSource: \`.gsd/DECISIONS.md\`\n\n${formatted}`; } + // DB available but cascade returned empty — intentional per D020, don't fall back to file + return null; } - } catch { - // DB not available — fall through to filesystem + } catch (err) { + logWarning("prompt", `inlineDecisionsFromDb failed: ${err instanceof Error ? err.message : String(err)}`); } + // DB unavailable — fall back to filesystem return inlineGsdRootFile(base, "decisions.md", "Decisions"); } /** - * Inline requirements with optional slice scoping from the DB. + * Inline requirements with optional milestone and slice scoping from the DB. * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty. */ export async function inlineRequirementsFromDb( - base: string, sliceId?: string, level?: InlineLevel, + base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel, ): Promise { const inlineLevel = level ?? resolveInlineLevel(); try { const { isDbAvailable } = await import("./gsd-db.js"); if (isDbAvailable()) { const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js"); - const requirements = queryRequirements({ sliceId }); + const requirements = queryRequirements({ milestoneId, sliceId }); if (requirements.length > 0) { // Use compact format for non-full levels to save ~40% tokens const formatted = inlineLevel !== "full" @@ -302,8 +323,8 @@ export async function inlineRequirementsFromDb( return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`; } } - } catch { - // DB not available — fall through to filesystem + } catch (err) { + logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`); } return inlineGsdRootFile(base, "requirements.md", "Requirements"); } @@ -324,12 +345,137 @@ export async function inlineProjectFromDb( return `### Project\nSource: \`.gsd/PROJECT.md\`\n\n${content}`; } } - } catch { - // DB not available — fall through to filesystem + } catch (err) { + logWarning("prompt", `inlineProjectFromDb failed: ${err instanceof Error ? err.message : String(err)}`); } return inlineGsdRootFile(base, "project.md", "Project"); } +// ─── Stopwords for keyword extraction ───────────────────────────────────── +const STOPWORDS = new Set(['of', 'the', 'and', 'a', 'for', '+', '-', 'to', 'in', 'on', 'with', 'is', 'as', 'by']); + +// Generic words that don't provide meaningful scope differentiation +const GENERIC_WORDS = new Set([ + 'setup', 'integration', 'implementation', 'testing', 'test', 'tests', + 'config', 'configuration', 'init', 'initial', 'basic', 'core', + 'main', 'primary', 'final', 'complete', 'finish', 'end', + 'start', 'begin', 'first', 'last', 'update', 'updates', + 'fix', 'fixes', 'add', 'adds', 'remove', 'removes', + 'create', 'creates', 'build', 'builds', 'deploy', 'deployment', + 'refactor', 'refactoring', 'cleanup', 'polish', 'review', + // Process/activity words that describe what you're doing, not what domain + 'hardening', 'validation', 'verification', 'optimization', + 'improvement', 'enhancement', 'infrastructure', +]); + +// Pattern to match slice/milestone/task IDs (e.g., S01, M001, T03) +const UNIT_ID_PATTERN = /^[smt]\d+$/i; + +/** + * Derive a scope keyword from slice title and optional description. + * Returns the most specific noun (first non-generic keyword) for decision scoping. + * + * Examples: + * - "Auth Middleware & Protected Route" → "auth" + * - "Database & User Model Setup" → "database" + * - "Integration Testing" → undefined (too generic) + * - "API Rate Limiting" → "api" + * + * @param sliceTitle - The slice title + * @param sliceDescription - Optional roadmap description (demo text) + * @returns A single lowercase keyword or undefined if no meaningful scope + */ +export function deriveSliceScope(sliceTitle: string, sliceDescription?: string): string | undefined { + // Combine title and description for keyword extraction + const combinedText = sliceDescription + ? `${sliceTitle} ${sliceDescription}` + : sliceTitle; + + // Extract all words, lowercase, remove punctuation + const words = combinedText + .split(/[\s&+,;:|/\\()-]+/) + .map(w => w.toLowerCase().replace(/[^a-z0-9]/g, '')) + .filter(w => w.length >= 2); + + // Find the first word that is: + // 1. Not a stopword + // 2. Not a generic word + // 3. Not a unit ID (S01, M001, T03) + // 4. At least 3 characters (meaningful scope) + for (const word of words) { + if (STOPWORDS.has(word)) continue; + if (GENERIC_WORDS.has(word)) continue; + if (UNIT_ID_PATTERN.test(word)) continue; + if (word.length < 3) continue; + return word; + } + + return undefined; +} +/** + * Extract keywords from a slice title for scoped knowledge queries. + * Splits on whitespace, filters stopwords, lowercases. + * Example: 'KNOWLEDGE scoping + roadmap excerpt' → ['knowledge', 'scoping', 'roadmap', 'excerpt'] + */ +function extractKeywords(title: string): string[] { + return title + .split(/\s+/) + .map(w => w.toLowerCase().replace(/[^a-z0-9]/g, '')) + .filter(w => w.length > 0 && !STOPWORDS.has(w)); +} + +/** + * Inline scoped KNOWLEDGE.md content based on keywords from slice title. + * Reads KNOWLEDGE.md, filters to sections matching keywords, formats with header. + * Returns null if no KNOWLEDGE.md exists or no sections match. + */ +export async function inlineKnowledgeScoped( + base: string, + keywords: string[], +): Promise { + const knowledgePath = resolveGsdRootFile(base, "KNOWLEDGE"); + if (!existsSync(knowledgePath)) return null; + + const content = await loadFile(knowledgePath); + if (!content) return null; + + // Import queryKnowledge from context-store + const { queryKnowledge } = await import("./context-store.js"); + const scoped = await queryKnowledge(content, keywords); + + // Return null if no sections matched (empty string from queryKnowledge) + if (!scoped) return null; + + return `### Project Knowledge (scoped)\nSource: \`${relGsdRootFile("KNOWLEDGE")}\`\n\n${scoped.trim()}`; +} + +/** + * Inline a roadmap excerpt for a specific slice. + * Reads full roadmap, extracts minimal excerpt with header + predecessor + target row. + * Returns null if roadmap doesn't exist or slice not found. + */ +export async function inlineRoadmapExcerpt( + base: string, + mid: string, + sid: string, +): Promise { + const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP"); + if (!roadmapPath || !existsSync(roadmapPath)) return null; + + const roadmapRel = relMilestoneFile(base, mid, "ROADMAP"); + const content = await loadFile(roadmapPath); + if (!content) return null; + + // Import formatRoadmapExcerpt from context-store + const { formatRoadmapExcerpt } = await import("./context-store.js"); + const excerpt = formatRoadmapExcerpt(content, sid, roadmapRel); + + // Return null if slice not found in roadmap + if (!excerpt) return null; + + return `### Milestone Roadmap (excerpt)\nSource: \`${roadmapRel}\`\n\n${excerpt}`; +} + // ─── Skill Activation & Discovery ───────────────────────────────────────── function normalizeSkillReference(ref: string): string { @@ -485,8 +631,8 @@ export function buildSkillActivationBlock(params: { for (const skillName of taskPlan.frontmatter.skills_used) { matched.add(normalizeSkillReference(skillName)); } - } catch { - // Non-fatal — malformed task plan should not break prompt construction + } catch (err) { + logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -735,7 +881,9 @@ export async function checkNeedsReassessment( return { sliceId: lastCompleted }; } } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `checkNeedsReassessment DB lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } // File-based fallback using roadmap checkboxes const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP"); @@ -801,7 +949,9 @@ export async function checkNeedsRunUat( return { sliceId: sid, uatType }; } } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `checkNeedsRunUat DB lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } // File-based fallback using roadmap checkboxes if (!prefs?.uat_dispatch) return null; @@ -847,8 +997,9 @@ export async function buildDiscussMilestonePrompt(mid: string, midTitle: string, milestoneId: mid, milestoneTitle: midTitle, inlinedTemplates: discussTemplates, - structuredQuestionsAvailable: "true", + structuredQuestionsAvailable: "false", commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.", + fastPathInstruction: "", }); // If a CONTEXT-DRAFT.md exists, append it as seed material @@ -870,7 +1021,7 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string inlined.push(await inlineFile(contextPath, contextRel, "Milestone Context")); const projectInline = await inlineProjectFromDb(base); if (projectInline) inlined.push(projectInline); - const requirementsInline = await inlineRequirementsFromDb(base); + const requirementsInline = await inlineRequirementsFromDb(base, mid); if (requirementsInline) inlined.push(requirementsInline); const decisionsInline = await inlineDecisionsFromDb(base, mid); if (decisionsInline) inlined.push(decisionsInline); @@ -906,6 +1057,11 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba const researchRel = relMilestoneFile(base, mid, "RESEARCH"); const inlined: string[] = []; + + // Inject phase handoff anchor from research phase (if available) + const researchAnchor = readPhaseAnchor(base, mid, "research-milestone"); + if (researchAnchor) inlined.push(formatAnchorForPrompt(researchAnchor)); + inlined.push(await inlineFile(contextPath, contextRel, "Milestone Context")); const researchInline = await inlineFileOptional(researchPath, researchRel, "Milestone Research"); if (researchInline) inlined.push(researchInline); @@ -915,7 +1071,7 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba if (inlineLevel !== "minimal") { const projectInline = await inlineProjectFromDb(base); if (projectInline) inlined.push(projectInline); - const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel); if (decisionsInline) inlined.push(decisionsInline); @@ -980,18 +1136,39 @@ export async function buildResearchSlicePrompt( const milestoneResearchPath = resolveMilestoneFile(base, mid, "RESEARCH"); const milestoneResearchRel = relMilestoneFile(base, mid, "RESEARCH"); + const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT"); + const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT"); + const inlined: string[] = []; - inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + + // Use roadmap excerpt instead of full roadmap for context reduction + const roadmapExcerptRS = await inlineRoadmapExcerpt(base, mid, sid); + if (roadmapExcerptRS) { + inlined.push(roadmapExcerptRS); + } else { + // Fall back to full roadmap if excerpt fails + inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + } + const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context"); if (contextInline) inlined.push(contextInline); + const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)"); + if (sliceCtxInline) inlined.push(sliceCtxInline); const researchInline = await inlineFileOptional(milestoneResearchPath, milestoneResearchRel, "Milestone Research"); if (researchInline) inlined.push(researchInline); - const decisionsInline = await inlineDecisionsFromDb(base, mid); + + // Derive scope from slice title for decision filtering (R005) + const derivedScope = deriveSliceScope(sTitle); + const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScope); if (decisionsInline) inlined.push(decisionsInline); - const requirementsInline = await inlineRequirementsFromDb(base, sid); + const requirementsInline = await inlineRequirementsFromDb(base, mid, sid); if (requirementsInline) inlined.push(requirementsInline); - const knowledgeInlineRS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge"); + + // Use scoped knowledge based on slice title keywords + const keywords = extractKeywords(sTitle); + const knowledgeInlineRS = await inlineKnowledgeScoped(base, keywords); if (knowledgeInlineRS) inlined.push(knowledgeInlineRS); + inlined.push(inlineTemplate("research", "Research")); const depContent = await inlineDependencySummaries(mid, sid, base); @@ -1031,19 +1208,42 @@ export async function buildPlanSlicePrompt( const roadmapRel = relMilestoneFile(base, mid, "ROADMAP"); const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH"); const researchRel = relSliceFile(base, mid, sid, "RESEARCH"); + const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT"); + const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT"); const inlined: string[] = []; - inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + + // Inject phase handoff anchor from research phase (if available) + const researchSliceAnchor = readPhaseAnchor(base, mid, "research-slice"); + if (researchSliceAnchor) inlined.push(formatAnchorForPrompt(researchSliceAnchor)); + + // Use roadmap excerpt instead of full roadmap for context reduction + const roadmapExcerptPS = await inlineRoadmapExcerpt(base, mid, sid); + if (roadmapExcerptPS) { + inlined.push(roadmapExcerptPS); + } else { + // Fall back to full roadmap if excerpt fails + inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + } + + const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)"); + if (sliceCtxInline) inlined.push(sliceCtxInline); const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research"); if (researchInline) inlined.push(researchInline); if (inlineLevel !== "minimal") { - const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel); + // Derive scope from slice title for decision filtering (R005) + const derivedScopePS = deriveSliceScope(sTitle); + const decisionsInline = await inlineDecisionsFromDb(base, mid, derivedScopePS, inlineLevel); if (decisionsInline) inlined.push(decisionsInline); - const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); } - const knowledgeInlinePS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge"); + + // Use scoped knowledge based on slice title keywords + const keywordsPS = extractKeywords(sTitle); + const knowledgeInlinePS = await inlineKnowledgeScoped(base, keywordsPS); if (knowledgeInlinePS) inlined.push(knowledgeInlinePS); + inlined.push(inlineTemplate("plan", "Slice Plan")); if (inlineLevel === "full") { inlined.push(inlineTemplate("task-plan", "Task Plan")); @@ -1100,6 +1300,9 @@ export async function buildExecuteTaskPrompt( : { level: level as InlineLevel | undefined }; const inlineLevel = opts.level ?? resolveInlineLevel(); + // Inject phase handoff anchor from planning phase (if available) + const planAnchor = readPhaseAnchor(base, mid, "plan-slice"); + const priorSummaries = opts.carryForwardPaths ?? await getPriorTaskSummaryPaths(mid, sid, tid, base); const priorLines = priorSummaries.length > 0 ? priorSummaries.map(p => `- \`${p}\``).join("\n") @@ -1190,9 +1393,12 @@ export async function buildExecuteTaskPrompt( ? `### Runtime Context\nSource: \`.gsd/RUNTIME.md\`\n\n${runtimeContent.trim()}` : ""; + const phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : ""; + return loadPrompt("execute-task", { overridesSection, runtimeContext, + phaseAnchorSection, workingDirectory: base, milestoneId: mid, sliceId: sid, sliceTitle: sTitle, taskId: tid, taskTitle: tTitle, planPath: join(base, relSliceFile(base, mid, sid, "PLAN")), @@ -1228,12 +1434,16 @@ export async function buildCompleteSlicePrompt( const roadmapRel = relMilestoneFile(base, mid, "ROADMAP"); const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN"); const slicePlanRel = relSliceFile(base, mid, sid, "PLAN"); + const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT"); + const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT"); const inlined: string[] = []; inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)"); + if (sliceCtxInline) inlined.push(sliceCtxInline); inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Slice Plan")); if (inlineLevel !== "minimal") { - const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, sid, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); } const knowledgeInlineCS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge"); @@ -1293,9 +1503,13 @@ export async function buildCompleteMilestonePrompt( try { const { isDbAvailable, getMilestoneSlices } = await import("./gsd-db.js"); if (isDbAvailable()) { - sliceIds = getMilestoneSlices(mid).map(s => s.id); + sliceIds = getMilestoneSlices(mid) + .filter(s => s.status !== "skipped") + .map(s => s.id); } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `buildCompleteMilestonePrompt DB lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } // File-based fallback: parse roadmap for slice IDs when DB has no data if (sliceIds.length === 0 && roadmapPath) { const roadmapContent = await loadFile(roadmapPath); @@ -1314,7 +1528,7 @@ export async function buildCompleteMilestonePrompt( // Inline root GSD files (skip for minimal — completion can read these if needed) if (inlineLevel !== "minimal") { - const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel); if (decisionsInline) inlined.push(decisionsInline); @@ -1376,16 +1590,22 @@ export async function buildValidateMilestonePrompt( } } } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `buildValidateMilestonePrompt verification classes lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } - // Inline all slice summaries and UAT results + // Inline all slice summaries and assessment results let valSliceIds: string[] = []; try { const { isDbAvailable, getMilestoneSlices } = await import("./gsd-db.js"); if (isDbAvailable()) { - valSliceIds = getMilestoneSlices(mid).map(s => s.id); + valSliceIds = getMilestoneSlices(mid) + .filter(s => s.status !== "skipped") + .map(s => s.id); } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `buildValidateMilestonePrompt slice IDs lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } // File-based fallback: parse roadmap for slice IDs when DB has no data if (valSliceIds.length === 0 && roadmapPath) { const roadmapContent = await loadFile(roadmapPath); @@ -1401,10 +1621,10 @@ export async function buildValidateMilestonePrompt( const summaryRel = relSliceFile(base, mid, sid, "SUMMARY"); inlined.push(await inlineFile(summaryPath, summaryRel, `${sid} Summary`)); - const uatPath = resolveSliceFile(base, mid, sid, "UAT"); - const uatRel = relSliceFile(base, mid, sid, "UAT"); - const uatInline = await inlineFileOptional(uatPath, uatRel, `${sid} UAT Result`); - if (uatInline) inlined.push(uatInline); + const assessmentPath = resolveSliceFile(base, mid, sid, "ASSESSMENT"); + const assessmentRel = relSliceFile(base, mid, sid, "ASSESSMENT"); + const assessmentInline = await inlineFileOptional(assessmentPath, assessmentRel, `${sid} Assessment`); + if (assessmentInline) inlined.push(assessmentInline); } // Aggregate unresolved follow-ups and known limitations across slices @@ -1435,7 +1655,7 @@ export async function buildValidateMilestonePrompt( // Inline root GSD files if (inlineLevel !== "minimal") { - const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel); if (decisionsInline) inlined.push(decisionsInline); @@ -1479,9 +1699,13 @@ export async function buildReplanSlicePrompt( const roadmapRel = relMilestoneFile(base, mid, "ROADMAP"); const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN"); const slicePlanRel = relSliceFile(base, mid, sid, "PLAN"); + const sliceContextPath = resolveSliceFile(base, mid, sid, "CONTEXT"); + const sliceContextRel = relSliceFile(base, mid, sid, "CONTEXT"); const inlined: string[] = []; inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap")); + const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)"); + if (sliceCtxInline) inlined.push(sliceCtxInline); inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Current Slice Plan")); // Find the blocker task summary — the completed task with blocker_discovered: true @@ -1524,8 +1748,8 @@ export async function buildReplanSlicePrompt( `- **${c.id}**: "${c.text}" — ${c.rationale ?? "no rationale"}` ).join("\n"); } - } catch { - // Non-fatal — captures module may not be available + } catch (err) { + logWarning("prompt", `loadReplanCaptures failed: ${err instanceof Error ? err.message : String(err)}`); } return loadPrompt("replan-slice", { @@ -1568,7 +1792,7 @@ export async function buildRunUatPrompt( const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`); - const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "UAT")); + const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT")); const uatType = getUatType(uatContent); return loadPrompt("run-uat", { @@ -1596,14 +1820,18 @@ export async function buildReassessRoadmapPrompt( const roadmapRel = relMilestoneFile(base, mid, "ROADMAP"); const summaryPath = resolveSliceFile(base, mid, completedSliceId, "SUMMARY"); const summaryRel = relSliceFile(base, mid, completedSliceId, "SUMMARY"); + const sliceContextPath = resolveSliceFile(base, mid, completedSliceId, "CONTEXT"); + const sliceContextRel = relSliceFile(base, mid, completedSliceId, "CONTEXT"); const inlined: string[] = []; inlined.push(await inlineFile(roadmapPath, roadmapRel, "Current Roadmap")); + const sliceCtxInline = await inlineFileOptional(sliceContextPath, sliceContextRel, "Slice Context (from discussion)"); + if (sliceCtxInline) inlined.push(sliceCtxInline); inlined.push(await inlineFile(summaryPath, summaryRel, `${completedSliceId} Summary`)); if (inlineLevel !== "minimal") { const projectInline = await inlineProjectFromDb(base); if (projectInline) inlined.push(projectInline); - const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel); + const requirementsInline = await inlineRequirementsFromDb(base, mid, undefined, inlineLevel); if (requirementsInline) inlined.push(requirementsInline); const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel); if (decisionsInline) inlined.push(decisionsInline); @@ -1625,8 +1853,8 @@ export async function buildReassessRoadmapPrompt( `- **${c.id}**: "${c.text}" — ${c.rationale ?? "deferred during triage"}` ).join("\n"); } - } catch { - // Non-fatal — captures module may not be available + } catch (err) { + logWarning("prompt", `loadDeferredCaptures failed: ${err instanceof Error ? err.message : String(err)}`); } const reassessCommitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git."; @@ -1749,6 +1977,36 @@ const GATE_QUESTIONS: Record = { }, }; +export async function buildParallelResearchSlicesPrompt( + mid: string, + midTitle: string, + slices: Array<{ id: string; title: string }>, + basePath: string, +): Promise { + // Build individual research-slice prompts for each slice + const subagentSections: string[] = []; + for (const slice of slices) { + const slicePrompt = await buildResearchSlicePrompt(mid, midTitle, slice.id, slice.title, basePath); + subagentSections.push([ + `### ${slice.id}: ${slice.title}`, + "", + "Use this as the prompt for a `subagent` call (agent: `gsd-executor` or the default agent):", + "", + "```", + slicePrompt, + "```", + ].join("\n")); + } + + return loadPrompt("parallel-research-slices", { + mid, + midTitle, + sliceCount: String(slices.length), + sliceList: slices.map((s) => `- **${s.id}**: ${s.title}`).join("\n"), + subagentPrompts: subagentSections.join("\n\n---\n\n"), + }); +} + export async function buildGateEvaluatePrompt( mid: string, midTitle: string, sid: string, sTitle: string, base: string, @@ -1842,7 +2100,9 @@ export async function buildRewriteDocsPrompt( .filter(t => t.status !== "complete" && t.status !== "done") .map(t => ({ id: t.id })); } - } catch { /* fall through */ } + } catch (err) { + logWarning("prompt", `buildRewriteDocsPrompt DB task lookup failed: ${err instanceof Error ? err.message : String(err)}`); + } if (!incompleteTasks) { // DB unavailable — no task data to inline diff --git a/src/resources/extensions/gsd/auto-recovery.ts b/src/resources/extensions/gsd/auto-recovery.ts index 9181d7fe8..92086af16 100644 --- a/src/resources/extensions/gsd/auto-recovery.ts +++ b/src/resources/extensions/gsd/auto-recovery.ts @@ -9,11 +9,14 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent"; import { parseUnitId } from "./unit-id.js"; +import { appendEvent } from "./workflow-events.js"; import { atomicWriteSync } from "./atomic-write.js"; import { clearParseCache } from "./files.js"; import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js"; -import { isDbAvailable, getTask, getSlice, getSliceTasks, updateTaskStatus } from "./gsd-db.js"; +import { isDbAvailable, getTask, getSlice, getSliceTasks, getPendingGates, updateTaskStatus, updateSliceStatus } from "./gsd-db.js"; import { isValidationTerminal } from "./state.js"; +import { getErrorMessage } from "./error-utils.js"; +import { logWarning, logError } from "./workflow-logger.js"; import { nativeConflictFiles, nativeCommit, @@ -58,21 +61,21 @@ export { resolveExpectedArtifactPath, diagnoseExpectedArtifact }; * in the git history. Uses `git log --name-only` to inspect all commits on the * current branch that touch files outside `.gsd/`. * - * Returns true if at least one non-`.gsd/` file was committed, false otherwise. - * Non-fatal: returns true on git errors to avoid blocking the pipeline when - * running outside a git repo (e.g., tests). + * Returns "present" if implementation files found, "absent" if only .gsd/ files, + * "unknown" if git is unavailable or check failed (callers decide how to handle). */ -export function hasImplementationArtifacts(basePath: string): boolean { +export function hasImplementationArtifacts(basePath: string): "present" | "absent" | "unknown" { try { - // Verify we're in a git repo — fail open if not + // Verify we're in a git repo try { execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8", }); - } catch { - return true; + } catch (e) { + logWarning("recovery", `git rev-parse check failed: ${(e as Error).message}`); + return "unknown"; } // Strategy: check `git diff --name-only` against the merge-base with the @@ -82,18 +85,19 @@ export function hasImplementationArtifacts(basePath: string): boolean { const mainBranch = detectMainBranch(basePath); const changedFiles = getChangedFilesSinceBranch(basePath, mainBranch); - // No files changed at all — fail open (could be detached HEAD, single- + // No files changed at all — unknown (could be detached HEAD, single- // commit repo, or other edge case where git diff returns nothing). - if (changedFiles.length === 0) return true; + if (changedFiles.length === 0) return "unknown"; // Filter out .gsd/ files — only implementation files count. // If every changed file is under .gsd/, the milestone produced no // implementation code (#1703). const implFiles = changedFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\")); - return implFiles.length > 0; - } catch { - // Non-fatal — if git operations fail, don't block the pipeline - return true; + return implFiles.length > 0 ? "present" : "absent"; + } catch (e) { + // Non-fatal — if git operations fail, return unknown so callers can decide + logWarning("recovery", `implementation artifact check failed: ${(e as Error).message}`); + return "unknown"; } } @@ -108,8 +112,9 @@ function detectMainBranch(basePath: string): string { encoding: "utf-8", }); if (result.trim()) return "main"; - } catch { - // main doesn't exist + } catch (_) { + // Expected — main doesn't exist, try master next + void _; } try { const result = execFileSync("git", ["rev-parse", "--verify", "master"], { @@ -118,10 +123,13 @@ function detectMainBranch(basePath: string): string { encoding: "utf-8", }); if (result.trim()) return "master"; - } catch { - // master doesn't exist either + } catch (_) { + // Expected — master doesn't exist either + void _; } - return "main"; // default fallback + // Neither main nor master found — warn and fall back + logWarning("recovery", "neither main nor master branch found, defaulting to main"); + return "main"; } /** @@ -143,8 +151,9 @@ function getChangedFilesSinceBranch(basePath: string, targetBranch: string): str ).trim(); return result ? result.split("\n").filter(Boolean) : []; } - } catch { + } catch (err) { // merge-base failed — fall back + logWarning("recovery", `merge-base detection failed: ${err instanceof Error ? err.message : String(err)}`); } // Fallback: check last 20 commits @@ -154,7 +163,8 @@ function getChangedFilesSinceBranch(basePath: string, targetBranch: string): str { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }, ).trim(); return result ? [...new Set(result.split("\n").filter(Boolean))] : []; - } catch { + } catch (e) { + logWarning("recovery", `git log fallback failed: ${(e as Error).message}`); return []; } } @@ -238,15 +248,15 @@ export function verifyExpectedArtifact( if (gateIds.length === 0) return true; try { - const { getPendingGates: getPending } = require("./gsd-db.js"); - const pending = getPending(mid, sid, "slice"); + const pending = getPendingGates(mid, sid, "slice"); const pendingIds = new Set(pending.map((g: any) => g.gate_id)); // All dispatched gates must no longer be pending for (const gid of gateIds) { if (pendingIds.has(gid)) return false; } - } catch { + } catch (err) { // DB unavailable — treat as verified to avoid blocking + logWarning("recovery", `gate-evaluate DB check failed: ${err instanceof Error ? err.message : String(err)}`); } return true; } @@ -275,7 +285,7 @@ export function verifyExpectedArtifact( if (!hasCheckboxTask && !hasHeadingTask) return false; } - // execute-task: DB status is authoritative. Fall back to heading-style plan + // execute-task: DB status is authoritative. Fall back to checked-checkbox // detection when the DB is unavailable (unmigrated projects). if (unitType === "execute-task") { const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId); @@ -286,20 +296,22 @@ export function verifyExpectedArtifact( if (dbTask.status !== "complete" && dbTask.status !== "done") return false; } else if (!isDbAvailable()) { // LEGACY: Pre-migration fallback for projects without DB. - // Fall back to plan heading check (format detection, not reconciliation). - // Heading-style entries (### T01 --) count as verified because the - // summary file existence (checked above) is the real signal. + // Require a CHECKED checkbox — a bare heading or unchecked checkbox + // does not prove gsd_complete_task ran. Summary file on disk alone + // is not sufficient evidence (could be a rogue write) (#3607). const planAbs = resolveSliceFile(base, mid, sid, "PLAN"); if (planAbs && existsSync(planAbs)) { const planContent = readFileSync(planAbs, "utf-8"); const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); - const hdRe = new RegExp(`^#{2,4}\\s+${escapedTid}\\s*(?:--|—|:)`, "m"); const cbRe = new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m"); - if (!hdRe.test(planContent) && !cbRe.test(planContent)) return false; + if (!cbRe.test(planContent)) return false; + } else { + return false; // no plan file → cannot verify } + } else { + // DB available but task row not found — completion tool never ran (#3607) + return false; } - // else: DB available but task not found — summary file exists (checked above), - // so treat as verified (task may not be imported yet) } } @@ -334,8 +346,9 @@ export function verifyExpectedArtifact( } } } - } catch { + } catch (err) { // Parse failure — don't block; slice plan may have non-standard format + logWarning("recovery", `plan-slice task plan verification failed: ${err instanceof Error ? err.message : String(err)}`); } } } @@ -365,7 +378,8 @@ export function verifyExpectedArtifact( const roadmap = parseLegacyRoadmap(roadmapContent); const slice = roadmap.slices.find((s) => s.id === sid); if (slice && !slice.done) return false; - } catch { + } catch (e) { + logWarning("recovery", `roadmap parse failed: ${(e as Error).message}`); return false; } } @@ -379,7 +393,7 @@ export function verifyExpectedArtifact( // A milestone with only .gsd/ plan files and zero implementation code is // not genuinely complete — the LLM wrote plan files but skipped actual work. if (unitType === "complete-milestone") { - if (!hasImplementationArtifacts(base)) return false; + if (hasImplementationArtifacts(base) === "absent") return false; } return true; @@ -411,13 +425,20 @@ export function writeBlockerPlaceholder( ].join("\n"); writeFileSync(absPath, content, "utf-8"); - // Mark the task as complete in the DB so verifyExpectedArtifact passes. + // Mark the task/slice as complete in the DB so verifyExpectedArtifact passes. // Without this, the DB status stays "pending" and the dispatch loop - // re-derives the same task indefinitely (#2531). - if (unitType === "execute-task" && isDbAvailable()) { + // re-derives the same unit indefinitely (#2531, #2653). + if (isDbAvailable()) { const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId); - if (mid && sid && tid) { - try { updateTaskStatus(mid, sid, tid, "complete", new Date().toISOString()); } catch { /* non-fatal */ } + const ts = new Date().toISOString(); + if (unitType === "execute-task" && mid && sid && tid) { + try { updateTaskStatus(mid, sid, tid, "complete", ts); } catch (e) { logWarning("recovery", `updateTaskStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`); } + // Append event so worktree reconciliation can replay this recovery completion + try { appendEvent(base, { cmd: "complete-task", params: { milestoneId: mid, sliceId: sid, taskId: tid }, ts, actor: "system", trigger_reason: "blocker-placeholder-recovery" }); } catch (e) { logWarning("recovery", `appendEvent failed for task recovery: ${e instanceof Error ? e.message : String(e)}`); } + } + if (unitType === "complete-slice" && mid && sid) { + try { updateSliceStatus(mid, sid, "complete", ts); } catch (e) { logWarning("recovery", `updateSliceStatus failed during context exhaustion: ${e instanceof Error ? e.message : String(e)}`); } + try { appendEvent(base, { cmd: "complete-slice", params: { milestoneId: mid, sliceId: sid }, ts, actor: "system", trigger_reason: "blocker-placeholder-recovery" }); } catch (e) { logWarning("recovery", `appendEvent failed for slice recovery: ${e instanceof Error ? e.message : String(e)}`); } } } @@ -438,49 +459,59 @@ function abortAndResetMerge( if (hasMergeHead) { try { nativeMergeAbort(basePath); - } catch { + } catch (err) { /* best-effort */ + logWarning("recovery", `git merge-abort failed: ${err instanceof Error ? err.message : String(err)}`); } } else if (squashMsgPath) { try { unlinkSync(squashMsgPath); - } catch { + } catch (err) { /* best-effort */ + logWarning("recovery", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`); } } try { nativeResetHard(basePath); - } catch { + } catch (err) { /* best-effort */ + logError("recovery", `git reset failed: ${err instanceof Error ? err.message : String(err)}`); } } +export type MergeReconcileResult = "clean" | "reconciled" | "blocked"; + /** * Detect leftover merge state from a prior session and reconcile it. * If MERGE_HEAD or SQUASH_MSG exists, check whether conflicts are resolved. - * If resolved: finalize the commit. If still conflicted: abort and reset. - * - * Returns true if state was dirty and re-derivation is needed. + * If resolved: finalize the commit. If only .gsd conflicts remain: auto-resolve. + * If code conflicts remain: fail safe without modifying the worktree. */ export function reconcileMergeState( basePath: string, ctx: ExtensionContext, -): boolean { +): MergeReconcileResult { const mergeHeadPath = join(basePath, ".git", "MERGE_HEAD"); const squashMsgPath = join(basePath, ".git", "SQUASH_MSG"); const hasMergeHead = existsSync(mergeHeadPath); const hasSquashMsg = existsSync(squashMsgPath); - if (!hasMergeHead && !hasSquashMsg) return false; + if (!hasMergeHead && !hasSquashMsg) return "clean"; const conflictedFiles = nativeConflictFiles(basePath); if (conflictedFiles.length === 0) { // All conflicts resolved — finalize the merge/squash commit try { - nativeCommit(basePath, ""); // --no-edit equivalent: use empty message placeholder - const mode = hasMergeHead ? "merge" : "squash commit"; - ctx.ui.notify(`Finalized leftover ${mode} from prior session.`, "info"); - } catch { - // Commit may already exist; non-fatal + const commitSha = nativeCommit(basePath, "chore(gsd): reconcile merge state"); + if (commitSha) { + const mode = hasMergeHead ? "merge" : "squash commit"; + ctx.ui.notify(`Finalized leftover ${mode} from prior session.`, "info"); + } else { + ctx.ui.notify("No new commit needed for leftover merge/squash state — already committed.", "info"); + } + } catch (err) { + const errorMessage = getErrorMessage(err); + ctx.ui.notify(`Failed to finalize leftover merge/squash commit: ${errorMessage}`, "error"); + return "blocked"; } } else { // Still conflicted — try auto-resolving .gsd/ state file conflicts (#530) @@ -493,7 +524,8 @@ export function reconcileMergeState( try { nativeCheckoutTheirs(basePath, gsdConflicts); nativeAddPaths(basePath, gsdConflicts); - } catch { + } catch (e) { + logError("recovery", `auto-resolve .gsd/ conflicts failed: ${(e as Error).message}`); resolved = false; } if (resolved) { @@ -506,7 +538,8 @@ export function reconcileMergeState( `Auto-resolved ${gsdConflicts.length} .gsd/ state file conflict(s) from prior merge.`, "info", ); - } catch { + } catch (e) { + logError("recovery", `auto-commit .gsd/ conflict resolution failed: ${(e as Error).message}`); resolved = false; } } @@ -518,15 +551,16 @@ export function reconcileMergeState( ); } } else { - // Code conflicts present — abort and reset - abortAndResetMerge(basePath, hasMergeHead, squashMsgPath); + // Code conflicts present — fail safe and preserve any manual resolution + // work instead of discarding it with merge --abort/reset --hard. ctx.ui.notify( - "Detected leftover merge state with unresolved conflicts — cleaned up. Re-deriving state.", - "warning", + "Detected leftover merge state with unresolved code conflicts. Auto-mode will pause without modifying the worktree so manual conflict resolution is preserved.", + "error", ); + return "blocked"; } } - return true; + return "reconciled"; } // ─── Loop Remediation ───────────────────────────────────────────────────────── diff --git a/src/resources/extensions/gsd/auto-start.ts b/src/resources/extensions/gsd/auto-start.ts index 85bdbe370..5856bd0b9 100644 --- a/src/resources/extensions/gsd/auto-start.ts +++ b/src/resources/extensions/gsd/auto-start.ts @@ -15,6 +15,7 @@ import type { } from "@gsd/pi-coding-agent"; import { deriveState } from "./state.js"; import { loadFile, getManifestStatus } from "./files.js"; +import type { InterruptedSessionAssessment } from "./interrupted-session.js"; import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, @@ -23,16 +24,9 @@ import { import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-identity.js"; import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js"; import { collectSecretsFromManifest } from "../get-secrets-from-user.js"; -import { gsdRoot, resolveMilestoneFile, milestonesDir } from "./paths.js"; +import { gsdRoot, resolveMilestoneFile } from "./paths.js"; import { invalidateAllCaches } from "./cache.js"; -import { synthesizeCrashRecovery } from "./session-forensics.js"; -import { - writeLock, - clearLock, - readCrashLock, - formatCrashInfo, - isLockProcessAlive, -} from "./crash-recovery.js"; +import { writeLock, clearLock } from "./crash-recovery.js"; import { acquireSessionLock, releaseSessionLock, @@ -44,6 +38,13 @@ import { nativeInit, nativeAddAll, nativeCommit, + nativeGetCurrentBranch, + nativeDetectMainBranch, + nativeCheckoutBranch, + nativeBranchList, + nativeBranchListMerged, + nativeBranchDelete, + nativeWorktreeRemove, } from "./native-git-bridge.js"; import { GitServiceImpl } from "./git-service.js"; import { @@ -53,6 +54,7 @@ import { } from "./worktree.js"; import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js"; import { readResourceVersion, cleanStaleRuntimeUnits } from "./auto-worktree.js"; +import { worktreePath as getWorktreeDir, isInsideWorktreesDir } from "./worktree-manager.js"; import { initMetrics } from "./metrics.js"; import { initRoutingHistory } from "./routing-history.js"; import { restoreHookState, resetHookState } from "./post-unit-hooks.js"; @@ -60,26 +62,28 @@ import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactiv import { snapshotSkills } from "./skill-discovery.js"; import { isDbAvailable, getMilestone, openDatabase } from "./gsd-db.js"; import { hideFooter } from "./auto-dashboard.js"; -import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js"; import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js"; +import { logWarning, logError } from "./workflow-logger.js"; import { parseUnitId } from "./unit-id.js"; -import { setLogBasePath } from "./workflow-logger.js"; import type { AutoSession } from "./auto/session.js"; import { existsSync, mkdirSync, readdirSync, + rmSync, statSync, unlinkSync, } from "node:fs"; import { join } from "node:path"; import { sep as pathSep } from "node:path"; +import { resolveProjectRootDbPath } from "./bootstrap/dynamic-tools.js"; +import { resolveDefaultSessionModel, resolveDynamicRoutingConfig } from "./preferences-models.js"; import type { WorktreeResolver } from "./worktree-resolver.js"; export interface BootstrapDeps { @@ -98,26 +102,138 @@ export interface BootstrapDeps { * concurrent session detected). Returns true when ready to dispatch. */ -/** Guard: tracks consecutive bootstrap attempts that found phase === "complete". - * Prevents the recursive dialog loop described in #1348 where - * bootstrapAutoSession → showSmartEntry → checkAutoStartAfterDiscuss → startAuto - * cycles indefinitely when the discuss workflow doesn't produce a milestone. */ -let _consecutiveCompleteBootstraps = 0; +// Guard constant for consecutive bootstrap attempts that found phase === "complete". +// Counter moved to AutoSession.consecutiveCompleteBootstraps so s.reset() clears it. const MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS = 2; -async function openProjectDbIfPresent(basePath: string): Promise { +export async function openProjectDbIfPresent(basePath: string): Promise { const gsdDbPath = resolveProjectRootDbPath(basePath); if (!existsSync(gsdDbPath) || isDbAvailable()) return; try { openDatabase(gsdDbPath); } catch (err) { - process.stderr.write( - `gsd-db: failed to open existing database: ${(err as Error).message}\n`, - ); + logWarning("engine", `gsd-db: failed to open existing database: ${err instanceof Error ? err.message : String(err)}`); } } +/** + * Audit for orphaned milestone branches at bootstrap. + * + * After a milestone completes, the teardown step (merge branch → main, + * delete branch, remove worktree) runs as a post-completion engine step. + * If the session ends between completion and teardown, the branch and + * worktree are orphaned — the DB says "complete" so auto-mode won't + * re-enter the milestone, and the teardown is never retried. + * + * This audit runs on every fresh bootstrap to catch that gap: + * 1. Lists all local `milestone/*` branches. + * 2. For each, checks if the milestone's DB status is "complete". + * 3. If the branch is already merged into main → deletes the branch + * and cleans up any orphaned worktree directory (safe, no data loss). + * 4. If the branch is NOT merged → preserves it and warns the user + * so they can merge manually (data safety first). + * + * Returns a summary of actions taken for the caller to surface via notify. + */ +export function auditOrphanedMilestoneBranches( + basePath: string, + isolationMode: "worktree" | "branch" | "none", +): { recovered: string[]; warnings: string[] } { + const recovered: string[] = []; + const warnings: string[] = []; + + // Skip in none mode — no milestone branches are created + if (isolationMode === "none") return { recovered, warnings }; + + // Skip if DB not available — can't determine completion status + if (!isDbAvailable()) return { recovered, warnings }; + + let milestoneBranches: string[]; + try { + milestoneBranches = nativeBranchList(basePath, "milestone/*"); + } catch { + // git branch list failed — skip audit + return { recovered, warnings }; + } + + if (milestoneBranches.length === 0) return { recovered, warnings }; + + // Detect main branch for merge-check + let mainBranch: string; + try { + mainBranch = nativeDetectMainBranch(basePath); + } catch { + mainBranch = "main"; + } + + // Get branches already merged into main + let mergedBranches: Set; + try { + mergedBranches = new Set(nativeBranchListMerged(basePath, mainBranch, "milestone/*")); + } catch { + mergedBranches = new Set(); + } + + for (const branch of milestoneBranches) { + const milestoneId = branch.replace(/^milestone\//, ""); + const milestone = getMilestone(milestoneId); + + // Only audit completed milestones + if (!milestone || milestone.status !== "complete") continue; + + const isMerged = mergedBranches.has(branch); + + if (isMerged) { + // Branch is merged — safe to delete branch and clean up worktree dir + try { + nativeBranchDelete(basePath, branch, true); + recovered.push(`Deleted merged branch ${branch} for completed milestone ${milestoneId}.`); + } catch (err) { + warnings.push(`Failed to delete merged branch ${branch}: ${err instanceof Error ? err.message : String(err)}`); + } + + // Clean up orphaned worktree directory if it exists + const wtDir = getWorktreeDir(basePath, milestoneId); + if (existsSync(wtDir)) { + // Try git worktree remove first (handles registered worktrees) + try { + nativeWorktreeRemove(basePath, wtDir, true); + } catch (e) { + // Not a registered worktree — expected for orphaned dirs + logWarning("engine", `worktree remove failed (expected for orphaned dirs): ${e instanceof Error ? e.message : String(e)}`); + } + + // If the directory still exists after git worktree remove (either it + // wasn't registered or the remove was a noop), fall back to direct + // filesystem removal — but only inside .gsd/worktrees/ for safety (#2365). + if (existsSync(wtDir)) { + if (isInsideWorktreesDir(basePath, wtDir)) { + try { + rmSync(wtDir, { recursive: true, force: true }); + recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`); + } catch (err2) { + warnings.push(`Failed to remove worktree directory for ${milestoneId}: ${err2 instanceof Error ? err2.message : String(err2)}`); + } + } else { + warnings.push(`Orphaned worktree directory for ${milestoneId} is outside .gsd/worktrees/ — skipping removal for safety.`); + } + } else { + recovered.push(`Removed orphaned worktree directory for ${milestoneId}.`); + } + } + } else { + // Branch is NOT merged — preserve for safety, warn the user + warnings.push( + `Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` + + `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`, + ); + } + } + + return { recovered, warnings }; +} + export async function bootstrapAutoSession( s: AutoSession, ctx: ExtensionCommandContext, @@ -126,6 +242,7 @@ export async function bootstrapAutoSession( verboseMode: boolean, requestedStepMode: boolean, deps: BootstrapDeps, + interrupted: InterruptedSessionAssessment, ): Promise { const { shouldUseWorktreeIsolation, @@ -148,12 +265,16 @@ export async function bootstrapAutoSession( // Capture the user's session model before guided-flow dispatch can apply a // phase-specific planning model for a discuss turn (#2829). - const startModelSnapshot = ctx.model - ? { - provider: ctx.model.provider, - id: ctx.model.id, - } - : null; + // + // GSD PREFERENCES.md takes priority over the session model from settings.json + // (#3517). The session model (ctx.model) comes from findInitialModel() which + // reads defaultProvider/defaultModel from ~/.gsd/agent/settings.json. When + // the user has explicit model preferences in PREFERENCES.md, those should win. + const preferredModel = resolveDefaultSessionModel(ctx.model?.provider); + const startModelSnapshot = preferredModel + ?? (ctx.model + ? { provider: ctx.model.provider, id: ctx.model.id } + : null); try { // Validate GSD_PROJECT_ID early so the user gets immediate feedback @@ -198,69 +319,33 @@ export async function bootstrapAutoSession( ensureGitignore(base, { manageGitignore }); if (manageGitignore !== false) untrackRuntimeFiles(base); - // Bootstrap .gsd/ if it doesn't exist + // Bootstrap milestones/ if it doesn't exist. + // Check milestones/ directly — ensureGsdSymlink above already created .gsd/, + // so checking .gsd/ existence would be dead code (#2942). const gsdDir = join(base, ".gsd"); - if (!existsSync(gsdDir)) { - mkdirSync(join(gsdDir, "milestones"), { recursive: true }); + const milestonesPath = join(gsdDir, "milestones"); + if (!existsSync(milestonesPath)) { + mkdirSync(milestonesPath, { recursive: true }); try { nativeAddAll(base); nativeCommit(base, "chore: init gsd"); - } catch { + } catch (err) { /* nothing to commit */ + logWarning("engine", `mkdir failed: ${err instanceof Error ? err.message : String(err)}`); } } + { + const { prepareWorkflowMcpForProject } = await import("./workflow-mcp-auto-prep.js"); + prepareWorkflowMcpForProject(ctx, base); + } + // Initialize GitServiceImpl s.gitService = new GitServiceImpl( s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {}, ); - // Check for crash from previous session. Skip our own fresh bootstrap lock. - const crashLock = readCrashLock(base); - if (crashLock && crashLock.pid !== process.pid) { - if (isLockProcessAlive(crashLock)) { - ctx.ui.notify( - `Another auto-mode session (PID ${crashLock.pid}) appears to be running.\nStop it with \`kill ${crashLock.pid}\` before starting a new session.`, - "error", - ); - return releaseLockAndReturn(); - } - const recoveredMid = parseUnitId(crashLock.unitId).milestone; - const milestoneAlreadyComplete = recoveredMid - ? !!resolveMilestoneFile(base, recoveredMid, "SUMMARY") - : false; - - if (milestoneAlreadyComplete) { - ctx.ui.notify( - `Crash recovery: discarding stale context for ${crashLock.unitId} — milestone ${recoveredMid} is already complete.`, - "info", - ); - } else { - const activityDir = join(gsdRoot(base), "activity"); - const recovery = synthesizeCrashRecovery( - base, - crashLock.unitType, - crashLock.unitId, - crashLock.sessionFile, - activityDir, - ); - if (recovery && recovery.trace.toolCallCount > 0) { - s.pendingCrashRecovery = recovery.prompt; - ctx.ui.notify( - `${formatCrashInfo(crashLock)}\nRecovered ${recovery.trace.toolCallCount} tool calls from crashed session. Resuming with full context.`, - "warning", - ); - } else { - ctx.ui.notify( - `${formatCrashInfo(crashLock)}\nNo session data recovered. Resuming from disk state.`, - "warning", - ); - } - } - clearLock(base); - } - // ── Debug mode ── if (!isDebugEnabled() && process.env.GSD_DEBUG === "1") { enableDebug(base); @@ -280,9 +365,9 @@ export async function bootstrapAutoSession( ctx.ui.notify(`Debug logging enabled → ${getDebugLogPath()}`, "info"); } - // Open the project DB before the first derive so resume uses DB truth - // immediately on cold starts instead of falling back to markdown (#2841). - await openProjectDbIfPresent(base); + if (interrupted.classification !== "recoverable") { + s.pendingCrashRecovery = null; + } // Invalidate caches before initial state derivation invalidateAllCaches(); @@ -293,6 +378,30 @@ export async function bootstrapAutoSession( (mid) => !!resolveMilestoneFile(base, mid, "SUMMARY"), ); + // Open the project-root DB before deriveState so DB-backed state + // derivation (queue-order, task status) works on a cold start (#2841). + await openProjectDbIfPresent(base); + + // ── Orphaned milestone branch audit ── + // Catches completed milestones whose teardown (merge + branch delete) + // was lost due to session ending between completion and teardown. + // Must run after DB open and before worktree entry. + try { + const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode()); + for (const msg of auditResult.recovered) { + ctx.ui.notify(`Orphan audit: ${msg}`, "info"); + } + for (const msg of auditResult.warnings) { + ctx.ui.notify(`Orphan audit: ${msg}`, "warning"); + } + if (auditResult.recovered.length > 0) { + debugLog("orphan-audit", { recovered: auditResult.recovered, warnings: auditResult.warnings }); + } + } catch (err) { + // Non-fatal — the audit is defensive, never block bootstrap + logWarning("bootstrap", `orphaned milestone branch audit failed: ${err instanceof Error ? err.message : String(err)}`); + } + let state = await deriveState(base); // Stale worktree state recovery (#654) @@ -382,9 +491,9 @@ export async function bootstrapAutoSession( // Guard against recursive dialog loop (#1348): // If we've entered this branch multiple times in quick succession, // the discuss workflow isn't producing a milestone. Break the cycle. - _consecutiveCompleteBootstraps++; - if (_consecutiveCompleteBootstraps > MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS) { - _consecutiveCompleteBootstraps = 0; + s.consecutiveCompleteBootstraps++; + if (s.consecutiveCompleteBootstraps > MAX_CONSECUTIVE_COMPLETE_BOOTSTRAPS) { + s.consecutiveCompleteBootstraps = 0; ctx.ui.notify( "All milestones are complete and the discussion didn't produce a new one. " + "Run /gsd to start a new milestone manually.", @@ -403,7 +512,7 @@ export async function bootstrapAutoSession( postState.phase !== "complete" && postState.phase !== "pre-planning" ) { - _consecutiveCompleteBootstraps = 0; // Successfully advanced past "complete" + s.consecutiveCompleteBootstraps = 0; // Successfully advanced past "complete" state = postState; } else if ( postState.activeMilestone && @@ -482,7 +591,7 @@ export async function bootstrapAutoSession( } // Successfully resolved an active milestone — reset the re-entry guard - _consecutiveCompleteBootstraps = 0; + s.consecutiveCompleteBootstraps = 0; // ── Initialize session state ── s.active = true; @@ -490,7 +599,6 @@ export async function bootstrapAutoSession( s.verbose = verboseMode; s.cmdCtx = ctx; s.basePath = base; - setLogBasePath(base); s.unitDispatchCount.clear(); s.unitRecoveryCount.clear(); s.lastBudgetAlertLevel = 0; @@ -522,6 +630,22 @@ export async function bootstrapAutoSession( setActiveMilestoneId(base, s.currentMilestoneId); } + // Guard against stale milestone branch when isolation:none (#3613). + // A prior session with isolation:branch/worktree may have left HEAD on + // milestone/. Auto-checkout back to the integration branch. + if (getIsolationMode() === "none" && nativeIsRepo(base)) { + try { + const currentBranch = nativeGetCurrentBranch(base); + if (currentBranch.startsWith("milestone/")) { + const integrationBranch = nativeDetectMainBranch(base); + nativeCheckoutBranch(base, integrationBranch); + logWarning("bootstrap", `Returned to "${integrationBranch}" — HEAD was on stale milestone branch "${currentBranch}" (isolation: none does not use milestone branches).`); + } + } catch (err) { + logWarning("bootstrap", `Could not auto-checkout from stale milestone branch: ${err instanceof Error ? err.message : String(err)}`); + } + } + // ── Auto-worktree setup ── s.originalBasePath = base; @@ -561,24 +685,22 @@ export async function bootstrapAutoSession( const hasRequirements = existsSync(join(gsdDirPath, "REQUIREMENTS.md")); const hasMilestones = existsSync(join(gsdDirPath, "milestones")); try { - openDatabase(gsdDbPath); + const { openDatabase: openDb } = await import("./gsd-db.js"); + openDb(gsdDbPath); if (hasDecisions || hasRequirements || hasMilestones) { const { migrateFromMarkdown } = await import("./md-importer.js"); migrateFromMarkdown(s.basePath); } } catch (err) { - process.stderr.write( - `gsd-migrate: auto-migration failed: ${(err as Error).message}\n`, - ); + logError("engine", `auto-migration failed: ${(err as Error).message}`); } } if (existsSync(gsdDbPath) && !isDbAvailable()) { try { - openDatabase(gsdDbPath); + const { openDatabase: openDb } = await import("./gsd-db.js"); + openDb(gsdDbPath); } catch (err) { - process.stderr.write( - `gsd-db: failed to open existing database: ${(err as Error).message}\n`, - ); + logError("engine", `failed to open existing database: ${(err as Error).message}`); } } @@ -610,6 +732,25 @@ export async function bootstrapAutoSession( }; } + // Apply worker model override from parallel orchestrator (#worker-model). + // GSD_WORKER_MODEL is injected by the coordinator when parallel.worker_model + // is configured, so parallel milestone workers use a cheaper model than the + // coordinator session (e.g. Haiku for execution, Sonnet for planning). + const workerModelOverride = process.env.GSD_WORKER_MODEL; + if (workerModelOverride && process.env.GSD_PARALLEL_WORKER === "1") { + const availableModels = ctx.modelRegistry.getAvailable(); + const { resolveModelId } = await import("./auto-model-selection.js"); + const overrideModel = resolveModelId(workerModelOverride, availableModels, ctx.model?.provider); + if (overrideModel) { + const ok = await pi.setModel(overrideModel, { persist: false }); + if (ok) { + // Update start model so all subsequent units use this as the baseline + s.autoModeStartModel = { provider: overrideModel.provider, id: overrideModel.id }; + ctx.ui.notify(`Worker model override: ${overrideModel.provider}/${overrideModel.id}`, "info"); + } + } + } + // Snapshot installed skills if (resolveSkillDiscoveryMode() !== "off") { snapshotSkills(); @@ -627,6 +768,39 @@ export async function bootstrapAutoSession( : "Will loop until milestone complete."; ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info"); + // Show dynamic routing status so users know upfront if models will be + // downgraded for simple tasks (#3962). + // Use the same effective logic as selectAndApplyModel: check flat-rate + // provider suppression and resolve the actual ceiling model. + const routingConfig = resolveDynamicRoutingConfig(); + const startModelLabel = s.autoModeStartModel + ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` + : ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "default"; + + // Flat-rate providers (e.g. GitHub Copilot, claude-code) suppress routing + // at dispatch time (#3453) — reflect that in the banner. + const { isFlatRateProvider } = await import("./auto-model-selection.js"); + const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider; + const effectivelyEnabled = routingConfig.enabled + && !(effectiveProvider && isFlatRateProvider(effectiveProvider)); + + // The actual ceiling may come from tier_models.heavy, not the start model. + const effectiveCeiling = (routingConfig.enabled && routingConfig.tier_models?.heavy) + ? routingConfig.tier_models.heavy + : startModelLabel; + + if (effectivelyEnabled) { + ctx.ui.notify( + `Dynamic routing: enabled — simple tasks may use cheaper models (ceiling: ${effectiveCeiling})`, + "info", + ); + } else { + ctx.ui.notify( + `Dynamic routing: disabled — all tasks will use ${startModelLabel}`, + "info", + ); + } + updateSessionLock( lockBase(), "starting", @@ -715,8 +889,9 @@ export async function bootstrapAutoSession( } } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("engine", `preflight validation failed: ${err instanceof Error ? err.message : String(err)}`); } return true; diff --git a/src/resources/extensions/gsd/auto-timers.ts b/src/resources/extensions/gsd/auto-timers.ts index afa3af98b..3b7b11f81 100644 --- a/src/resources/extensions/gsd/auto-timers.ts +++ b/src/resources/extensions/gsd/auto-timers.ts @@ -24,6 +24,7 @@ import { saveActivityLog } from "./activity-log.js"; import { recoverTimedOutUnit, type RecoveryContext } from "./auto-timeout-recovery.js"; import { resolveAgentEndCancelled } from "./auto/resolve.js"; import type { AutoSession } from "./auto/session.js"; +import { logWarning, logError } from "./workflow-logger.js"; export interface SupervisionContext { s: AutoSession; @@ -99,13 +100,15 @@ export function startUnitSupervision(sctx: SupervisionContext): void { } } } - } catch { + } catch (err) { // Non-fatal — fall through with no estimate + logWarning("timer", `operation failed: ${err instanceof Error ? err.message : String(err)}`); } } const estimateMinutes = taskEstimate ? parseEstimateMinutes(taskEstimate) : null; + const MAX_TIMEOUT_SCALE = 6; // Cap at 6x (60min task). Prevents 2h+ tasks from creating 120min+ timeout windows. const timeoutScale = estimateMinutes && estimateMinutes > 0 - ? Math.max(1, estimateMinutes / 10) // 10min task = 1x, 30min = 3x, 2h = 12x + ? Math.min(MAX_TIMEOUT_SCALE, Math.max(1, estimateMinutes / 10)) : 1; const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale; @@ -120,6 +123,10 @@ export function startUnitSupervision(sctx: SupervisionContext): void { phase: "wrapup-warning-sent", wrapupWarningSent: true, }); + // Only trigger a new turn if no tools are currently in flight. + // Triggering during active tool calls causes tool results to be skipped + // with "Skipped due to queued user message", leading to provider errors (#3512). + const softTrigger = getInFlightToolCount() === 0; pi.sendMessage( { customType: "gsd-auto-wrapup", @@ -134,7 +141,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void { "4. leave precise resume notes if anything remains unfinished", ].join("\n"), }, - { triggerTurn: true }, + { triggerTurn: softTrigger }, ); }, softTimeoutMs); @@ -214,12 +221,14 @@ export function startUnitSupervision(sctx: SupervisionContext): void { await pauseAuto(ctx, pi); } catch (err) { const message = err instanceof Error ? err.message : String(err); - console.error(`[idle-watchdog] Unhandled error: ${message}`); + logError("timer", `[idle-watchdog] Unhandled error: ${message}`); // Unblock any pending unit promise so the auto-loop is not orphaned. resolveAgentEndCancelled({ message: `Idle watchdog error: ${message}`, category: "idle", isTransient: true }); try { ctx.ui.notify(`Idle watchdog error: ${message}`, "warning"); - } catch { /* best effort */ } + } catch (err) { /* best effort */ + logWarning("timer", `notification failed: ${err instanceof Error ? err.message : String(err)}`); + } } }, 15000); @@ -248,12 +257,14 @@ export function startUnitSupervision(sctx: SupervisionContext): void { await pauseAuto(ctx, pi); } catch (err) { const message = err instanceof Error ? err.message : String(err); - console.error(`[hard-timeout] Unhandled error: ${message}`); + logError("timer", `[hard-timeout] Unhandled error: ${message}`); // Unblock any pending unit promise so the auto-loop is not orphaned. resolveAgentEndCancelled({ message: `Hard timeout error: ${message}`, category: "timeout", isTransient: true }); try { ctx.ui.notify(`Hard timeout error: ${message}`, "warning"); - } catch { /* best effort */ } + } catch (err) { /* best effort */ + logWarning("timer", `notification failed: ${err instanceof Error ? err.message : String(err)}`); + } } }, hardTimeoutMs); @@ -287,6 +298,8 @@ export function startUnitSupervision(sctx: SupervisionContext): void { ); } + // Only trigger a new turn if no tools are currently in flight (#3512). + const contextTrigger = getInFlightToolCount() === 0; pi.sendMessage( { customType: "gsd-auto-wrapup", @@ -302,7 +315,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void { "Do NOT start new sub-tasks or investigations.", ].join("\n"), }, - { triggerTurn: true }, + { triggerTurn: contextTrigger }, ); if (s.continueHereHandle) { @@ -311,3 +324,4 @@ export function startUnitSupervision(sctx: SupervisionContext): void { } }, 15_000); } + diff --git a/src/resources/extensions/gsd/auto-tool-tracking.ts b/src/resources/extensions/gsd/auto-tool-tracking.ts index 65ef2ff01..cab495813 100644 --- a/src/resources/extensions/gsd/auto-tool-tracking.ts +++ b/src/resources/extensions/gsd/auto-tool-tracking.ts @@ -83,3 +83,32 @@ export function hasInteractiveToolInFlight(): boolean { export function clearInFlightTools(): void { inFlightTools.clear(); } + +// ─── Tool invocation error classification (#2883) ──────────────────────── + +/** + * Patterns that indicate a tool invocation failed due to malformed or truncated + * JSON arguments — as opposed to a normal business-logic error from the tool + * handler. When these errors occur, retrying the same unit will produce the same + * failure, so the retry loop must be broken. + */ +const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON/i; + +/** + * Returns true if the error message indicates a tool invocation failure due to + * malformed/truncated arguments (as opposed to a normal tool execution error). + */ +export function isToolInvocationError(errorMsg: string): boolean { + if (!errorMsg) return false; + return TOOL_INVOCATION_ERROR_RE.test(errorMsg); +} + +/** + * Returns true if the error message indicates the tool was skipped because + * a queued user message interrupted the turn (#3595). Retrying will produce + * the same skip, so the unit should be paused rather than retried. + */ +export function isQueuedUserMessageSkip(errorMsg: string): boolean { + if (!errorMsg) return false; + return /^Skipped due to queued user message\.?$/i.test(errorMsg.trim()); +} diff --git a/src/resources/extensions/gsd/auto-unit-closeout.ts b/src/resources/extensions/gsd/auto-unit-closeout.ts index 8d5bf4f94..ccd274176 100644 --- a/src/resources/extensions/gsd/auto-unit-closeout.ts +++ b/src/resources/extensions/gsd/auto-unit-closeout.ts @@ -7,6 +7,7 @@ import type { ExtensionContext } from "@gsd/pi-coding-agent"; import { snapshotUnitMetrics } from "./metrics.js"; import { saveActivityLog } from "./activity-log.js"; +import { logWarning } from "./workflow-logger.js"; export interface CloseoutOptions { promptCharCount?: number; @@ -38,11 +39,14 @@ export async function closeoutUnit( const llmCallFn = buildMemoryLLMCall(ctx); if (llmCallFn) { extractMemoriesFromUnit(activityFile, unitType, unitId, llmCallFn).catch((err) => { - if (process.env.GSD_DEBUG) console.error(`[gsd] memory extraction failed for ${unitType}/${unitId}:`, err); + logWarning("engine", `memory extraction failed for ${unitType}/${unitId}: ${(err as Error).message}`); }); } - } catch { /* non-fatal */ } + } catch (err) { /* non-fatal */ + logWarning("engine", `operation failed: ${err instanceof Error ? err.message : String(err)}`); + } } return activityFile ?? undefined; } + diff --git a/src/resources/extensions/gsd/auto-verification.ts b/src/resources/extensions/gsd/auto-verification.ts index 0312b60b8..73595df46 100644 --- a/src/resources/extensions/gsd/auto-verification.ts +++ b/src/resources/extensions/gsd/auto-verification.ts @@ -11,9 +11,10 @@ */ import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent"; +import { mkdirSync, writeFileSync } from "node:fs"; import { resolveSliceFile, resolveSlicePath } from "./paths.js"; import { parseUnitId } from "./unit-id.js"; -import { isDbAvailable, getTask } from "./gsd-db.js"; +import { isDbAvailable, getTask, getSliceTasks, type TaskRow } from "./gsd-db.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; import { runVerificationGate, @@ -21,8 +22,11 @@ import { captureRuntimeErrors, runDependencyAudit, } from "./verification-gate.js"; -import { writeVerificationJSON } from "./verification-evidence.js"; +import { writeVerificationJSON, type PostExecutionCheckJSON, type EvidenceJSON } from "./verification-evidence.js"; +import { logWarning } from "./workflow-logger.js"; +import { runPostExecutionChecks, type PostExecutionResult } from "./post-execution-checks.js"; import type { AutoSession } from "./auto/session.js"; +import type { VerificationResult as VerificationGateResult } from "./types.js"; import { join } from "node:path"; export interface VerificationContext { @@ -159,9 +163,7 @@ export async function runPostUnitVerification( } } } catch (evidenceErr) { - process.stderr.write( - `verification-evidence: write error — ${(evidenceErr as Error).message}\n`, - ); + logWarning("engine", `verification-evidence write error: ${(evidenceErr as Error).message}`); } } @@ -184,11 +186,140 @@ export async function runPostUnitVerification( return "continue"; } + // ── Post-execution checks (run after main verification passes for execute-task units) ── + let postExecChecks: PostExecutionCheckJSON[] | undefined; + let postExecBlockingFailure = false; + + if (result.passed && mid && sid && tid) { + // Check preferences — respect enhanced_verification and enhanced_verification_post + const enhancedEnabled = prefs?.enhanced_verification !== false; // default true + const postEnabled = prefs?.enhanced_verification_post !== false; // default true + + if (enhancedEnabled && postEnabled && isDbAvailable()) { + try { + // Get the completed task from DB + const taskRow = getTask(mid, sid, tid); + if (taskRow && taskRow.key_files && taskRow.key_files.length > 0) { + // Get all tasks in the slice + const allTasks = getSliceTasks(mid, sid); + // Filter to prior completed tasks (status = 'complete' or 'done', before current task) + const priorTasks = allTasks.filter( + (t: TaskRow) => + (t.status === "complete" || t.status === "done") && + t.id !== tid && + t.sequence < taskRow.sequence + ); + + // Run post-execution checks + const postExecResult: PostExecutionResult = runPostExecutionChecks( + taskRow, + priorTasks, + s.basePath + ); + + // Store checks for evidence JSON + postExecChecks = postExecResult.checks; + + // Log summary to stderr with gsd-post-exec: prefix + const emoji = + postExecResult.status === "pass" + ? "✅" + : postExecResult.status === "warn" + ? "⚠️" + : "❌"; + process.stderr.write( + `gsd-post-exec: ${emoji} Post-execution checks ${postExecResult.status} for ${mid}/${sid}/${tid} (${postExecResult.durationMs}ms)\n` + ); + + // Log individual check results + for (const check of postExecResult.checks) { + const checkEmoji = check.passed + ? "✓" + : check.blocking + ? "✗" + : "⚠"; + process.stderr.write( + `gsd-post-exec: ${checkEmoji} [${check.category}] ${check.target}: ${check.message}\n` + ); + } + + // Check for blocking failures + if (postExecResult.status === "fail") { + postExecBlockingFailure = true; + const blockingCount = postExecResult.checks.filter( + (c) => !c.passed && c.blocking + ).length; + ctx.ui.notify( + `Post-execution checks failed: ${blockingCount} blocking issue${blockingCount === 1 ? "" : "s"} found`, + "error" + ); + } else if (postExecResult.status === "warn") { + ctx.ui.notify( + `Post-execution checks passed with warnings`, + "warning" + ); + // Strict mode: treat warnings as blocking + if (prefs?.enhanced_verification_strict === true) { + postExecBlockingFailure = true; + } + } + } + } catch (postExecErr) { + // Post-execution check errors are non-fatal — log and continue + logWarning("engine", `gsd-post-exec: error — ${(postExecErr as Error).message}`); + } + } + } + + // Re-write verification evidence JSON with post-execution checks + if (postExecChecks && postExecChecks.length > 0 && mid && sid && tid) { + try { + const sDir = resolveSlicePath(s.basePath, mid, sid); + if (sDir) { + const tasksDir = join(sDir, "tasks"); + // Add postExecutionChecks to the result for the JSON write + const resultWithPostExec = { + ...result, + // Mark as failed if there was a blocking post-exec failure + passed: result.passed && !postExecBlockingFailure, + }; + // Manually write with postExecutionChecks field + writeVerificationJSONWithPostExec( + resultWithPostExec, + tasksDir, + tid, + s.currentUnit.id, + postExecChecks, + postExecBlockingFailure ? attempt + 1 : undefined, + postExecBlockingFailure ? maxRetries : undefined + ); + } + } catch (evidenceErr) { + logWarning("engine", `verification-evidence: post-exec write error — ${(evidenceErr as Error).message}`); + } + } + + // Update result.passed based on post-execution checks + if (postExecBlockingFailure) { + result.passed = false; + } + // ── Auto-fix retry logic ── if (result.passed) { s.verificationRetryCount.delete(s.currentUnit.id); s.pendingVerificationRetry = null; return "continue"; + } else if (postExecBlockingFailure) { + // Post-execution failures are cross-task consistency issues — retrying the same task won't fix them. + // Skip retry and pause immediately for human review. + s.verificationRetryCount.delete(s.currentUnit.id); + s.pendingVerificationRetry = null; + ctx.ui.notify( + `Post-execution checks failed — cross-task consistency issue detected, pausing for human review`, + "error", + ); + await pauseAuto(ctx, pi); + return "pause"; } else if (autoFixEnabled && attempt + 1 <= maxRetries) { const nextAttempt = attempt + 1; s.verificationRetryCount.set(s.currentUnit.id, nextAttempt); @@ -197,19 +328,30 @@ export async function runPostUnitVerification( failureContext: formatFailureContext(result), attempt: nextAttempt, }; + const failedCmds = result.checks + .filter((c) => c.exitCode !== 0) + .map((c) => c.command); + const cmdSummary = failedCmds.length <= 3 + ? failedCmds.join(", ") + : `${failedCmds.slice(0, 3).join(", ")}... and ${failedCmds.length - 3} more`; ctx.ui.notify( - `Verification failed — auto-fix attempt ${nextAttempt}/${maxRetries}`, + `Verification failed (${cmdSummary}) — auto-fix attempt ${nextAttempt}/${maxRetries}`, "warning", ); // Return "retry" — the autoLoop while loop will re-iterate with the retry context return "retry"; } else { // Gate failed, retries exhausted - const exhaustedAttempt = attempt + 1; s.verificationRetryCount.delete(s.currentUnit.id); s.pendingVerificationRetry = null; + const exhaustedFails = result.checks + .filter((c) => c.exitCode !== 0) + .map((c) => c.command); + const exhaustedSummary = exhaustedFails.length <= 3 + ? exhaustedFails.join(", ") + : `${exhaustedFails.slice(0, 3).join(", ")}... and ${exhaustedFails.length - 3} more`; ctx.ui.notify( - `Verification gate FAILED after ${exhaustedAttempt > maxRetries ? exhaustedAttempt - 1 : exhaustedAttempt} retries — pausing for human review`, + `Verification gate FAILED after ${attempt} ${attempt === 1 ? "retry" : "retries"} (${exhaustedSummary}) — pausing for human review`, "error", ); await pauseAuto(ctx, pi); @@ -217,9 +359,63 @@ export async function runPostUnitVerification( } } catch (err) { // Gate errors are non-fatal - process.stderr.write( - `verification-gate: error — ${(err as Error).message}\n`, - ); + logWarning("engine", `verification-gate error: ${(err as Error).message}`); return "continue"; } } + +/** + * Write verification evidence JSON with post-execution checks included. + * This is a variant of writeVerificationJSON that adds the postExecutionChecks field. + */ +function writeVerificationJSONWithPostExec( + result: VerificationGateResult, + tasksDir: string, + taskId: string, + unitId: string, + postExecutionChecks: PostExecutionCheckJSON[], + retryAttempt?: number, + maxRetries?: number, +): void { + mkdirSync(tasksDir, { recursive: true }); + + const evidence: EvidenceJSON = { + schemaVersion: 1, + taskId, + unitId: unitId ?? taskId, + timestamp: result.timestamp, + passed: result.passed, + discoverySource: result.discoverySource, + checks: result.checks.map((check) => ({ + command: check.command, + exitCode: check.exitCode, + durationMs: check.durationMs, + verdict: check.exitCode === 0 ? "pass" : "fail", + })), + ...(retryAttempt !== undefined ? { retryAttempt } : {}), + ...(maxRetries !== undefined ? { maxRetries } : {}), + postExecutionChecks, + }; + + if (result.runtimeErrors && result.runtimeErrors.length > 0) { + evidence.runtimeErrors = result.runtimeErrors.map(e => ({ + source: e.source, + severity: e.severity, + message: e.message, + blocking: e.blocking, + })); + } + + if (result.auditWarnings && result.auditWarnings.length > 0) { + evidence.auditWarnings = result.auditWarnings.map(w => ({ + name: w.name, + severity: w.severity, + title: w.title, + url: w.url, + fixAvailable: w.fixAvailable, + })); + } + + const filePath = join(tasksDir, `${taskId}-VERIFY.json`); + writeFileSync(filePath, JSON.stringify(evidence, null, 2) + "\n", "utf-8"); +} diff --git a/src/resources/extensions/gsd/auto-worktree.ts b/src/resources/extensions/gsd/auto-worktree.ts index c07c7d4e5..a0e14c663 100644 --- a/src/resources/extensions/gsd/auto-worktree.ts +++ b/src/resources/extensions/gsd/auto-worktree.ts @@ -15,6 +15,7 @@ import { realpathSync, rmSync, unlinkSync, + statSync, lstatSync as lstatSyncFn, } from "node:fs"; import { isAbsolute, join, sep as pathSep } from "node:path"; @@ -35,6 +36,7 @@ import { removeWorktree, resolveGitDir, worktreePath, + isInsideWorktreesDir, } from "./worktree-manager.js"; import { detectWorktreeName, @@ -43,7 +45,7 @@ import { } from "./worktree.js"; import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js"; import { debugLog } from "./debug-logger.js"; -import { logWarning } from "./workflow-logger.js"; +import { logWarning, logError } from "./workflow-logger.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; import { nativeGetCurrentBranch, @@ -62,6 +64,7 @@ import { nativeDiffNumstat, nativeUpdateRef, nativeIsAncestor, + nativeMergeAbort, } from "./native-git-bridge.js"; const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd"); @@ -84,6 +87,7 @@ const ROOT_STATE_FILES = [ "QUEUE.md", "completed-units.json", "metrics.json", + "mcp.json", // NOTE: project preferences are intentionally NOT in ROOT_STATE_FILES. // Forward-sync (main → worktree) is handled explicitly in syncGsdStateToWorktree(). // Back-sync (worktree → main) must NEVER overwrite the project root's copy @@ -97,11 +101,76 @@ const ROOT_STATE_FILES = [ function isSamePath(a: string, b: string): boolean { try { return realpathSync(a) === realpathSync(b); - } catch { + } catch (e) { + logWarning("worktree", `isSamePath failed: ${(e as Error).message}`); return false; } } +// ─── ASSESSMENT Force-Sync Helper (#2821) ───────────────────────────────── + +/** Regex matching YAML frontmatter `verdict:` field. */ +const VERDICT_RE = /verdict:\s*[\w-]+/i; + +/** + * Walk a milestone directory and force-overwrite ASSESSMENT files in the + * destination when the source copy contains a `verdict:` field. + * + * This is the targeted fix for the UAT stuck-loop (#2821): the main + * safeCopyRecursive uses force:false to protect worktree-authoritative + * files (#1886), but ASSESSMENT files written by run-uat must be + * forward-synced when the project root has a verdict. Without this, + * the worktree retains a stale FAIL or missing ASSESSMENT and + * checkNeedsRunUat re-dispatches run-uat indefinitely. + * + * Only overwrites when the source has a verdict — never clobbers a + * worktree ASSESSMENT with a verdictless project-root copy. + */ +function forceOverwriteAssessmentsWithVerdict( + srcMilestoneDir: string, + dstMilestoneDir: string, +): void { + if (!existsSync(srcMilestoneDir)) return; + + // Walk slices// looking for *-ASSESSMENT.md files + const slicesDir = join(srcMilestoneDir, "slices"); + if (!existsSync(slicesDir)) return; + + try { + for (const sliceEntry of readdirSync(slicesDir, { withFileTypes: true })) { + if (!sliceEntry.isDirectory()) continue; + const srcSliceDir = join(slicesDir, sliceEntry.name); + const dstSliceDir = join(dstMilestoneDir, "slices", sliceEntry.name); + + try { + for (const fileEntry of readdirSync(srcSliceDir, { withFileTypes: true })) { + if (!fileEntry.isFile()) continue; + if (!fileEntry.name.endsWith("-ASSESSMENT.md")) continue; + + const srcFile = join(srcSliceDir, fileEntry.name); + try { + const srcContent = readFileSync(srcFile, "utf-8"); + if (!VERDICT_RE.test(srcContent)) continue; // no verdict in source — skip + + // Source has a verdict — force-copy into worktree + mkdirSync(dstSliceDir, { recursive: true }); + safeCopy(srcFile, join(dstSliceDir, fileEntry.name), { force: true }); + } catch (err) { + /* non-fatal per file */ + logWarning("worktree", `assessment force-copy failed: ${err instanceof Error ? err.message : String(err)}`); + } + } + } catch (err) { + /* non-fatal per slice */ + logWarning("worktree", `assessment slice scan failed: ${err instanceof Error ? err.message : String(err)}`); + } + } + } catch (err) { + /* non-fatal */ + logWarning("worktree", `assessment sync failed: ${err instanceof Error ? err.message : String(err)}`); + } +} + // ─── Module State ────────────────────────────────────────────────────────── /** Original project root before chdir into auto-worktree. */ @@ -118,8 +187,11 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void for (const file of transientFiles) { try { unlinkSync(file); - } catch { - /* non-fatal — file may not exist */ + } catch (err) { + // ENOENT is expected — file may not exist (#3597) + if ((err as NodeJS.ErrnoException).code !== "ENOENT") { + logWarning("worktree", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`); + } } } @@ -147,14 +219,19 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void for (const f of untrackedOutput.split("\n").filter(Boolean)) { try { unlinkSync(join(basePath, f)); - } catch { - /* non-fatal */ + } catch (err) { + // ENOENT/EISDIR are expected for already-removed or directory entries (#3597) + const code = (err as NodeJS.ErrnoException).code; + if (code !== "ENOENT" && code !== "EISDIR") { + logWarning("worktree", `untracked file unlink failed: ${err instanceof Error ? err.message : String(err)}`); + } } } } } - } catch { + } catch (err) { /* non-fatal — git command may fail if not in repo */ + logWarning("worktree", `untracked file cleanup failed: ${err instanceof Error ? err.message : String(err)}`); } } } @@ -214,6 +291,19 @@ export function syncProjectRootToWorktree( { force: false }, ); + // Force-sync ASSESSMENT files that have a verdict from project root (#2821). + // The additive-only copy above preserves worktree-authoritative files, but + // ASSESSMENT files are special: after run-uat writes a verdict and post-unit + // syncs it to the project root, the worktree may retain a stale copy (e.g. + // verdict:fail while the project root has verdict:pass from a retry). On + // session resume the DB is rebuilt from disk, and if the stale ASSESSMENT + // persists, checkNeedsRunUat finds no passing verdict → re-dispatches + // run-uat indefinitely (stuck-loop ×9). + forceOverwriteAssessmentsWithVerdict( + join(prGsd, "milestones", milestoneId), + join(wtGsd, "milestones", milestoneId), + ); + // Forward-sync completed-units.json from project root to worktree. // Project root is authoritative for completion state after crash recovery; // without this, the worktree re-dispatches already-completed units (#1886). @@ -223,15 +313,40 @@ export function syncProjectRootToWorktree( { force: true }, ); - // Delete worktree gsd.db so it rebuilds from the freshly synced files. - // Stale DB rows are the root cause of the infinite skip loop (#853). + // Delete worktree gsd.db ONLY if it is empty (0 bytes). + // An empty DB is stale/corrupt and should be rebuilt (#853). + // A non-empty DB was populated by gsd-migrate on respawn and must be + // preserved — deleting it truncates the file to 0 bytes when + // openDatabase re-creates it, causing "no such table" failures (#2815). try { const wtDb = join(wtGsd, "gsd.db"); + let deleteSidecars = false; if (existsSync(wtDb)) { - unlinkSync(wtDb); + const size = statSync(wtDb).size; + if (size === 0) { + unlinkSync(wtDb); + deleteSidecars = true; + } + } else { + // Main DB already missing — sidecars are orphaned from a previous + // partial cleanup and must still be removed. + deleteSidecars = true; } - } catch { + // Always clean up WAL/SHM sidecar files when the main DB was deleted + // or is already missing. Orphaned WAL/SHM files cause SQLite WAL + // recovery on next open, which triggers a CPU spin on Node 24's + // node:sqlite DatabaseSync implementation (#2478). + if (deleteSidecars) { + for (const suffix of ["-wal", "-shm"]) { + const f = wtDb + suffix; + if (existsSync(f)) { + unlinkSync(f); + } + } + } + } catch (err) { /* non-fatal */ + logWarning("worktree", `worktree DB cleanup failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -300,7 +415,8 @@ export function readResourceVersion(): string | null { return typeof manifest?.gsdVersion === "string" ? manifest.gsdVersion : null; - } catch { + } catch (e) { + logWarning("worktree", `readResourceVersion failed: ${(e as Error).message}`); return null; } } @@ -366,8 +482,9 @@ export function escapeStaleWorktree(base: string): string { try { process.chdir(projectRoot); - } catch { + } catch (e) { // If chdir fails, return the original — caller will handle errors downstream + logWarning("worktree", `escapeStaleWorktree chdir failed: ${(e as Error).message}`); return base; } return projectRoot; @@ -397,13 +514,15 @@ export function cleanStaleRuntimeUnits( try { unlinkSync(join(runtimeUnitsDir, file)); cleaned++; - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `stale runtime unit unlink failed (${file}): ${err instanceof Error ? err.message : String(err)}`); } } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `stale runtime unit cleanup failed: ${err instanceof Error ? err.message : String(err)}`); } return cleaned; } @@ -445,8 +564,9 @@ export function syncGsdStateToWorktree( try { cpSync(src, dst); synced.push(f); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `file copy failed (${f}): ${err instanceof Error ? err.message : String(err)}`); } } } @@ -465,8 +585,9 @@ export function syncGsdStateToWorktree( try { cpSync(src, dst); synced.push(file); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `preferences copy failed (${file}): ${err instanceof Error ? err.message : String(err)}`); } break; } @@ -495,8 +616,9 @@ export function syncGsdStateToWorktree( try { cpSync(srcDir, dstDir, { recursive: true }); synced.push(`milestones/${mid}/`); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`); } } else { // Milestone directory exists but may be missing files (stale snapshot). @@ -515,8 +637,9 @@ export function syncGsdStateToWorktree( cpSync(srcFile, dstFile); synced.push(`milestones/${mid}/${f}`); } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone file copy failed (${mid}/${f}): ${err instanceof Error ? err.message : String(err)}`); } } } @@ -528,8 +651,9 @@ export function syncGsdStateToWorktree( try { cpSync(srcSlicesDir, dstSlicesDir, { recursive: true }); synced.push(`milestones/${mid}/slices/`); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `slices copy failed (${mid}): ${err instanceof Error ? err.message : String(err)}`); } } else if (existsSync(srcSlicesDir) && existsSync(dstSlicesDir)) { // Both exist — sync missing slice directories @@ -545,19 +669,22 @@ export function syncGsdStateToWorktree( try { cpSync(srcSlice, dstSlice, { recursive: true }); synced.push(`milestones/${mid}/slices/${sid}/`); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `slice copy failed (${mid}/${sid}): ${err instanceof Error ? err.message : String(err)}`); } } } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone file sync failed: ${err instanceof Error ? err.message : String(err)}`); } } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -609,8 +736,9 @@ export function syncWorktreeStateBack( try { reconcileWorktreeDb(mainDb, wtLocalDb); synced.push("gsd.db (pre-upgrade reconcile)"); - } catch { + } catch (err) { // Non-fatal — file sync below is the fallback + logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -627,8 +755,9 @@ export function syncWorktreeStateBack( try { cpSync(src, dst, { force: true }); synced.push(f); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `state file copy-back failed (${f}): ${err instanceof Error ? err.message : String(err)}`); } } } @@ -646,10 +775,14 @@ export function syncWorktreeStateBack( .map((d) => d.name); for (const mid of wtMilestones) { + // Skip the current milestone being merged — its files are already in the + // milestone branch and would conflict with the squash merge (#3641). + if (mid === milestoneId) continue; syncMilestoneDir(wtGsd, mainGsd, mid, synced); } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone sync-back failed: ${err instanceof Error ? err.message : String(err)}`); } return { synced }; @@ -673,12 +806,14 @@ function syncDirFiles( try { cpSync(join(srcDir, entry.name), join(dstDir, entry.name), { force: true }); synced.push(`${prefix}${entry.name}`); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `file copy failed (${prefix}${entry.name}): ${err instanceof Error ? err.message : String(err)}`); } } - } catch { + } catch (err) { /* non-fatal — srcDir may not be readable */ + logWarning("worktree", `directory read failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -721,8 +856,9 @@ function syncMilestoneDir( syncDirFiles(wtTasksDir, mainTasksDir, isMd, synced, `milestones/${mid}/slices/${sid}/tasks/`); } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `milestone slice sync failed (${mid}): ${err instanceof Error ? err.message : String(err)}`); } } // ─── Worktree Post-Create Hook (#597) ──────────────────────────────────────── @@ -754,7 +890,9 @@ export function runWorktreePostCreateHook( return `Worktree post-create hook not found: ${resolved}`; } if (process.platform === "win32") { - try { resolved = realpathSync.native(resolved); } catch { /* keep original */ } + try { resolved = realpathSync.native(resolved); } catch (err) { /* keep original */ + logWarning("worktree", `realpath failed: ${err instanceof Error ? err.message : String(err)}`); + } } try { @@ -838,8 +976,9 @@ function reconcilePlanCheckboxes( results.push(full); } } - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `walkMd directory read failed: ${err instanceof Error ? err.message : String(err)}`); } return results; } @@ -854,7 +993,8 @@ function reconcilePlanCheckboxes( try { srcContent = readFileSync(srcFile, "utf-8"); dstContent = readFileSync(dstFile, "utf-8"); - } catch { + } catch (e) { + logWarning("worktree", `reconcilePlanCheckboxes read failed: ${(e as Error).message}`); continue; } @@ -889,8 +1029,9 @@ function reconcilePlanCheckboxes( if (changed) { try { atomicWriteSync(dstFile, updated, "utf-8"); - } catch { + } catch (err) { /* non-fatal */ + logWarning("worktree", `plan checkbox reconcile write failed: ${err instanceof Error ? err.message : String(err)}`); } } } @@ -916,12 +1057,20 @@ export function createAutoWorktree( reuseExistingBranch: true, }); } else { - // Fresh start — create branch from integration branch + // Fresh start — create branch from integration branch. + // Use the same 3-tier fallback as mergeMilestoneToMain (#3461): + // 1. META.json integration branch (explicit per-milestone override) + // 2. git.main_branch preference (user's configured working branch) + // 3. nativeDetectMainBranch (origin/HEAD auto-detection) + // Without tier 2, projects with main_branch=dev but origin/HEAD→master + // would fork worktrees from the wrong (stale) branch. const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined; + const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git; + const startPoint = integrationBranch ?? gitPrefs?.main_branch ?? undefined; info = createWorktree(basePath, milestoneId, { branch, - startPoint: integrationBranch, + startPoint, }); } @@ -988,6 +1137,7 @@ function copyPlanningArtifacts(srcBase: string, wtPath: string): void { const srcGsd = join(srcBase, ".gsd"); const dstGsd = join(wtPath, ".gsd"); if (!existsSync(srcGsd)) return; + if (isSamePath(srcGsd, dstGsd)) return; // Copy milestones/ directory (planning files, roadmaps, plans, research) safeCopyRecursive(join(srcGsd, "milestones"), join(dstGsd, "milestones"), { @@ -1004,6 +1154,7 @@ function copyPlanningArtifacts(srcBase: string, wtPath: string): void { "STATE.md", "KNOWLEDGE.md", "OVERRIDES.md", + "mcp.json", ]) { safeCopy(join(srcGsd, file), join(dstGsd, file), { force: true }); } @@ -1071,11 +1222,19 @@ export function teardownAutoWorktree( `Remove it manually with: rm -rf "${wtDir.replaceAll("\\", "/")}"`, { worktree: milestoneId }, ); - // Attempt a direct filesystem removal as a fallback - try { - rmSync(wtDir, { recursive: true, force: true }); - } catch { - // Non-fatal — the warning above tells the user how to clean up + // Attempt a direct filesystem removal as a fallback — but ONLY if the + // path is safely inside .gsd/worktrees/ to prevent #2365 data loss. + if (isInsideWorktreesDir(originalBasePath, wtDir)) { + try { + rmSync(wtDir, { recursive: true, force: true }); + } catch (err) { + // Non-fatal — the warning above tells the user how to clean up + logWarning("worktree", `worktree directory removal failed: ${err instanceof Error ? err.message : String(err)}`); + } + } else { + console.error( + `[GSD] REFUSING fallback rmSync — path is outside .gsd/worktrees/: ${wtDir}`, + ); } } } @@ -1116,7 +1275,8 @@ export function getAutoWorktreePath( try { const content = readFileSync(gitPath, "utf8").trim(); if (!content.startsWith("gitdir: ")) return null; - } catch { + } catch (e) { + logWarning("worktree", `getAutoWorktreePath .git read failed: ${(e as Error).message}`); return null; } @@ -1261,8 +1421,31 @@ export function mergeMilestoneToMain( const worktreeCwd = process.cwd(); const milestoneBranch = autoWorktreeBranch(milestoneId); - // 1. Auto-commit dirty state in worktree before leaving - autoCommitDirtyState(worktreeCwd); + // 1. Auto-commit dirty state before leaving. + // Guard: when we entered through an auto-worktree (originalBase is set), + // only auto-commit when cwd is on the milestone branch. In parallel mode, + // cwd may be on the integration branch after a prior merge's + // MergeConflictError left cwd unrestored. Auto-committing on the + // integration branch captures dirty files from OTHER milestones under a + // misleading commit message, contaminating the main branch (#2929). + // + // When originalBase is null (branch mode, no worktree), autoCommitDirtyState + // runs unconditionally — the caller is responsible for cwd placement. + { + let shouldAutoCommit = true; + if (originalBase !== null) { + try { + const currentBranch = nativeGetCurrentBranch(worktreeCwd); + shouldAutoCommit = currentBranch === milestoneBranch; + } catch { + // If we can't determine the branch, skip the auto-commit to be safe + shouldAutoCommit = false; + } + } + if (shouldAutoCommit) { + autoCommitDirtyState(worktreeCwd); + } + } // Reconcile worktree DB into main DB before leaving worktree context. // Skip when both paths resolve to the same physical file (shared WAL / @@ -1275,8 +1458,9 @@ export function mergeMilestoneToMain( if (!isSamePath(worktreeDbPath, mainDbPath)) { reconcileWorktreeDb(mainDbPath, worktreeDbPath); } - } catch { + } catch (err) { /* non-fatal */ + logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -1309,8 +1493,13 @@ export function mergeMilestoneToMain( originalBasePath_, milestoneId, ); + // Validate prefs.main_branch exists before using it — a stale preference + // (e.g. "master" when repo uses "main") causes merge failure (#3589). + const validatedPrefBranch = prefs.main_branch && nativeBranchExists(originalBasePath_, prefs.main_branch) + ? prefs.main_branch + : undefined; const mainBranch = - integrationBranch ?? prefs.main_branch ?? nativeDetectMainBranch(originalBasePath_); + integrationBranch ?? validatedPrefBranch ?? nativeDetectMainBranch(originalBasePath_); // Remove transient project-root state files before any branch or merge // operation. Untracked milestone metadata can otherwise block squash merges. @@ -1414,16 +1603,94 @@ export function mergeMilestoneToMain( encoding: "utf-8", }).trim(); if (status) { + // Use --include-untracked to stash untracked files that would block + // the squash merge, but EXCLUDE .gsd/milestones/ (#2505). + // --include-untracked without exclusion sweeps queued milestone + // CONTEXT files into the stash. If stash pop later fails, those files + // are permanently trapped in the stash entry and lost on the next + // stash push or drop. execFileSync( "git", - ["stash", "push", "--include-untracked", "-m", `gsd: pre-merge stash for ${milestoneId}`], + [ + "stash", "push", "--include-untracked", + "-m", `gsd: pre-merge stash for ${milestoneId}`, + "--", ":(exclude).gsd/milestones", + ], { cwd: originalBasePath_, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }, ); stashed = true; } - } catch { + } catch (err) { // Stash failure is non-fatal — proceed without stash and let the merge // report the dirty tree if it fails. + logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`); + } + + // 7a. Shelter queued milestone directories before the squash merge (#2505). + // The milestone branch may contain copies of queued milestone dirs (via + // copyPlanningArtifacts), so `git merge --squash` rejects when those same + // files exist as untracked in the working tree. Temporarily move them to + // a backup location, then restore after the merge+commit. + const milestonesDir = join(gsdRoot(originalBasePath_), "milestones"); + const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter"); + const shelteredDirs: string[] = []; + + // Helper: restore sheltered milestone directories (#2505). + // Called on both success and error paths to ensure queued CONTEXT files + // are never permanently lost. + const restoreShelter = (): void => { + if (shelteredDirs.length === 0) return; + for (const dirName of shelteredDirs) { + try { + mkdirSync(milestonesDir, { recursive: true }); + cpSync(join(shelterDir, dirName), join(milestonesDir, dirName), { recursive: true, force: true }); + } catch (err) { /* best-effort */ + logError("worktree", `shelter restore failed: ${err instanceof Error ? err.message : String(err)}`); + } + } + try { rmSync(shelterDir, { recursive: true, force: true }); } catch (err) { /* best-effort */ + logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`); + } + }; + + try { + if (existsSync(milestonesDir)) { + const entries = readdirSync(milestonesDir, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isDirectory()) continue; + // Only shelter directories that do NOT belong to the milestone being merged + if (entry.name === milestoneId) continue; + const srcDir = join(milestonesDir, entry.name); + const dstDir = join(shelterDir, entry.name); + try { + mkdirSync(shelterDir, { recursive: true }); + cpSync(srcDir, dstDir, { recursive: true, force: true }); + rmSync(srcDir, { recursive: true, force: true }); + shelteredDirs.push(entry.name); + } catch (err) { + // Non-fatal — if shelter fails, the merge may still succeed + logWarning("worktree", `milestone shelter failed (${entry.name}): ${err instanceof Error ? err.message : String(err)}`); + } + } + } + } catch (err) { + // Non-fatal — proceed with merge; untracked files may block it + logWarning("worktree", `milestone shelter operation failed: ${err instanceof Error ? err.message : String(err)}`); + } + + // 7b. Clean up stale merge state before attempting squash merge (#2912). + // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path, + // or interrupted operation) causes `git merge --squash` to refuse with + // "fatal: You have not concluded your merge (MERGE_HEAD exists)". + // Defensively remove merge artifacts before starting. + try { + const gitDir_ = resolveGitDir(originalBasePath_); + for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) { + const p = join(gitDir_, f); + if (existsSync(p)) unlinkSync(p); + } + } catch (err) { /* best-effort */ + logError("worktree", `merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`); } // 8. Squash merge — auto-resolve .gsd/ state file conflicts (#530) @@ -1434,6 +1701,18 @@ export function mergeMilestoneToMain( // untracked .gsd/ files left by syncStateToProjectRoot). Preserve the // milestone branch so commits are not lost. if (mergeResult.conflicts.includes("__dirty_working_tree__")) { + // Defensively clean merge state — the native path may leave MERGE_HEAD + // even when the merge is rejected (#2912). + try { + const gitDir_ = resolveGitDir(originalBasePath_); + for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) { + const p = join(gitDir_, f); + if (existsSync(p)) unlinkSync(p); + } + } catch (err) { /* best-effort */ + logError("worktree", `merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`); + } + // Pop stash before throwing so local work is not lost. if (stashed) { try { @@ -1442,8 +1721,11 @@ export function mergeMilestoneToMain( stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8", }); - } catch { /* stash pop conflict is non-fatal */ } + } catch (err) { /* stash pop conflict is non-fatal */ + logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`); + } } + restoreShelter(); // Restore cwd so the caller is not stranded on the integration branch process.chdir(previousCwd); // Surface the actual dirty filenames from git stderr instead of @@ -1480,9 +1762,10 @@ export function mergeMilestoneToMain( try { nativeCheckoutTheirs(originalBasePath_, [safeFile]); nativeAddPaths(originalBasePath_, [safeFile]); - } catch { + } catch (e) { // If checkout --theirs fails, try removing the file from the merge // (it's a runtime file that shouldn't be committed anyway) + logWarning("worktree", `checkout --theirs failed for ${safeFile}, removing: ${(e as Error).message}`); nativeRmForce(originalBasePath_, [safeFile]); } } @@ -1490,6 +1773,22 @@ export function mergeMilestoneToMain( // If there are still real code conflicts, escalate if (codeConflicts.length > 0) { + // Abort merge state so MERGE_HEAD is not left on disk (#2912). + // libgit2's merge creates MERGE_HEAD even for squash merges; if left + // dangling, subsequent merges fail and doctor reports corrupt state. + try { nativeMergeAbort(originalBasePath_); } catch (err) { /* best-effort */ + logError("worktree", `git merge-abort failed: ${err instanceof Error ? err.message : String(err)}`); + } + try { + const gitDir_ = resolveGitDir(originalBasePath_); + for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) { + const p = join(gitDir_, f); + if (existsSync(p)) unlinkSync(p); + } + } catch (err) { /* best-effort */ + logError("worktree", `merge state file cleanup failed: ${err instanceof Error ? err.message : String(err)}`); + } + // Pop stash before throwing so local work is not lost (#2151). if (stashed) { try { @@ -1498,8 +1797,17 @@ export function mergeMilestoneToMain( stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8", }); - } catch { /* stash pop conflict is non-fatal */ } + } catch (err) { /* stash pop conflict is non-fatal */ + logWarning("worktree", `git stash pop failed: ${err instanceof Error ? err.message : String(err)}`); + } } + restoreShelter(); + // Restore cwd so the caller is not stranded on the integration branch. + // Without this, the next mergeMilestoneToMain call in a parallel merge + // sequence uses process.cwd() (now the project root) as worktreeCwd, + // causing autoCommitDirtyState to commit unrelated milestone files to + // the integration branch (#2929). + process.chdir(previousCwd); throw new MergeConflictError( codeConflicts, "squash", @@ -1515,15 +1823,21 @@ export function mergeMilestoneToMain( const commitResult = nativeCommit(originalBasePath_, commitMessage); const nothingToCommit = commitResult === null; - // 9a. Clean up SQUASH_MSG left by git merge --squash (#1853). + // 9a. Clean up merge state files left by git merge --squash (#1853, #2912). // git only removes SQUASH_MSG when the commit reads it directly (plain // `git commit`). nativeCommit uses `-F -` (stdin) or libgit2, neither - // of which trigger git's SQUASH_MSG cleanup. If left on disk, doctor - // reports `corrupt_merge_state` on every subsequent run. + // of which trigger git's SQUASH_MSG cleanup. MERGE_HEAD is created by + // libgit2's merge even in squash mode and is not removed by nativeCommit. + // If left on disk, doctor reports `corrupt_merge_state` on every subsequent run. try { - const squashMsgPath = join(resolveGitDir(originalBasePath_), "SQUASH_MSG"); - if (existsSync(squashMsgPath)) unlinkSync(squashMsgPath); - } catch { /* best-effort */ } + const gitDir_ = resolveGitDir(originalBasePath_); + for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) { + const p = join(gitDir_, f); + if (existsSync(p)) unlinkSync(p); + } + } catch (err) { /* best-effort */ + logError("worktree", `post-commit merge state cleanup failed: ${err instanceof Error ? err.message : String(err)}`); + } // 9a-ii. Restore stashed files now that the merge+commit is complete (#2151). // Pop after commit so stashed changes do not interfere with the squash merge @@ -1536,7 +1850,8 @@ export function mergeMilestoneToMain( stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8", }); - } catch { + } catch (e) { + logWarning("worktree", `git stash pop failed, attempting conflict resolution: ${(e as Error).message}`); // Stash pop after squash merge can conflict on .gsd/ state files that // diverged between branches. Left unresolved, these UU entries block // every subsequent merge. Auto-resolve them the same way we handle @@ -1556,8 +1871,9 @@ export function mergeMilestoneToMain( encoding: "utf-8", }); nativeAddPaths(originalBasePath_, [f]); - } catch { + } catch (e) { // Last resort: remove the conflicted state file + logWarning("worktree", `checkout HEAD failed for ${f}, removing: ${(e as Error).message}`); nativeRmForce(originalBasePath_, [f]); } } @@ -1571,7 +1887,9 @@ export function mergeMilestoneToMain( stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8", }); - } catch { /* stash may already be consumed */ } + } catch (err) { /* stash may already be consumed */ + logWarning("worktree", `git stash drop failed: ${err instanceof Error ? err.message : String(err)}`); + } } else { // Non-.gsd conflicts remain — leave stash for manual resolution logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", { @@ -1581,6 +1899,9 @@ export function mergeMilestoneToMain( } } + // 9a-iii. Restore sheltered queued milestone directories (#2505). + restoreShelter(); + // 9b. Safety check (#1792): if nothing was committed, verify the milestone // work is already on the integration branch before allowing teardown. // Compare only non-.gsd/ paths — .gsd/ state files diverge normally and @@ -1621,8 +1942,9 @@ export function mergeMilestoneToMain( codeFilesChanged = mergedFiles.some( (entry) => !entry.path.startsWith(".gsd/"), ); - } catch { + } catch (e) { // If HEAD~1 doesn't exist (first commit), assume code was changed + logWarning("worktree", `diff numstat failed (assuming code changed): ${(e as Error).message}`); codeFilesChanged = true; } } @@ -1638,8 +1960,9 @@ export function mergeMilestoneToMain( encoding: "utf-8", }); pushed = true; - } catch { + } catch (err) { // Push failure is non-fatal + logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -1668,8 +1991,9 @@ export function mergeMilestoneToMain( encoding: "utf-8", }); prCreated = true; - } catch { + } catch (err) { // PR creation failure is non-fatal — gh may not be installed or authenticated + logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`); } } @@ -1681,23 +2005,38 @@ export function mergeMilestoneToMain( // changes (e.g. nativeHasChanges cache returned stale false, or auto-commit // silently failed), force one final commit so code is not destroyed by // `git worktree remove --force`. + // + // Guard: only run when worktreeCwd is on the milestone branch (#2929). + // In parallel mode or branch-mode merges, worktreeCwd may be the project + // root on the integration branch. Committing dirty state there would + // capture unrelated files from other milestones. if (existsSync(worktreeCwd)) { + let preTeardownBranch: string | null = null; try { - const dirtyCheck = nativeWorkingTreeStatus(worktreeCwd); - if (dirtyCheck) { + preTeardownBranch = nativeGetCurrentBranch(worktreeCwd); + } catch (err) { + debugLog("mergeMilestoneToMain", { phase: "pre-teardown-branch-detect-failed", error: String(err) }); + } + const isOnMilestoneBranch = preTeardownBranch === milestoneBranch; + + if (isOnMilestoneBranch) { + try { + const dirtyCheck = nativeWorkingTreeStatus(worktreeCwd); + if (dirtyCheck) { + debugLog("mergeMilestoneToMain", { + phase: "pre-teardown-dirty", + worktreeCwd, + status: dirtyCheck.slice(0, 200), + }); + nativeAddAllWithExclusions(worktreeCwd, RUNTIME_EXCLUSION_PATHS); + nativeCommit(worktreeCwd, "chore: pre-teardown auto-commit of uncommitted worktree changes"); + } + } catch (e) { debugLog("mergeMilestoneToMain", { - phase: "pre-teardown-dirty", - worktreeCwd, - status: dirtyCheck.slice(0, 200), + phase: "pre-teardown-commit-error", + error: String(e), }); - nativeAddAllWithExclusions(worktreeCwd, RUNTIME_EXCLUSION_PATHS); - nativeCommit(worktreeCwd, "chore: pre-teardown auto-commit of uncommitted worktree changes"); } - } catch (e) { - debugLog("mergeMilestoneToMain", { - phase: "pre-teardown-commit-error", - error: String(e), - }); } } @@ -1707,15 +2046,17 @@ export function mergeMilestoneToMain( branch: null as unknown as string, deleteBranch: false, }); - } catch { + } catch (err) { // Best-effort -- worktree dir may already be gone + logWarning("worktree", `worktree removal failed: ${err instanceof Error ? err.message : String(err)}`); } // 13. Delete milestone branch (after worktree removal so ref is unlocked) try { nativeBranchDelete(originalBasePath_, milestoneBranch); - } catch { + } catch (err) { // Best-effort + logWarning("worktree", `git branch-delete failed: ${err instanceof Error ? err.message : String(err)}`); } // 14. Clear module state diff --git a/src/resources/extensions/gsd/auto.ts b/src/resources/extensions/gsd/auto.ts index 2fc826095..1b8d4fd47 100644 --- a/src/resources/extensions/gsd/auto.ts +++ b/src/resources/extensions/gsd/auto.ts @@ -19,6 +19,11 @@ import type { import { deriveState } from "./state.js"; import { parseUnitId } from "./unit-id.js"; import type { GSDState } from "./types.js"; +import { + assessInterruptedSession, + readPausedSessionMetadata, + type InterruptedSessionAssessment, +} from "./interrupted-session.js"; import { getManifestStatus } from "./files.js"; export { inlinePriorMilestoneSummary } from "./files.js"; import { collectSecretsFromManifest } from "../get-secrets-from-user.js"; @@ -46,6 +51,7 @@ import { clearLock, readCrashLock, isLockProcessAlive, + formatCrashInfo, } from "./crash-recovery.js"; import { acquireSessionLock, @@ -75,6 +81,8 @@ import { getOldestInFlightToolStart, hasInteractiveToolInFlight, clearInFlightTools, + isToolInvocationError, + isQueuedUserMessageSkip, } from "./auto-tool-tracking.js"; import { closeoutUnit } from "./auto-unit-closeout.js"; import { recoverTimedOutUnit } from "./auto-timeout-recovery.js"; @@ -115,8 +123,10 @@ import { formatCost, formatTokenCount, } from "./metrics.js"; -import { setLogBasePath } from "./workflow-logger.js"; +import { setLogBasePath, logWarning, logError } from "./workflow-logger.js"; +import { homedir } from "node:os"; import { join } from "node:path"; +import { pathToFileURL } from "node:url"; import { readFileSync, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs"; import { atomicWriteSync } from "./atomic-write.js"; import { @@ -185,8 +195,11 @@ import { postUnitPreVerification, postUnitPostVerification, } from "./auto-post-unit.js"; -import { bootstrapAutoSession, type BootstrapDeps } from "./auto-start.js"; +import { bootstrapAutoSession, openProjectDbIfPresent, type BootstrapDeps } from "./auto-start.js"; import { autoLoop, resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSessionSwitchInFlight, type LoopDeps, type ErrorContext } from "./auto-loop.js"; +// Slice-level parallelism (#2340) +import { getEligibleSlices } from "./slice-parallel-eligibility.js"; +import { startSliceParallel } from "./slice-parallel-orchestrator.js"; import { WorktreeResolver, type WorktreeResolverDeps, @@ -236,6 +249,29 @@ const s = new AutoSession(); /** Throttle STATE.md rebuilds — at most once per 30 seconds */ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000; +function captureProjectRootEnv(projectRoot: string): void { + if (!s.projectRootEnvCaptured) { + s.hadProjectRootEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_PROJECT_ROOT"); + s.previousProjectRootEnv = process.env.GSD_PROJECT_ROOT ?? null; + s.projectRootEnvCaptured = true; + } + process.env.GSD_PROJECT_ROOT = projectRoot; +} + +function restoreProjectRootEnv(): void { + if (!s.projectRootEnvCaptured) return; + + if (s.hadProjectRootEnv && s.previousProjectRootEnv !== null) { + process.env.GSD_PROJECT_ROOT = s.previousProjectRootEnv; + } else { + delete process.env.GSD_PROJECT_ROOT; + } + + s.previousProjectRootEnv = null; + s.hadProjectRootEnv = false; + s.projectRootEnvCaptured = false; +} + export function shouldUseWorktreeIsolation(): boolean { const prefs = loadEffectiveGSDPreferences()?.preferences?.git; if (prefs?.isolation === "worktree") return true; @@ -316,8 +352,9 @@ export function getAutoDashboardData(): AutoDashboardData { if (s.basePath) { pendingCaptureCount = countPendingCaptures(s.basePath); } - } catch { + } catch (err) { // Non-fatal — captures module may not be loaded + logWarning("engine", `capture count failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } return { active: s.active, @@ -384,6 +421,19 @@ export function markToolEnd(toolCallId: string): void { _markToolEnd(toolCallId); } +/** + * Record a tool invocation error on the current session (#2883). + * Called from tool_execution_end when a GSD tool fails with isError. + * Only stores the error if it matches the tool-invocation-error pattern + * (malformed/truncated JSON), not normal business-logic errors. + */ +export function recordToolInvocationError(toolName: string, errorMsg: string): void { + if (!s.active) return; + if (isToolInvocationError(errorMsg) || isQueuedUserMessageSkip(errorMsg)) { + s.lastToolInvocationError = `${toolName}: ${errorMsg}`; + } +} + export function getOldestInFlightToolAgeMs(): number { return _getOldestInFlightToolAgeMs(); } @@ -523,6 +573,7 @@ function handleLostSessionLock( s.active = false; s.paused = false; clearUnitTimeout(); + restoreProjectRootEnv(); deregisterSigtermHandler(); clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences); const base = lockBase(); @@ -558,6 +609,7 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void { s.currentUnit = null; s.active = false; clearUnitTimeout(); + restoreProjectRootEnv(); // Clear crash lock and release session lock so the next `/gsd next` does // not see a stale lock with the current PID and treat it as a "remote" @@ -565,8 +617,9 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void { try { if (lockBase()) clearLock(lockBase()); if (lockBase()) releaseSessionLock(lockBase()); - } catch { + } catch (err) { /* best-effort — mirror stopAuto cleanup */ + logWarning("session", `lock cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } ctx.ui.setStatus("gsd-auto", undefined); @@ -578,8 +631,9 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void { s.basePath = s.originalBasePath; try { process.chdir(s.basePath); - } catch { + } catch (err) { /* best-effort */ + logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } } } @@ -603,6 +657,18 @@ export async function stopAuto( debugLog("stop-cleanup-locks", { error: e instanceof Error ? e.message : String(e) }); } + // ── Step 1b: Flush queued follow-up messages (#3512) ── + // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger + // extra LLM turns after stop. Flush them the same way run-unit.ts does. + try { + const cmdCtxAny = s.cmdCtx as Record | null; + if (typeof cmdCtxAny?.clearQueue === "function") { + (cmdCtxAny.clearQueue as () => unknown)(); + } + } catch (e) { + debugLog("stop-cleanup-queue", { error: e instanceof Error ? e.message : String(e) }); + } + // ── Step 2: Skill state ── try { clearSkillSnapshot(); @@ -651,8 +717,9 @@ export async function stopAuto( } else { milestoneComplete = true; } - } catch { + } catch (err) { // Non-fatal — fall through to preserveBranch path + logWarning("engine", `milestone summary check failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } if (milestoneComplete) { @@ -687,8 +754,9 @@ export async function stopAuto( s.basePath = s.originalBasePath; try { process.chdir(s.basePath); - } catch { + } catch (err) { /* best-effort */ + logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } } } catch (e) { @@ -760,7 +828,9 @@ export async function stopAuto( try { const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json"); if (existsSync(pausedPath)) unlinkSync(pausedPath); - } catch { /* non-fatal */ } + } catch (err) { /* non-fatal */ + logWarning("engine", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } // ── Step 13: Restore original model (before reset clears IDs) ── try { @@ -794,7 +864,9 @@ export async function stopAuto( const { closeBrowser } = await import("../browser-tools/lifecycle.js"); await closeBrowser(); } - } catch { /* non-fatal: browser-tools may not be loaded */ } + } catch (err) { /* non-fatal: browser-tools may not be loaded */ + logWarning("engine", `browser teardown failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } // External cleanup (not covered by session reset) clearInFlightTools(); @@ -807,6 +879,7 @@ export async function stopAuto( ctx?.ui.setStatus("gsd-auto", undefined); ctx?.ui.setWidget("gsd-progress", undefined); ctx?.ui.setFooter(undefined); + restoreProjectRootEnv(); // Reset all session state in one call s.reset(); @@ -825,6 +898,19 @@ export async function pauseAuto( ): Promise { if (!s.active) return; clearUnitTimeout(); + + // Flush queued follow-up messages (#3512). + // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger + // extra LLM turns after pause. Flush them the same way run-unit.ts does. + try { + const cmdCtxAny = s.cmdCtx as Record | null; + if (typeof cmdCtxAny?.clearQueue === "function") { + (cmdCtxAny.clearQueue as () => unknown)(); + } + } catch (e) { + debugLog("pause-cleanup-queue", { error: e instanceof Error ? e.message : String(e) }); + } + // Unblock any pending unit promise so the auto-loop is not orphaned. // Pass errorContext so runUnitPhase can distinguish user-initiated pause // from provider-error pause and avoid hard-stopping (#2762). @@ -842,8 +928,11 @@ export async function pauseAuto( stepMode: s.stepMode, pausedAt: new Date().toISOString(), sessionFile: s.pausedSessionFile, + unitType: s.currentUnit?.type ?? undefined, + unitId: s.currentUnit?.id ?? undefined, activeEngineId: s.activeEngineId, activeRunDir: s.activeRunDir, + autoStartTime: s.autoStartTime, }; const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime"); mkdirSync(runtimeDir, { recursive: true }); @@ -852,16 +941,18 @@ export async function pauseAuto( JSON.stringify(pausedMeta, null, 2), "utf-8", ); - } catch { + } catch (err) { // Non-fatal — resume will still work via full bootstrap, just without worktree context + logWarning("engine", `paused-session file write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } // Close out the current unit so its runtime record doesn't stay at "dispatched" if (s.currentUnit && ctx) { try { await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt); - } catch { + } catch (err) { // Non-fatal — best-effort closeout on pause + logWarning("engine", `unit closeout on pause failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } s.currentUnit = null; } @@ -879,6 +970,7 @@ export async function pauseAuto( s.active = false; s.paused = true; + restoreProjectRootEnv(); s.pendingVerificationRetry = null; s.verificationRetryCount.clear(); ctx?.ui.setStatus("gsd-auto", "paused"); @@ -1059,7 +1151,10 @@ export async function startAuto( pi: ExtensionAPI, base: string, verboseMode: boolean, - options?: { step?: boolean }, + options?: { + step?: boolean; + interrupted?: InterruptedSessionAssessment; + }, ): Promise { if (s.active) { debugLog("startAuto", { phase: "already-active", skipping: true }); @@ -1067,36 +1162,60 @@ export async function startAuto( } const requestedStepMode = options?.step ?? false; + const interruptedAssessment = options?.interrupted ?? null; // Escape stale worktree cwd from a previous milestone (#608). base = escapeStaleWorktree(base); + const freshStartAssessment = interruptedAssessment + ?? await assessInterruptedSession(base); + + if (freshStartAssessment.classification === "running") { + const pid = freshStartAssessment.lock?.pid; + ctx.ui.notify( + pid + ? `Another auto-mode session (PID ${pid}) appears to be running.\nStop it with \`kill ${pid}\` before starting a new session.` + : "Another auto-mode session appears to be running.", + "error", + ); + return; + } + // If resuming from paused state, just re-activate and dispatch next unit. // Check persisted paused-session first (#1383) — survives /exit. if (!s.paused) { try { + const meta = freshStartAssessment.pausedSession ?? readPausedSessionMetadata(base); const pausedPath = join(gsdRoot(base), "runtime", "paused-session.json"); - if (existsSync(pausedPath)) { - const meta = JSON.parse(readFileSync(pausedPath, "utf-8")); - if (meta.activeEngineId && meta.activeEngineId !== "dev") { - // Custom workflow resume — restore engine state - s.activeEngineId = meta.activeEngineId; - s.activeRunDir = meta.activeRunDir ?? null; - s.originalBasePath = meta.originalBasePath || base; - s.stepMode = meta.stepMode ?? requestedStepMode; - s.paused = true; - try { unlinkSync(pausedPath); } catch { /* non-fatal */ } - ctx.ui.notify( - `Resuming paused custom workflow${meta.activeRunDir ? ` (${meta.activeRunDir})` : ""}.`, - "info", + if (meta?.activeEngineId && meta.activeEngineId !== "dev") { + // Custom workflow resume — restore engine state + s.activeEngineId = meta.activeEngineId; + s.activeRunDir = meta.activeRunDir ?? null; + s.originalBasePath = meta.originalBasePath || base; + s.stepMode = meta.stepMode ?? requestedStepMode; + s.autoStartTime = meta.autoStartTime || Date.now(); + s.paused = true; + try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); } + ctx.ui.notify( + `Resuming paused custom workflow${meta.activeRunDir ? ` (${meta.activeRunDir})` : ""}.`, + "info", + ); + } else if (meta?.milestoneId) { + const shouldResumePausedSession = + freshStartAssessment.classification === "recoverable" + && ( + freshStartAssessment.hasResumableDiskState + || !!freshStartAssessment.recoveryPrompt + || !!freshStartAssessment.lock ); - } else if (meta.milestoneId) { + if (shouldResumePausedSession) { // Validate the milestone still exists and isn't already complete (#1664). const mDir = resolveMilestonePath(base, meta.milestoneId); const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY"); if (!mDir || summaryFile) { - // Stale milestone — clean up and fall through to fresh bootstrap - try { unlinkSync(pausedPath); } catch { /* non-fatal */ } + try { unlinkSync(pausedPath); } catch (err) { + logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } ctx.ui.notify( `Paused milestone ${meta.milestoneId} is ${!mDir ? "missing" : "already complete"}. Starting fresh.`, "info", @@ -1105,40 +1224,91 @@ export async function startAuto( s.currentMilestoneId = meta.milestoneId; s.originalBasePath = meta.originalBasePath || base; s.stepMode = meta.stepMode ?? requestedStepMode; + s.pausedSessionFile = meta.sessionFile ?? null; + s.pausedUnitType = meta.unitType ?? null; + s.pausedUnitId = meta.unitId ?? null; + s.autoStartTime = meta.autoStartTime || Date.now(); s.paused = true; - // Clean up the persisted file — we're consuming it - try { unlinkSync(pausedPath); } catch { /* non-fatal */ } + try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); } ctx.ui.notify( - `Resuming paused session for ${meta.milestoneId}${meta.worktreePath ? ` (worktree)` : ""}.`, + `Resuming paused session for ${meta.milestoneId}${meta.worktreePath && existsSync(meta.worktreePath) ? ` (worktree)` : ""}.`, "info", ); } + } else if (existsSync(pausedPath)) { + try { unlinkSync(pausedPath); } catch (e) { logWarning("session", `stale pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" }); } } } - } catch { + } catch (err) { // Malformed or missing — proceed with fresh bootstrap + logWarning("session", `paused-session restore failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } + // Guard against zero/missing autoStartTime after resume (#3585) + if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now(); + } + + if (!s.paused) { + s.stepMode = requestedStepMode; + } + + if (freshStartAssessment.lock) { + clearLock(base); + } + + if (!s.paused) { + s.pendingCrashRecovery = + freshStartAssessment.classification === "recoverable" + ? freshStartAssessment.recoveryPrompt + : null; + + if (freshStartAssessment.classification === "recoverable" && freshStartAssessment.lock) { + const info = formatCrashInfo(freshStartAssessment.lock); + if (freshStartAssessment.recoveryToolCallCount > 0) { + ctx.ui.notify( + `${info}\nRecovered ${freshStartAssessment.recoveryToolCallCount} tool calls from crashed session. Resuming with full context.`, + "warning", + ); + } else if (freshStartAssessment.hasResumableDiskState) { + ctx.ui.notify(`${info}\nResuming from disk state.`, "warning"); + } } } if (s.paused) { const resumeLock = acquireSessionLock(base); if (!resumeLock.acquired) { + // Reset paused state so isAutoPaused() doesn't stick true after lock failure. + // Pause file is preserved on disk for retry — not deleted. + s.paused = false; ctx.ui.notify(`Cannot resume: ${resumeLock.reason}`, "error"); return; } + // Lock acquired — now safe to delete the pause file + if (s.pausedSessionFile) { + try { unlinkSync(s.pausedSessionFile); } catch (err) { + logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } + s.pausedSessionFile = null; + } + s.paused = false; s.active = true; s.verbose = verboseMode; s.stepMode = requestedStepMode; s.cmdCtx = ctx; s.basePath = base; - setLogBasePath(base); s.unitDispatchCount.clear(); s.unitLifetimeDispatches.clear(); if (!getLedger()) initMetrics(base); if (s.currentMilestoneId) setActiveMilestoneId(base, s.currentMilestoneId); + // Re-register health level notification callback lost across process restart + setLevelChangeCallback((_from, to, summary) => { + const level = to === "red" ? "error" : to === "yellow" ? "warning" : "info"; + ctx.ui.notify(summary, level as "info" | "warning" | "error"); + }); + // ── Auto-worktree: re-enter worktree on resume ── if ( s.currentMilestoneId && @@ -1162,6 +1332,23 @@ export async function startAuto( "info", ); restoreHookState(s.basePath); + // Re-sync managed resources on resume so long-lived auto sessions pick up + // bundled extension updates before resume-time verification/state logic runs. + // GSD_PKG_ROOT is set by loader.ts and points to the gsd-pi package root. + // The relative import ("../../../resource-loader.js") only works from the source + // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the + // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist. + // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949). + const agentDir = process.env.GSD_CODING_AGENT_DIR || join(process.env.GSD_HOME || homedir(), ".gsd", "agent"); + const pkgRoot = process.env.GSD_PKG_ROOT; + const resourceLoaderPath = pkgRoot + ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href + : new URL("../../../resource-loader.js", import.meta.url).href; + const { initResources } = await import(resourceLoaderPath); + initResources(agentDir); + // Open the project DB before rebuild/derive so resume uses DB-backed + // state instead of falling back to stale markdown parsing (#2940). + await openProjectDbIfPresent(s.basePath); try { await rebuildState(s.basePath); syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath)); @@ -1189,8 +1376,8 @@ export async function startAuto( const activityDir = join(gsdRoot(s.basePath), "activity"); const recovery = synthesizeCrashRecovery( s.basePath, - s.currentUnit?.type ?? "unknown", - s.currentUnit?.id ?? "unknown", + s.currentUnit?.type ?? s.pausedUnitType ?? "unknown", + s.currentUnit?.id ?? s.pausedUnitId ?? "unknown", s.pausedSessionFile ?? undefined, activityDir, ); @@ -1216,6 +1403,7 @@ export async function startAuto( ); logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress"); + captureProjectRootEnv(s.originalBasePath || s.basePath); await autoLoop(ctx, pi, s, buildLoopDeps()); cleanupAfterLoopExit(ctx); return; @@ -1237,13 +1425,16 @@ export async function startAuto( verboseMode, requestedStepMode, bootstrapDeps, + freshStartAssessment, ); if (!ready) return; + captureProjectRootEnv(s.originalBasePath || s.basePath); try { syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath)); - } catch { + } catch (err) { // Best-effort only — sidebar sync must never block auto-mode startup + logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress"); @@ -1307,6 +1498,7 @@ const widgetStateAccessors: WidgetStateAccessors = { getBasePath: () => s.basePath, isVerbose: () => s.verbose, isSessionSwitching: isSessionSwitchInFlight, + getCurrentDispatchedModelId: () => s.currentDispatchedModelId, }; // ─── Preconditions ──────────────────────────────────────────────────────────── @@ -1347,27 +1539,6 @@ function ensurePreconditions( } } -// ─── Diagnostics ────────────────────────────────────────────────────────────── - -/** Build recovery context from module state for recoverTimedOutUnit */ -function buildRecoveryContext(): import("./auto-timeout-recovery.js").RecoveryContext { - return { - basePath: s.basePath, - verbose: s.verbose, - currentUnitStartedAt: s.currentUnit?.startedAt ?? Date.now(), - unitRecoveryCount: s.unitRecoveryCount, - }; -} - -/** - * Test-only: expose skip-loop state for unit tests. - * Not part of the public API. - */ - -/** - * Dispatch a hook unit directly, bypassing normal pre-dispatch hooks. - * Used for manual hook triggers via /gsd run-hook. - */ export async function dispatchHookUnit( ctx: ExtensionContext, pi: ExtensionAPI, @@ -1415,8 +1586,9 @@ export async function dispatchHookUnit( if (match) { try { await pi.setModel(match); - } catch { + } catch (err) { /* non-fatal */ + logWarning("dispatch", `hook model set failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); } } else { ctx.ui.notify( @@ -1453,7 +1625,9 @@ export async function dispatchHookUnit( ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info"); // Ensure cwd matches basePath before hook dispatch (#1389) - try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch {} + try { if (process.cwd() !== s.basePath) process.chdir(s.basePath); } catch (err) { + logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" }); + } debugLog("dispatchHookUnit", { phase: "send-message", diff --git a/src/resources/extensions/gsd/auto/detect-stuck.ts b/src/resources/extensions/gsd/auto/detect-stuck.ts index 4d6cba5d2..ab28f4850 100644 --- a/src/resources/extensions/gsd/auto/detect-stuck.ts +++ b/src/resources/extensions/gsd/auto/detect-stuck.ts @@ -6,6 +6,13 @@ import type { WindowEntry } from "./types.js"; +/** + * Pattern matching ENOENT errors with a file path. + * Matches: "ENOENT: no such file or directory, access '/path/to/file'" + * and similar Node.js filesystem error messages. + */ +const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/; + /** * Analyze a sliding window of recent unit dispatches for stuck patterns. * Returns a signal with reason if stuck, null otherwise. @@ -13,6 +20,8 @@ import type { WindowEntry } from "./types.js"; * Rule 1: Same error string twice in a row → stuck immediately. * Rule 2: Same unit key 3+ consecutive times → stuck (preserves prior behavior). * Rule 3: Oscillation A→B→A→B in last 4 entries → stuck. + * Rule 4: Same ENOENT path in any 2 entries within the window → stuck (#3575). + * Missing files don't self-heal between retries — retrying wastes budget. */ export function detectStuck( window: readonly WindowEntry[], @@ -56,5 +65,23 @@ export function detectStuck( } } + // Rule 4: Same ENOENT path seen twice in window (#3575) + // Missing files don't appear between retries — stop immediately. + const enoentPaths = new Map(); + for (const entry of window) { + if (!entry.error) continue; + const match = ENOENT_PATH_RE.exec(entry.error); + if (!match) continue; + const filePath = match[1]; + const count = (enoentPaths.get(filePath) ?? 0) + 1; + if (count >= 2) { + return { + stuck: true, + reason: `Missing file referenced twice: ${filePath} (ENOENT)`, + }; + } + enoentPaths.set(filePath, count); + } + return null; } diff --git a/src/resources/extensions/gsd/auto/finalize-timeout.ts b/src/resources/extensions/gsd/auto/finalize-timeout.ts new file mode 100644 index 000000000..f5e073fc9 --- /dev/null +++ b/src/resources/extensions/gsd/auto/finalize-timeout.ts @@ -0,0 +1,49 @@ +/** + * auto/finalize-timeout.ts — Timeout guard for post-unit finalization. + * + * Prevents the auto-loop from hanging indefinitely when + * postUnitPostVerification() never resolves (#2344). + * + * Leaf module — no imports from auto/ to avoid circular dependencies. + */ + +/** Timeout for postUnitPreVerification in runFinalize (ms). */ +export const FINALIZE_PRE_TIMEOUT_MS = 60_000; + +/** Timeout for postUnitPostVerification in runFinalize (ms). */ +export const FINALIZE_POST_TIMEOUT_MS = 60_000; + +/** + * Race a promise against a timeout. Returns an object indicating whether + * the timeout fired and the resolved value (if any). + * + * Unlike Promise.race with a rejection, this returns a discriminated + * result so callers can handle timeouts as a recoverable condition + * rather than an exception. + * + * The timeout timer is always cleaned up, whether the promise resolves + * or the timeout fires. + */ +export async function withTimeout( + promise: Promise, + timeoutMs: number, + label: string, +): Promise<{ value: T; timedOut: false } | { value: undefined; timedOut: true }> { + let timeoutHandle: ReturnType | undefined; + + const timeoutPromise = new Promise<{ value: undefined; timedOut: true }>((resolve) => { + timeoutHandle = setTimeout(() => { + resolve({ value: undefined, timedOut: true }); + }, timeoutMs); + }); + + try { + const result = await Promise.race([ + promise.then((value) => ({ value, timedOut: false as const })), + timeoutPromise, + ]); + return result; + } finally { + if (timeoutHandle) clearTimeout(timeoutHandle); + } +} diff --git a/src/resources/extensions/gsd/auto/loop-deps.ts b/src/resources/extensions/gsd/auto/loop-deps.ts index 565dde5a3..ff63d8a3e 100644 --- a/src/resources/extensions/gsd/auto/loop-deps.ts +++ b/src/resources/extensions/gsd/auto/loop-deps.ts @@ -20,6 +20,7 @@ import type { DispatchAction } from "../auto-dispatch.js"; import type { WorktreeResolver } from "../worktree-resolver.js"; import type { CmuxLogLevel } from "../../cmux/index.js"; import type { JournalEntry } from "../journal.js"; +import type { MergeReconcileResult } from "../auto-recovery.js"; /** * Dependencies injected by the caller (auto.ts startAuto) so autoLoop @@ -93,6 +94,7 @@ export interface LoopDeps { body: string, kind: string, category: string, + projectName?: string, ) => void; setActiveMilestoneId: (basePath: string, mid: string) => void; pruneQueueOrder: (basePath: string, pendingIds: string[]) => void; @@ -117,7 +119,7 @@ export interface LoopDeps { milestoneId: string, fileType: string, ) => string | null; - reconcileMergeState: (basePath: string, ctx: ExtensionContext) => boolean; + reconcileMergeState: (basePath: string, ctx: ExtensionContext) => MergeReconcileResult; // Budget/context/secrets getLedger: () => unknown; diff --git a/src/resources/extensions/gsd/auto/loop.ts b/src/resources/extensions/gsd/auto/loop.ts index 712968422..3a0c8de10 100644 --- a/src/resources/extensions/gsd/auto/loop.ts +++ b/src/resources/extensions/gsd/auto/loop.ts @@ -46,8 +46,9 @@ export async function autoLoop( ): Promise { debugLog("autoLoop", { phase: "enter" }); let iteration = 0; - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; let consecutiveErrors = 0; + const recentErrorMessages: string[] = []; while (s.active) { iteration++; @@ -193,7 +194,7 @@ export async function autoLoop( // Verification passed — mark step complete debugLog("autoLoop", { phase: "custom-engine-reconcile", iteration, unitId: iterData.unitId }); - await engine.reconcile(engineState, { + const reconcileResult = await engine.reconcile(engineState, { unitType: iterData.unitType, unitId: iterData.unitId, startedAt: s.currentUnit?.startedAt ?? Date.now(), @@ -202,8 +203,22 @@ export async function autoLoop( deps.clearUnitTimeout(); consecutiveErrors = 0; + recentErrorMessages.length = 0; deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } }); debugLog("autoLoop", { phase: "iteration-complete", iteration }); + + if (reconcileResult.outcome === "milestone-complete") { + await deps.stopAuto(ctx, pi, "Workflow complete"); + break; + } + if (reconcileResult.outcome === "pause") { + await deps.pauseAuto(ctx, pi); + break; + } + if (reconcileResult.outcome === "stop") { + await deps.stopAuto(ctx, pi, reconcileResult.reason ?? "Engine stopped"); + break; + } continue; } @@ -245,17 +260,23 @@ export async function autoLoop( // ── Phase 5: Finalize ─────────────────────────────────────────────── - const finalizeResult = await runFinalize(ic, iterData, sidecarItem); + const finalizeResult = await runFinalize(ic, iterData, loopState, sidecarItem); if (finalizeResult.action === "break") break; if (finalizeResult.action === "continue") continue; consecutiveErrors = 0; // Iteration completed successfully + recentErrorMessages.length = 0; deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration } }); debugLog("autoLoop", { phase: "iteration-complete", iteration }); } catch (loopErr) { // ── Blanket catch: absorb unexpected exceptions, apply graduated recovery ── const msg = loopErr instanceof Error ? loopErr.message : String(loopErr); + // Always emit iteration-end on error so the journal records iteration + // completion even on failure (#2344). Without this, errors in + // runFinalize leave the journal incomplete, making diagnosis harder. + deps.emitJournalEvent({ ts: new Date().toISOString(), flowId, seq: nextSeq(), eventType: "iteration-end", data: { iteration, error: msg } }); + // ── Infrastructure errors: immediate stop, no retry ── // These are unrecoverable (disk full, OOM, etc.). Retrying just burns // LLM budget on guaranteed failures. @@ -280,6 +301,7 @@ export async function autoLoop( } consecutiveErrors++; + recentErrorMessages.push(msg.length > 120 ? msg.slice(0, 120) + "..." : msg); debugLog("autoLoop", { phase: "iteration-error", iteration, @@ -289,8 +311,11 @@ export async function autoLoop( if (consecutiveErrors >= 3) { // 3+ consecutive: hard stop — something is fundamentally broken + const errorHistory = recentErrorMessages + .map((m, i) => ` ${i + 1}. ${m}`) + .join("\n"); ctx.ui.notify( - `Auto-mode stopped: ${consecutiveErrors} consecutive iteration failures. Last: ${msg}`, + `Auto-mode stopped: ${consecutiveErrors} consecutive iteration failures:\n${errorHistory}`, "error", ); await deps.stopAuto( diff --git a/src/resources/extensions/gsd/auto/phases.ts b/src/resources/extensions/gsd/auto/phases.ts index 06778ff1b..a3591e6ca 100644 --- a/src/resources/extensions/gsd/auto/phases.ts +++ b/src/resources/extensions/gsd/auto/phases.ts @@ -15,6 +15,7 @@ import type { PostUnitContext, PreVerificationOpts } from "../auto-post-unit.js" import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, + MAX_FINALIZE_TIMEOUTS, type PhaseResult, type IterationContext, type LoopState, @@ -26,13 +27,24 @@ import { runUnit } from "./run-unit.js"; import { debugLog } from "../debug-logger.js"; import { PROJECT_FILES } from "../detection.js"; import { MergeConflictError } from "../git-service.js"; -import { join } from "node:path"; -import { existsSync, cpSync } from "node:fs"; +import { join, basename, dirname, parse as parsePath } from "node:path"; +import { existsSync, cpSync, readdirSync } from "node:fs"; import { logWarning, logError } from "../workflow-logger.js"; import { gsdRoot } from "../paths.js"; import { atomicWriteSync } from "../atomic-write.js"; -import { verifyExpectedArtifact } from "../auto-recovery.js"; +import { verifyExpectedArtifact, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.js"; import { writeUnitRuntimeRecord } from "../unit-runtime.js"; +import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js"; +import { getEligibleSlices } from "../slice-parallel-eligibility.js"; +import { startSliceParallel } from "../slice-parallel-orchestrator.js"; +import { isDbAvailable, getMilestoneSlices } from "../gsd-db.js"; +import { resetEvidence } from "../safety/evidence-collector.js"; +import { createCheckpoint, cleanupCheckpoint, rollbackToCheckpoint } from "../safety/git-checkpoint.js"; +import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js"; +import { + getWorkflowTransportSupportError, + getRequiredWorkflowToolsForAutoUnit, +} from "../workflow-mcp.js"; // ─── generateMilestoneReport ────────────────────────────────────────────────── @@ -182,7 +194,7 @@ export async function runPreDispatch( } if (!healthGate.proceed) { ctx.ui.notify( - healthGate.reason ?? "Pre-dispatch health check failed.", + healthGate.reason || "Pre-dispatch health check failed — run /gsd doctor for details.", "error", ); await deps.pauseAuto(ctx, pi); @@ -218,6 +230,63 @@ export async function runPreDispatch( statePhase: state.phase, }); + // ── Slice-level parallelism gate (#2340) ───────────────────────────── + // When slice_parallel is enabled, check if multiple slices are eligible + // for parallel execution. If so, dispatch them in parallel and stop the + // sequential loop. Workers are spawned via slice-parallel-orchestrator.ts. + if ( + prefs?.slice_parallel?.enabled && + mid && + !process.env.GSD_PARALLEL_WORKER && + isDbAvailable() + ) { + try { + const dbSlices = getMilestoneSlices(mid); + if (dbSlices.length > 0) { + const doneIds = new Set(dbSlices.filter(sl => sl.status === "complete" || sl.status === "done").map(sl => sl.id)); + const sliceInputs = dbSlices.map(sl => ({ + id: sl.id, + done: doneIds.has(sl.id), + depends: sl.depends ?? [], + })); + const eligible = getEligibleSlices(sliceInputs, doneIds); + if (eligible.length > 1) { + debugLog("autoLoop", { + phase: "slice-parallel-dispatch", + iteration: ic.iteration, + mid, + eligibleSlices: eligible.map(e => e.id), + }); + ctx.ui.notify( + `Slice-parallel: dispatching ${eligible.length} eligible slices for ${mid}.`, + "info", + ); + const result = await startSliceParallel( + s.basePath, + mid, + eligible, + { maxWorkers: prefs.slice_parallel.max_workers ?? 2 }, + ); + if (result.started.length > 0) { + ctx.ui.notify( + `Slice-parallel: started ${result.started.length} worker(s): ${result.started.join(", ")}.`, + "info", + ); + await deps.stopAuto(ctx, pi, `Slice-parallel dispatched for ${mid}`); + return { action: "break", reason: "slice-parallel-dispatched" }; + } + // Fall through to sequential if no workers started + } + } + } catch (err) { + debugLog("autoLoop", { + phase: "slice-parallel-check-error", + error: err instanceof Error ? err.message : String(err), + }); + // Non-fatal — fall through to sequential dispatch + } + } + // ── Milestone transition ──────────────────────────────────────────── if (mid && s.currentMilestoneId && mid !== s.currentMilestoneId) { deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "milestone-transition", data: { from: s.currentMilestoneId, to: mid } }); @@ -230,6 +299,7 @@ export async function runPreDispatch( `Milestone ${s.currentMilestoneId} complete!`, "success", "milestone", + basename(s.originalBasePath || s.basePath), ); deps.logCmuxEvent( prefs, @@ -388,6 +458,7 @@ export async function runPreDispatch( "All milestones complete!", "success", "milestone", + basename(s.originalBasePath || s.basePath), ); deps.logCmuxEvent( prefs, @@ -411,7 +482,7 @@ export async function runPreDispatch( const blockerMsg = `Blocked: ${state.blockers.join(", ")}`; await deps.stopAuto(ctx, pi, blockerMsg); ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning"); - deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention"); + deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath)); deps.logCmuxEvent(prefs, blockerMsg, "error"); } else { const ids = incomplete.map((m: { id: string }) => m.id).join(", "); @@ -440,7 +511,13 @@ export async function runPreDispatch( } // Mid-merge safety check - if (deps.reconcileMergeState(s.basePath, ctx)) { + const mergeReconcileResult = deps.reconcileMergeState(s.basePath, ctx); + if (mergeReconcileResult === "blocked") { + await deps.pauseAuto(ctx, pi); + debugLog("autoLoop", { phase: "exit", reason: "merge-reconciliation-blocked" }); + return { action: "break", reason: "merge-reconciliation-blocked" }; + } + if (mergeReconcileResult === "reconciled") { deps.invalidateAllCaches(); state = await deps.deriveState(s.basePath); mid = state.activeMilestone?.id; @@ -492,6 +569,7 @@ export async function runPreDispatch( `Milestone ${mid} complete!`, "success", "milestone", + basename(s.originalBasePath || s.basePath), ); deps.logCmuxEvent( prefs, @@ -509,7 +587,7 @@ export async function runPreDispatch( const blockerMsg = `Blocked: ${state.blockers.join(", ")}`; await closeoutAndStop(ctx, pi, s, deps, blockerMsg); ctx.ui.notify(`${blockerMsg}. Fix and run /gsd auto.`, "warning"); - deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention"); + deps.sendDesktopNotification("GSD", blockerMsg, "error", "attention", basename(s.originalBasePath || s.basePath)); deps.logCmuxEvent(prefs, blockerMsg, "error"); debugLog("autoLoop", { phase: "exit", reason: "blocked" }); deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "terminal", data: { reason: "blocked", blockers: state.blockers } }); @@ -625,15 +703,17 @@ export async function runDispatch( unitId, reason: stuckSignal.reason, }); + const stuckDiag = diagnoseExpectedArtifact(unitType, unitId, s.basePath); + const stuckRemediation = buildLoopRemediationSteps(unitType, unitId, s.basePath); + const stuckParts = [`Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}.`]; + if (stuckDiag) stuckParts.push(`Expected: ${stuckDiag}`); + if (stuckRemediation) stuckParts.push(`To recover:\n${stuckRemediation}`); + ctx.ui.notify(stuckParts.join(" "), "error"); await deps.stopAuto( ctx, pi, `Stuck: ${stuckSignal.reason}`, ); - ctx.ui.notify( - `Stuck on ${unitType} ${unitId} — ${stuckSignal.reason}. The expected artifact was not written.`, - "error", - ); return { action: "break", reason: "stuck-detected" }; } } else { @@ -706,7 +786,7 @@ export async function runDispatch( // ─── runGuards ──────────────────────────────────────────────────────────────── /** - * Phase 2: Guards — budget ceiling, context window, secrets re-check. + * Phase 2: Guards — stop directives, budget ceiling, context window, secrets re-check. * Returns break to exit the loop, or next to proceed to dispatch. */ export async function runGuards( @@ -715,6 +795,55 @@ export async function runGuards( ): Promise { const { ctx, pi, s, deps, prefs } = ic; + // ── Stop/Backtrack directive guard (#3487) ── + // Check for unexecuted stop or backtrack captures BEFORE dispatching any unit. + // This ensures user "halt" directives are honored immediately. + // IMPORTANT: Fail-closed — any exception during stop handling still breaks the loop + // to ensure user halt intent is never silently dropped. + try { + const { loadStopCaptures, markCaptureExecuted } = await import("../captures.js"); + const stopCaptures = loadStopCaptures(s.basePath); + if (stopCaptures.length > 0) { + const first = stopCaptures[0]; + const isBacktrack = first.classification === "backtrack"; + const label = isBacktrack + ? `Backtrack directive: ${first.text}` + : `Stop directive: ${first.text}`; + + ctx.ui.notify(label, "warning"); + deps.sendDesktopNotification( + "GSD", label, "warning", "stop-directive", + basename(s.originalBasePath || s.basePath), + ); + + // Pause first — ensures auto-mode stops even if later steps fail + await deps.pauseAuto(ctx, pi); + + // For backtrack captures, write the backtrack trigger after pausing + if (isBacktrack) { + try { + const { executeBacktrack } = await import("../triage-resolution.js"); + executeBacktrack(s.basePath, mid, first); + } catch (e) { + debugLog("guards", { phase: "backtrack-execution-error", error: String(e) }); + } + } + + // Mark captures as executed only after successful pause/transition + for (const cap of stopCaptures) { + markCaptureExecuted(s.basePath, cap.id); + } + + debugLog("autoLoop", { phase: "exit", reason: isBacktrack ? "user-backtrack" : "user-stop" }); + return { action: "break", reason: isBacktrack ? "user-backtrack" : "user-stop" }; + } + } catch (e) { + // Fail-closed: if anything in the stop guard throws, break the loop + // rather than silently continuing and dropping user halt intent + debugLog("guards", { phase: "stop-guard-error", error: String(e) }); + return { action: "break", reason: "stop-guard-error" }; + } + // Budget ceiling guard const budgetCeiling = prefs?.budget_ceiling; if (budgetCeiling !== undefined && budgetCeiling > 0) { @@ -755,7 +884,7 @@ export async function runGuards( // 100% — special enforcement logic (halt/pause/warn) const msg = `Budget ceiling ${deps.formatCost(budgetCeiling)} reached (spent ${deps.formatCost(totalCost)}).`; if (budgetEnforcementAction === "halt") { - deps.sendDesktopNotification("GSD", msg, "error", "budget"); + deps.sendDesktopNotification("GSD", msg, "error", "budget", basename(s.originalBasePath || s.basePath)); await deps.stopAuto(ctx, pi, "Budget ceiling reached"); debugLog("autoLoop", { phase: "exit", reason: "budget-halt" }); return { action: "break", reason: "budget-halt" }; @@ -765,14 +894,14 @@ export async function runGuards( `${msg} Pausing auto-mode — /gsd auto to override and continue.`, "warning", ); - deps.sendDesktopNotification("GSD", msg, "warning", "budget"); + deps.sendDesktopNotification("GSD", msg, "warning", "budget", basename(s.originalBasePath || s.basePath)); deps.logCmuxEvent(prefs, msg, "warning"); await deps.pauseAuto(ctx, pi); debugLog("autoLoop", { phase: "exit", reason: "budget-pause" }); return { action: "break", reason: "budget-pause" }; } ctx.ui.notify(`${msg} Continuing (enforcement: warn).`, "warning"); - deps.sendDesktopNotification("GSD", msg, "warning", "budget"); + deps.sendDesktopNotification("GSD", msg, "warning", "budget", basename(s.originalBasePath || s.basePath)); deps.logCmuxEvent(prefs, msg, "warning"); } else if (threshold.pct < 100) { // Sub-100% — simple notification @@ -783,6 +912,7 @@ export async function runGuards( msg, threshold.notifyLevel, "budget", + basename(s.originalBasePath || s.basePath), ); deps.logCmuxEvent(prefs, msg, threshold.cmuxLevel); } @@ -812,6 +942,7 @@ export async function runGuards( `Context ${contextUsage.percent}% — paused`, "warning", "attention", + basename(s.originalBasePath || s.basePath), ); await deps.pauseAuto(ctx, pi); debugLog("autoLoop", { phase: "exit", reason: "context-window" }); @@ -892,11 +1023,38 @@ export async function runUnitPhase( } const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f))); const hasSrcDir = deps.existsSync(join(s.basePath, "src")); - if (!hasProjectFile && !hasSrcDir) { + // Xcode bundles have project-specific names (*.xcodeproj, *.xcworkspace) + // that cannot be matched by exact filename — scan the directory by suffix. + let hasXcodeBundle = false; + try { + const entries = deps.existsSync(s.basePath) ? readdirSync(s.basePath) : []; + hasXcodeBundle = entries.some((e: string) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace")); + } catch (err) { + debugLog("runUnitPhase", { phase: "xcode-bundle-scan-failed", basePath: s.basePath, error: String(err) }); + } + // Monorepo support (#2347): if no project files in the worktree directory, + // walk parent directories up to the filesystem root. In monorepos, + // package.json / Cargo.toml etc. live in a parent directory. + let hasProjectFileInParent = false; + if (!hasProjectFile && !hasSrcDir && !hasXcodeBundle) { + let checkDir = dirname(s.basePath); + const { root } = parsePath(checkDir); + while (checkDir !== root) { + // Stop at git repository boundary — ancestors above the repo root + // (e.g. ~ or /usr/local) may contain unrelated project files. + if (deps.existsSync(join(checkDir, ".git"))) break; + if (PROJECT_FILES.some((f) => deps.existsSync(join(checkDir, f)))) { + hasProjectFileInParent = true; + break; + } + checkDir = dirname(checkDir); + } + } + if (!hasProjectFile && !hasSrcDir && !hasXcodeBundle && !hasProjectFileInParent) { // Greenfield projects won't have project files yet — the first task creates them. // Log a warning but allow execution to proceed. The .git check above is sufficient // to ensure we're in a valid working directory. - debugLog("runUnitPhase", { phase: "worktree-health-warn-greenfield", basePath: s.basePath, hasProjectFile, hasSrcDir }); + debugLog("runUnitPhase", { phase: "worktree-health-warn-greenfield", basePath: s.basePath, hasProjectFile, hasSrcDir, hasXcodeBundle }); ctx.ui.notify(`Warning: ${s.basePath} has no recognized project files — proceeding as greenfield project`, "warning"); } } @@ -910,6 +1068,7 @@ export async function runUnitPhase( const previousTier = s.currentUnitRouting?.tier; s.currentUnit = { type: unitType, id: unitId, startedAt: Date.now() }; + s.lastToolInvocationError = null; // #2883: clear stale error from previous unit const unitStartSeq = ic.nextSeq(); deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } }); deps.captureAvailableSkills(); @@ -929,13 +1088,25 @@ export async function runUnitPhase( }, ); - // Status bar + progress widget + // Status bar (widget + preconditions deferred until after model selection — see #2899) ctx.ui.setStatus("gsd-auto", "auto"); if (mid) deps.updateSliceProgressCache(s.basePath, mid, state.activeSlice?.id); - deps.updateProgressWidget(ctx, unitType, unitId, state); - deps.ensurePreconditions(unitType, unitId, s.basePath, state); + // ── Safety harness: reset evidence + create checkpoint ── + const safetyConfig = resolveSafetyHarnessConfig( + prefs?.safety_harness as Record | undefined, + ); + if (safetyConfig.enabled && safetyConfig.evidence_collection) { + resetEvidence(); + } + // Only checkpoint code-executing units (not lifecycle/planning units) + if (safetyConfig.enabled && safetyConfig.checkpoints && unitType === "execute-task") { + s.checkpointSha = createCheckpoint(s.basePath, unitId); + if (s.checkpointSha) { + debugLog("runUnitPhase", { phase: "checkpoint-created", unitId, sha: s.checkpointSha.slice(0, 8) }); + } + } // Prompt injection let finalPrompt = prompt; @@ -1043,6 +1214,38 @@ export async function runUnitPhase( } } + // Store the final dispatched model ID so the dashboard can read it (#2899). + // This accounts for hook model overrides applied after selectAndApplyModel. + s.currentDispatchedModelId = s.currentUnitModel + ? `${(s.currentUnitModel as any).provider ?? ""}/${(s.currentUnitModel as any).id ?? ""}` + : null; + + const compatibilityError = getWorkflowTransportSupportError( + s.currentUnitModel?.provider ?? ctx.model?.provider, + getRequiredWorkflowToolsForAutoUnit(unitType), + { + projectRoot: s.basePath, + surface: "auto-mode", + unitType, + authMode: s.currentUnitModel?.provider + ? ctx.modelRegistry.getProviderAuthMode(s.currentUnitModel.provider) + : ctx.model?.provider + ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) + : undefined, + baseUrl: (s.currentUnitModel as any)?.baseUrl ?? ctx.model?.baseUrl, + }, + ); + if (compatibilityError) { + ctx.ui.notify(compatibilityError, "error"); + await deps.stopAuto(ctx, pi, compatibilityError); + return { action: "break", reason: "workflow-capability" }; + } + + // Progress widget + preconditions — deferred to after model selection so the + // widget's first render tick shows the correct model (#2899). + deps.updateProgressWidget(ctx, unitType, unitId, state); + deps.ensurePreconditions(unitType, unitId, s.basePath, state); + // Start unit supervision deps.clearUnitTimeout(); deps.startUnitSupervision({ @@ -1130,11 +1333,29 @@ export async function runUnitPhase( debugLog("autoLoop", { phase: "exit", reason: "provider-pause", isTransient: unitResult.errorContext.isTransient }); return { action: "break", reason: "provider-pause" }; } + // Session creation timeout (not a structural error): pause auto-mode + // and let the provider-error-resume timer handle recovery (#3767). This + // matches the provider-pause path — break out cleanly, don't hard-stop. + // Structural errors (TypeError, is not a function) are NOT transient + // and must hard-stop to avoid infinite retry loops. + if ( + unitResult.errorContext?.isTransient && + unitResult.errorContext?.category === "timeout" + ) { + ctx.ui.notify( + `Session creation timed out for ${unitType} ${unitId}. Pausing auto-mode (recoverable).`, + "warning", + ); + debugLog("autoLoop", { phase: "session-timeout-pause", unitType, unitId }); + await deps.pauseAuto(ctx, pi); + return { action: "break", reason: "session-timeout" }; + } + // All other cancelled states (structural errors, non-transient failures): hard stop ctx.ui.notify( - `Session creation timed out or was cancelled for ${unitType} ${unitId}. Will retry.`, + `Session creation failed for ${unitType} ${unitId}: ${unitResult.errorContext?.message ?? "unknown"}. Stopping auto-mode.`, "warning", ); - await deps.stopAuto(ctx, pi, "Session creation failed"); + await deps.stopAuto(ctx, pi, `Session creation failed: ${unitResult.errorContext?.message ?? "unknown"}`); debugLog("autoLoop", { phase: "exit", reason: "session-failed" }); return { action: "break", reason: "session-failed" }; } @@ -1142,39 +1363,45 @@ export async function runUnitPhase( // ── Immediate unit closeout (metrics, activity log, memory) ──────── // Run right after runUnit() returns so telemetry is never lost to a // crash between iterations. - await deps.closeoutUnit( - ctx, - s.basePath, - unitType, - unitId, - s.currentUnit.startedAt, - deps.buildSnapshotOpts(unitType, unitId), - ); + // Guard: stopAuto() may have nulled s.currentUnit via s.reset() while + // this coroutine was suspended at `await runUnit(...)` (#2939). + if (s.currentUnit) { + await deps.closeoutUnit( + ctx, + s.basePath, + unitType, + unitId, + s.currentUnit.startedAt, + deps.buildSnapshotOpts(unitType, unitId), + ); + } - // ── Zero tool-call guard (#1833) ────────────────────────────────── - // An execute-task agent that completes with 0 tool calls made no - // real changes — its summary is hallucinated. Treat as failed so - // the task is retried instead of silently marked complete. - if (unitType === "execute-task") { + // ── Zero tool-call guard (#1833, #2653) ────────────────────────── + // Any unit that completes with 0 tool calls made no real progress — + // likely context exhaustion where all tool calls errored out. Treat + // as failed so the unit is retried in a fresh context instead of + // silently passing through to artifact verification (which loops + // forever when the unit never produced its artifact). + { const currentLedger = deps.getLedger() as { units: Array<{ type: string; id: string; startedAt: number; toolCalls: number }> } | null; if (currentLedger?.units) { const lastUnit = [...currentLedger.units].reverse().find( - (u: { type: string; id: string; startedAt: number; toolCalls: number }) => u.type === unitType && u.id === unitId && u.startedAt === s.currentUnit!.startedAt, + (u: { type: string; id: string; startedAt: number; toolCalls: number }) => u.type === unitType && u.id === unitId && u.startedAt === s.currentUnit?.startedAt, ); if (lastUnit && lastUnit.toolCalls === 0) { debugLog("runUnitPhase", { phase: "zero-tool-calls", unitType, unitId, - warning: "Task completed with 0 tool calls — likely hallucinated, marking as failed", + warning: "Unit completed with 0 tool calls — likely context exhaustion, marking as failed", }); ctx.ui.notify( - `${unitType} ${unitId} completed with 0 tool calls — hallucinated summary, will retry`, + `${unitType} ${unitId} completed with 0 tool calls — context exhaustion, will retry`, "warning", ); // Fall through to next iteration where dispatch will re-derive - // and re-dispatch this task. - return { action: "next", data: { unitStartedAt: s.currentUnit.startedAt } }; + // and re-dispatch this unit. + return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt } }; } } } @@ -1196,9 +1423,49 @@ export async function runUnitPhase( s.unitRecoveryCount.delete(`${unitType}/${unitId}`); } + // Write phase handoff anchor after successful research/planning completion + const anchorPhases = new Set(["research-milestone", "research-slice", "plan-milestone", "plan-slice"]); + if (artifactVerified && mid && anchorPhases.has(unitType)) { + try { + const { writePhaseAnchor } = await import("../phase-anchor.js"); + writePhaseAnchor(s.basePath, mid, { + phase: unitType, + milestoneId: mid, + generatedAt: new Date().toISOString(), + intent: `Completed ${unitType} for ${unitId}`, + decisions: [], + blockers: [], + nextSteps: [], + }); + } catch (err) { /* non-fatal — anchor is advisory */ + logWarning("engine", `phase anchor failed: ${err instanceof Error ? err.message : String(err)}`); + } + } + deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: ic.nextSeq(), eventType: "unit-end", data: { unitType, unitId, status: unitResult.status, artifactVerified, ...(unitResult.errorContext ? { errorContext: unitResult.errorContext } : {}) }, causedBy: { flowId: ic.flowId, seq: unitStartSeq } }); - return { action: "next", data: { unitStartedAt: s.currentUnit.startedAt } }; + // ── Safety harness: checkpoint cleanup or rollback ── + if (s.checkpointSha) { + if (unitResult.status === "error" && safetyConfig.auto_rollback) { + const rolled = rollbackToCheckpoint(s.basePath, unitId, s.checkpointSha); + if (rolled) { + ctx.ui.notify(`Rolled back to pre-unit checkpoint for ${unitId}`, "info"); + debugLog("runUnitPhase", { phase: "checkpoint-rollback", unitId }); + } + } else if (unitResult.status === "error") { + ctx.ui.notify( + `Unit ${unitId} failed. Pre-unit checkpoint available at ${s.checkpointSha.slice(0, 8)}`, + "warning", + ); + } else { + // Success — clean up checkpoint ref + cleanupCheckpoint(s.basePath, unitId); + debugLog("runUnitPhase", { phase: "checkpoint-cleaned", unitId }); + } + s.checkpointSha = null; + } + + return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt } }; } // ─── runFinalize ────────────────────────────────────────────────────────────── @@ -1210,6 +1477,7 @@ export async function runUnitPhase( export async function runFinalize( ic: IterationContext, iterData: IterationData, + loopState: LoopState, sidecarItem?: SidecarItem, ): Promise { const { ctx, pi, s, deps } = ic; @@ -1233,13 +1501,58 @@ export async function runFinalize( }; // Pre-verification processing (commit, doctor, state rebuild, etc.) + // Timeout guard: if postUnitPreVerification hangs (e.g., safety harness + // deadlock, browser teardown hang, worktree sync stall), force-continue + // after timeout so the auto-loop is not permanently frozen (#3757). + // + // On timeout, null out s.currentUnit so the timed-out task's late async + // mutations are harmless — postUnitPreVerification guards all side effects + // behind `if (s.currentUnit)`. The next iteration sets a fresh currentUnit. // Sidecar items use lightweight pre-verification opts const preVerificationOpts: PreVerificationOpts | undefined = sidecarItem ? sidecarItem.kind === "hook" ? { skipSettleDelay: true, skipWorktreeSync: true } : { skipSettleDelay: true } : undefined; - const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts); + const preUnitSnapshot = s.currentUnit + ? { type: s.currentUnit.type, id: s.currentUnit.id, startedAt: s.currentUnit.startedAt } + : null; + const preResultGuard = await withTimeout( + deps.postUnitPreVerification(postUnitCtx, preVerificationOpts), + FINALIZE_PRE_TIMEOUT_MS, + "postUnitPreVerification", + ); + + if (preResultGuard.timedOut) { + // Detach session from the timed-out unit so late async completions + // cannot mutate state for the next unit (#3757). + s.currentUnit = null; + loopState.consecutiveFinalizeTimeouts++; + debugLog("autoLoop", { + phase: "pre-verification-timeout", + iteration: ic.iteration, + unitType: iterData.unitType, + unitId: iterData.unitId, + consecutiveTimeouts: loopState.consecutiveFinalizeTimeouts, + }); + + if (loopState.consecutiveFinalizeTimeouts >= MAX_FINALIZE_TIMEOUTS) { + ctx.ui.notify( + `postUnitPreVerification timed out ${loopState.consecutiveFinalizeTimeouts} consecutive times — stopping auto-mode to prevent budget waste`, + "error", + ); + await deps.stopAuto(ctx, pi, `${loopState.consecutiveFinalizeTimeouts} consecutive finalize timeouts`); + return { action: "break", reason: "finalize-timeout-escalation" }; + } + + ctx.ui.notify( + `postUnitPreVerification timed out after ${FINALIZE_PRE_TIMEOUT_MS / 1000}s for ${iterData.unitType} ${iterData.unitId} (${loopState.consecutiveFinalizeTimeouts}/${MAX_FINALIZE_TIMEOUTS}) — continuing to next iteration`, + "warning", + ); + return { action: "next", data: undefined as void }; + } + + const preResult = preResultGuard.value; if (preResult === "dispatched") { debugLog("autoLoop", { phase: "exit", @@ -1298,7 +1611,45 @@ export async function runFinalize( } // Post-verification processing (DB dual-write, hooks, triage, quick-tasks) - const postResult = await deps.postUnitPostVerification(postUnitCtx); + // Timeout guard: if postUnitPostVerification hangs (e.g., module import + // deadlock, SQLite transaction hang), force-continue after timeout so the + // auto-loop is not permanently frozen (#2344). + const postResultGuard = await withTimeout( + deps.postUnitPostVerification(postUnitCtx), + FINALIZE_POST_TIMEOUT_MS, + "postUnitPostVerification", + ); + + if (postResultGuard.timedOut) { + // Detach session from the timed-out unit so late async completions + // cannot mutate state for the next unit (#3757). + s.currentUnit = null; + loopState.consecutiveFinalizeTimeouts++; + debugLog("autoLoop", { + phase: "post-verification-timeout", + iteration: ic.iteration, + unitType: iterData.unitType, + unitId: iterData.unitId, + consecutiveTimeouts: loopState.consecutiveFinalizeTimeouts, + }); + + if (loopState.consecutiveFinalizeTimeouts >= MAX_FINALIZE_TIMEOUTS) { + ctx.ui.notify( + `postUnitPostVerification timed out ${loopState.consecutiveFinalizeTimeouts} consecutive times — stopping auto-mode to prevent budget waste`, + "error", + ); + await deps.stopAuto(ctx, pi, `${loopState.consecutiveFinalizeTimeouts} consecutive finalize timeouts`); + return { action: "break", reason: "finalize-timeout-escalation" }; + } + + ctx.ui.notify( + `postUnitPostVerification timed out after ${FINALIZE_POST_TIMEOUT_MS / 1000}s for ${iterData.unitType} ${iterData.unitId} (${loopState.consecutiveFinalizeTimeouts}/${MAX_FINALIZE_TIMEOUTS}) — continuing to next iteration`, + "warning", + ); + return { action: "next", data: undefined as void }; + } + + const postResult = postResultGuard.value; if (postResult === "stopped") { debugLog("autoLoop", { @@ -1314,5 +1665,8 @@ export async function runFinalize( return { action: "break", reason: "step-wizard" }; } + // Both pre and post verification completed without timeout — reset counter + loopState.consecutiveFinalizeTimeouts = 0; + return { action: "next", data: undefined as void }; } diff --git a/src/resources/extensions/gsd/auto/run-unit.ts b/src/resources/extensions/gsd/auto/run-unit.ts index c9e740171..6f1646364 100644 --- a/src/resources/extensions/gsd/auto/run-unit.ts +++ b/src/resources/extensions/gsd/auto/run-unit.ts @@ -12,6 +12,11 @@ import type { UnitResult } from "./types.js"; import { _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js"; import { debugLog } from "../debug-logger.js"; import { logWarning, logError } from "../workflow-logger.js"; +import { resolveAutoSupervisorConfig } from "../preferences.js"; + +// Tracks the latest session-switch attempt so a late timeout settlement from an +// older runUnit() call cannot clear the guard for a newer one. +let sessionSwitchGeneration = 0; /** * Execute a single unit: create a new session, send the prompt, and await @@ -36,10 +41,13 @@ export async function runUnit( let sessionResult: { cancelled: boolean }; let sessionTimeoutHandle: ReturnType | undefined; + const mySessionSwitchGeneration = ++sessionSwitchGeneration; _setSessionSwitchInFlight(true); try { const sessionPromise = s.cmdCtx!.newSession().finally(() => { - _setSessionSwitchInFlight(false); + if (sessionSwitchGeneration === mySessionSwitchGeneration) { + _setSessionSwitchInFlight(false); + } }); const timeoutPromise = new Promise<{ cancelled: true }>((resolve) => { sessionTimeoutHandle = setTimeout( @@ -108,9 +116,23 @@ export async function runUnit( { triggerTurn: true }, ); - // ── Await agent_end ── + // ── Await agent_end with absolute timeout (H4 fix) ── + // If supervision fails to resolve unitPromise within 30s, treat as cancelled. + // Without this, a crashed agent that never emits agent_end hangs the loop (#3161). debugLog("runUnit", { phase: "awaiting-agent-end", unitType, unitId }); - const result = await unitPromise; + const supervisor = resolveAutoSupervisorConfig(); + const UNIT_HARD_TIMEOUT_MS = Math.max( + 30_000, + ((supervisor.hard_timeout_minutes ?? 30) * 60 * 1000) + 30_000, + ); + let unitTimeoutHandle: ReturnType | undefined; + const timeoutResult = new Promise((resolve) => { + unitTimeoutHandle = setTimeout(() => { + resolve({ status: "cancelled", errorContext: { message: "Unit hard timeout — supervision may have failed", category: "timeout", isTransient: true } }); + }, UNIT_HARD_TIMEOUT_MS); + }); + const result = await Promise.race([unitPromise, timeoutResult]); + if (unitTimeoutHandle) clearTimeout(unitTimeoutHandle); debugLog("runUnit", { phase: "agent-end-received", unitType, diff --git a/src/resources/extensions/gsd/auto/session.ts b/src/resources/extensions/gsd/auto/session.ts index 9d11545e3..4f8fc82e0 100644 --- a/src/resources/extensions/gsd/auto/session.ts +++ b/src/resources/extensions/gsd/auto/session.ts @@ -67,7 +67,7 @@ export interface SidecarItem { export const MAX_UNIT_DISPATCHES = 3; export const STUB_RECOVERY_THRESHOLD = 2; export const MAX_LIFETIME_DISPATCHES = 6; -export const NEW_SESSION_TIMEOUT_MS = 30_000; +export const NEW_SESSION_TIMEOUT_MS = 120_000; // ─── AutoSession ───────────────────────────────────────────────────────────── @@ -84,6 +84,9 @@ export class AutoSession { // ── Paths ──────────────────────────────────────────────────────────────── basePath = ""; originalBasePath = ""; + previousProjectRootEnv: string | null = null; + hadProjectRootEnv = false; + projectRootEnvCaptured = false; gitService: GitServiceImpl | null = null; // ── Dispatch counters ──────────────────────────────────────────────────── @@ -105,6 +108,8 @@ export class AutoSession { // ── Model state ────────────────────────────────────────────────────────── autoModeStartModel: StartModel | null = null; currentUnitModel: Model | null = null; + /** Fully-qualified model ID (provider/id) set after selectAndApplyModel + hook overrides (#2899). */ + currentDispatchedModelId: string | null = null; originalModelId: string | null = null; originalModelProvider: string | null = null; lastBudgetAlertLevel: BudgetAlertLevel = 0; @@ -114,12 +119,19 @@ export class AutoSession { pendingVerificationRetry: PendingVerificationRetry | null = null; readonly verificationRetryCount = new Map(); pausedSessionFile: string | null = null; + pausedUnitType: string | null = null; + pausedUnitId: string | null = null; resourceVersionOnStart: string | null = null; lastStateRebuildAt = 0; // ── Sidecar queue ───────────────────────────────────────────────────── sidecarQueue: SidecarItem[] = []; + // ── Tool invocation errors (#2883) ────────────────────────────────── + /** Set when a GSD tool execution ends with isError due to malformed/truncated + * JSON arguments. Checked by postUnitPreVerification to break retry loops. */ + lastToolInvocationError: string | null = null; + // ── Isolation degradation ──────────────────────────────────────────── /** Set to true when worktree creation fails; prevents merge of nonexistent branch. */ isolationDegraded = false; @@ -131,6 +143,9 @@ export class AutoSession { // ── Dispatch circuit breakers ────────────────────────────────────── rewriteAttemptCount = 0; + /** Tracks consecutive bootstrap attempts that found phase === "complete". + * Moved from module-level to per-session so s.reset() clears it (#1348). */ + consecutiveCompleteBootstraps = 0; // ── Metrics ────────────────────────────────────────────────────────────── autoStartTime = 0; @@ -138,6 +153,10 @@ export class AutoSession { lastBaselineCharCount: number | undefined; pendingQuickTasks: CaptureEntry[] = []; + // ── Safety harness ─────────────────────────────────────────────────────── + /** SHA of the pre-unit git checkpoint ref. Cleared on success or rollback. */ + checkpointSha: string | null = null; + // ── Signal handler ─────────────────────────────────────────────────────── sigtermHandler: (() => void) | null = null; @@ -178,6 +197,9 @@ export class AutoSession { // Paths this.basePath = ""; this.originalBasePath = ""; + this.previousProjectRootEnv = null; + this.hadProjectRootEnv = false; + this.projectRootEnvCaptured = false; this.gitService = null; // Dispatch @@ -193,6 +215,7 @@ export class AutoSession { // Model this.autoModeStartModel = null; this.currentUnitModel = null; + this.currentDispatchedModelId = null; this.originalModelId = null; this.originalModelProvider = null; this.lastBudgetAlertLevel = 0; @@ -202,6 +225,8 @@ export class AutoSession { this.pendingVerificationRetry = null; this.verificationRetryCount.clear(); this.pausedSessionFile = null; + this.pausedUnitType = null; + this.pausedUnitId = null; this.resourceVersionOnStart = null; this.lastStateRebuildAt = 0; @@ -212,8 +237,11 @@ export class AutoSession { this.pendingQuickTasks = []; this.sidecarQueue = []; this.rewriteAttemptCount = 0; + this.consecutiveCompleteBootstraps = 0; + this.lastToolInvocationError = null; this.isolationDegraded = false; this.milestoneMergedInPhases = false; + this.checkpointSha = null; // Signal handler this.sigtermHandler = null; diff --git a/src/resources/extensions/gsd/auto/types.ts b/src/resources/extensions/gsd/auto/types.ts index d3e342f82..9c2d1d466 100644 --- a/src/resources/extensions/gsd/auto/types.ts +++ b/src/resources/extensions/gsd/auto/types.ts @@ -91,8 +91,13 @@ export interface IterationContext { export interface LoopState { recentUnits: Array<{ key: string; error?: string }>; stuckRecoveryAttempts: number; + /** Consecutive finalize timeout count — stops auto-mode after threshold. */ + consecutiveFinalizeTimeouts: number; } +/** Max consecutive finalize timeouts before hard-stopping auto-mode. */ +export const MAX_FINALIZE_TIMEOUTS = 3; + export interface PreDispatchData { state: GSDState; mid: string; diff --git a/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts b/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts index 22dd56075..553df4e65 100644 --- a/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts +++ b/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts @@ -1,5 +1,6 @@ import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent"; +import { logWarning } from "../workflow-logger.js"; import { checkAutoStartAfterDiscuss } from "../guided-flow.js"; import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto } from "../auto.js"; import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js"; @@ -18,7 +19,17 @@ import { const retryState = createRetryState(); const MAX_NETWORK_RETRIES = 2; -const MAX_TRANSIENT_AUTO_RESUMES = 3; +const MAX_TRANSIENT_AUTO_RESUMES = 8; + +/** + * Reset the module-level retry state so a resumed auto-session starts fresh. + * Called by provider-error-resume.ts before startAuto() — without this, the + * consecutiveTransientCount accumulates across pause/resume cycles and locks + * out auto-resume after MAX_TRANSIENT_AUTO_RESUMES total (not consecutive) errors. + */ +export function resetTransientRetryState(): void { + resetRetryState(retryState); +} async function pauseTransientWithBackoff( cls: ErrorClass, @@ -68,16 +79,82 @@ export async function handleAgentEnd( const lastMsg = event.messages[event.messages.length - 1]; if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") { + // Empty content with aborted stopReason is a non-fatal agent stop (the LLM + // chose to end without producing output). Only pause on genuine fatal aborts + // that carry error context — e.g. errorMessage field or non-empty content + // indicating a mid-stream failure. (#2695) + const content = "content" in lastMsg ? lastMsg.content : undefined; + const hasEmptyContent = Array.isArray(content) && content.length === 0; + const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage; + + if (hasEmptyContent && !hasErrorMessage) { + // Non-fatal: treat as a normal agent end so the loop can continue + // instead of entering a stuck re-dispatch cycle. + try { + resetRetryState(retryState); + resolveAgentEnd(event); + } catch (err) { + const message = err instanceof Error ? err.message : String(err); + ctx.ui.notify(`Auto-mode error after empty-content abort: ${message}. Stopping auto-mode.`, "error"); + try { await pauseAuto(ctx, pi); } catch (e) { logWarning("bootstrap", `pauseAuto failed after empty-content abort: ${(e as Error).message}`); } + } + return; + } + await pauseAuto(ctx, pi); return; } if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") { - const errorDetail = "errorMessage" in lastMsg && lastMsg.errorMessage ? `: ${lastMsg.errorMessage}` : ""; - const errorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : ""; + // #3588: errorMessage can be useless (e.g. "success") while the real error + // is in the assistant message text content. Fall back to content when + // errorMessage looks uninformative. + const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : ""; + const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim()); + // #3588: When errorMessage is uninformative, extract the real error from + // the assistant message text content for display purposes only. + // Classification still uses rawErrorMsg to avoid false positives from prose. + let displayMsg = rawErrorMsg; + if (isUseless && "content" in lastMsg && Array.isArray(lastMsg.content)) { + const textBlock = lastMsg.content.find((b: any) => b.type === "text" && b.text); + if (textBlock) displayMsg = (textBlock as any).text.slice(0, 300); + } + const errorDetail = displayMsg ? `: ${displayMsg}` : ""; const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined; - // ── 1. Classify ────────────────────────────────────────────────────── - const cls = classifyError(errorMsg, explicitRetryAfterMs); + // ── 1. Classify using rawErrorMsg to avoid prose false-positives ──── + const cls = classifyError(rawErrorMsg, explicitRetryAfterMs); + + // ── 1b. Defer to Core RetryHandler for transient errors ───────────── + // The Core RetryHandler (agent-session.ts) processes retryable errors + // AFTER this extension handler, in the same _processAgentEvent() call. + // For transient errors (overloaded, rate limit, server), the Core will + // retry in-context — same session, same conversation — which is strictly + // better than our Layer 2 pause+resume (which creates a new session). + // + // If we react here AND the Core also retries, we race: pauseAuto tears + // down the session while agent.continue() starts a new turn. + // + // Solution: Do nothing for transient errors. The Core RetryHandler + // runs next in _processAgentEvent and will either: + // a) Retry successfully → new agent_end (success) → we see it next time + // b) Exhaust retries → the agent stays idle, autoLoop's unit timeout + // or stuck detection handles it + // + // We do NOT call resolveAgentEnd here — that would unblock autoLoop + // prematurely while the Core is still retrying in the same session. + // We do NOT call pauseAuto — that would tear down the session. + if (isTransient(cls)) { + return; + } + + // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli) + // which use per-user quotas with shorter windows (#2922). + if (cls.kind === "rate-limit") { + const currentProvider = ctx.model?.provider; + if (currentProvider === "openai-codex" || currentProvider === "google-gemini-cli") { + cls.retryAfterMs = Math.min(cls.retryAfterMs, 30_000); + } + } // ── 2. Decide & Act ────────────────────────────────────────────────── @@ -181,8 +258,8 @@ export async function handleAgentEnd( ctx.ui.notify(`Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`, "error"); try { await pauseAuto(ctx, pi); - } catch { - // best-effort + } catch (e) { + logWarning("bootstrap", `pauseAuto failed in agent_end handler: ${(e as Error).message}`); } } } diff --git a/src/resources/extensions/gsd/bootstrap/db-tools.ts b/src/resources/extensions/gsd/bootstrap/db-tools.ts index 8e6e490d2..71d5ae9aa 100644 --- a/src/resources/extensions/gsd/bootstrap/db-tools.ts +++ b/src/resources/extensions/gsd/bootstrap/db-tools.ts @@ -7,6 +7,19 @@ import { loadEffectiveGSDPreferences } from "../preferences.js"; import { ensureDbOpen } from "./dynamic-tools.js"; import { StringEnum } from "@gsd/pi-ai"; import { logError } from "../workflow-logger.js"; +import { getErrorMessage } from "../error-utils.js"; +import { + executeCompleteMilestone, + executePlanMilestone, + executePlanSlice, + executeReplanSlice, + executeReassessRoadmap, + executeSaveGateResult, + executeSliceComplete, + executeSummarySave, + executeTaskComplete, + executeValidateMilestone, +} from "../tools/workflow-tool-executors.js"; /** * Register an alias tool that shares the same execute function as its canonical counterpart. @@ -121,14 +134,6 @@ export function registerDbTools(pi: ExtensionAPI): void { }; } try { - const db = await import("../gsd-db.js"); - const existing = db.getRequirementById(params.id); - if (!existing) { - return { - content: [{ type: "text" as const, text: `Error: Requirement ${params.id} not found.` }], - details: { operation: "update_requirement", id: params.id, error: "not_found" } as any, - }; - } const { updateRequirementInDb } = await import("../db-writer.js"); const updates: Record = {}; if (params.status !== undefined) updates.status = params.status; @@ -196,58 +201,97 @@ export function registerDbTools(pi: ExtensionAPI): void { pi.registerTool(requirementUpdateTool); registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update"); - // ─── gsd_summary_save (formerly gsd_save_summary) ────────────────────── + // ─── gsd_requirement_save ───────────────────────────────────────────── - const summarySaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { + const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { const dbAvailable = await ensureDbOpen(); if (!dbAvailable) { return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save artifact." }], - details: { operation: "save_summary", error: "db_unavailable" } as any, - }; - } - const validTypes = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT"]; - if (!validTypes.includes(params.artifact_type)) { - return { - content: [{ type: "text" as const, text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${validTypes.join(", ")}` }], - details: { operation: "save_summary", error: "invalid_artifact_type" } as any, + content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save requirement." }], + details: { operation: "save_requirement", error: "db_unavailable" } as any, }; } try { - let relativePath: string; - if (params.task_id && params.slice_id) { - relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`; - } else if (params.slice_id) { - relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`; - } else { - relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`; - } - const { saveArtifactToDb } = await import("../db-writer.js"); - await saveArtifactToDb( + const { saveRequirementToDb } = await import("../db-writer.js"); + const result = await saveRequirementToDb( { - path: relativePath, - artifact_type: params.artifact_type, - content: params.content, - milestone_id: params.milestone_id, - slice_id: params.slice_id, - task_id: params.task_id, + class: params.class, + status: params.status, + description: params.description, + why: params.why, + source: params.source, + primary_owner: params.primary_owner, + supporting_slices: params.supporting_slices, + validation: params.validation, + notes: params.notes, }, process.cwd(), ); return { - content: [{ type: "text" as const, text: `Saved ${params.artifact_type} artifact to ${relativePath}` }], - details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type } as any, + content: [{ type: "text" as const, text: `Saved requirement ${result.id}` }], + details: { operation: "save_requirement", id: result.id } as any, }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); - logError("tool", `gsd_summary_save tool failed: ${msg}`, { tool: "gsd_summary_save", error: String(err) }); + logError("tool", `gsd_requirement_save tool failed: ${msg}`, { tool: "gsd_requirement_save", error: String(err) }); return { - content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }], - details: { operation: "save_summary", error: msg } as any, + content: [{ type: "text" as const, text: `Error saving requirement: ${msg}` }], + details: { operation: "save_requirement", error: msg } as any, }; } }; + const requirementSaveTool = { + name: "gsd_requirement_save", + label: "Save Requirement", + description: + "Record a new requirement to the GSD database and regenerate REQUIREMENTS.md. " + + "Requirement IDs are auto-assigned — never provide an ID manually.", + promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)", + promptGuidelines: [ + "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.", + "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.", + "class, description, why, and source are required. All other fields are optional.", + "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.", + ], + parameters: Type.Object({ + class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }), + description: Type.String({ description: "Short description of the requirement" }), + why: Type.String({ description: "Why this requirement matters" }), + source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }), + status: Type.Optional(Type.String({ description: "Status (default: 'active')" })), + primary_owner: Type.Optional(Type.String({ description: "Primary owning slice" })), + supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })), + validation: Type.Optional(Type.String({ description: "Validation criteria" })), + notes: Type.Optional(Type.String({ description: "Additional notes" })), + }), + execute: requirementSaveExecute, + renderCall(args: any, theme: any) { + let text = theme.fg("toolTitle", theme.bold("requirement_save ")); + if (args.class) text += theme.fg("accent", `[${args.class}] `); + if (args.description) text += theme.fg("muted", args.description); + return new Text(text, 0, 0); + }, + renderResult(result: any, _options: any, theme: any) { + const d = result.details; + if (result.isError || d?.error) { + return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0); + } + let text = theme.fg("success", `Requirement ${d?.id ?? ""} saved`); + text += theme.fg("dim", ` → REQUIREMENTS.md`); + return new Text(text, 0, 0); + }, + }; + + pi.registerTool(requirementSaveTool); + registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save"); + + // ─── gsd_summary_save (formerly gsd_save_summary) ────────────────────── + + const summarySaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { + return executeSummarySave(params, process.cwd()); + }; + const summarySaveTool = { name: "gsd_summary_save", label: "Save Summary", @@ -256,16 +300,17 @@ export function registerDbTools(pi: ExtensionAPI): void { "Computes the file path from milestone/slice/task IDs automatically.", promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk", promptGuidelines: [ - "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT).", + "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).", "milestone_id is required. slice_id and task_id are optional — they determine the file path.", "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.", - "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT.", + "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.", + "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.", ], parameters: Type.Object({ milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }), slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })), task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })), - artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT" }), + artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }), content: Type.String({ description: "The full markdown content of the artifact" }), }), execute: summarySaveExecute, @@ -336,8 +381,8 @@ export function registerDbTools(pi: ExtensionAPI): void { try { const { insertMilestone } = await import("../gsd-db.js"); insertMilestone({ id: milestoneId, status: "queued" }); - } catch { - // Non-fatal — the safety-net in deriveStateFromDb will catch this + } catch (e) { + logError("tool", `insertMilestone failed for ${milestoneId}: ${(e as Error).message}`); } } @@ -377,38 +422,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_plan_milestone (gsd_milestone_plan alias) ───────────────────── const planMilestoneExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot plan milestone." }], - details: { operation: "plan_milestone", error: "db_unavailable" } as any, - }; - } - try { - const { handlePlanMilestone } = await import("../tools/plan-milestone.js"); - const result = await handlePlanMilestone(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error planning milestone: ${result.error}` }], - details: { operation: "plan_milestone", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Planned milestone ${result.milestoneId}` }], - details: { - operation: "plan_milestone", - milestoneId: result.milestoneId, - roadmapPath: result.roadmapPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `plan_milestone tool failed: ${msg}`, { tool: "gsd_plan_milestone", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error planning milestone: ${msg}` }], - details: { operation: "plan_milestone", error: msg } as any, - }; - } + return executePlanMilestone(params, process.cwd()); }; const planMilestoneTool = { @@ -424,28 +438,10 @@ export function registerDbTools(pi: ExtensionAPI): void { "Use the canonical name gsd_plan_milestone; gsd_milestone_plan is only an alias.", ], parameters: Type.Object({ + // ── Core identification + content (required) ────────────────────── milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }), title: Type.String({ description: "Milestone title" }), - status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })), - dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Milestone dependencies" })), vision: Type.String({ description: "Milestone vision" }), - successCriteria: Type.Array(Type.String(), { description: "Top-level success criteria bullets" }), - keyRisks: Type.Array(Type.Object({ - risk: Type.String({ description: "Risk statement" }), - whyItMatters: Type.String({ description: "Why the risk matters" }), - }), { description: "Structured risk entries" }), - proofStrategy: Type.Array(Type.Object({ - riskOrUnknown: Type.String({ description: "Risk or unknown to retire" }), - retireIn: Type.String({ description: "Where it will be retired" }), - whatWillBeProven: Type.String({ description: "What proof will be produced" }), - }), { description: "Structured proof strategy entries" }), - verificationContract: Type.String({ description: "Verification contract text" }), - verificationIntegration: Type.String({ description: "Integration verification text" }), - verificationOperational: Type.String({ description: "Operational verification text" }), - verificationUat: Type.String({ description: "UAT verification text" }), - definitionOfDone: Type.Array(Type.String(), { description: "Definition of done bullets" }), - requirementCoverage: Type.String({ description: "Requirement coverage text" }), - boundaryMapMarkdown: Type.String({ description: "Boundary map markdown block" }), slices: Type.Array(Type.Object({ sliceId: Type.String({ description: "Slice ID (e.g. S01)" }), title: Type.String({ description: "Slice title" }), @@ -458,6 +454,26 @@ export function registerDbTools(pi: ExtensionAPI): void { integrationClosure: Type.String({ description: "Slice integration closure" }), observabilityImpact: Type.String({ description: "Slice observability impact" }), }), { description: "Planned slices for the milestone" }), + // ── Enrichment metadata (optional — defaults to empty) ──────────── + status: Type.Optional(Type.String({ description: "Milestone status (defaults to active)" })), + dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Milestone dependencies" })), + successCriteria: Type.Optional(Type.Array(Type.String(), { description: "Top-level success criteria bullets" })), + keyRisks: Type.Optional(Type.Array(Type.Object({ + risk: Type.String({ description: "Risk statement" }), + whyItMatters: Type.String({ description: "Why the risk matters" }), + }), { description: "Structured risk entries" })), + proofStrategy: Type.Optional(Type.Array(Type.Object({ + riskOrUnknown: Type.String({ description: "Risk or unknown to retire" }), + retireIn: Type.String({ description: "Where it will be retired" }), + whatWillBeProven: Type.String({ description: "What proof will be produced" }), + }), { description: "Structured proof strategy entries" })), + verificationContract: Type.Optional(Type.String({ description: "Verification contract text" })), + verificationIntegration: Type.Optional(Type.String({ description: "Integration verification text" })), + verificationOperational: Type.Optional(Type.String({ description: "Operational verification text" })), + verificationUat: Type.Optional(Type.String({ description: "UAT verification text" })), + definitionOfDone: Type.Optional(Type.Array(Type.String(), { description: "Definition of done bullets" })), + requirementCoverage: Type.Optional(Type.String({ description: "Requirement coverage text" })), + boundaryMapMarkdown: Type.Optional(Type.String({ description: "Boundary map markdown block" })), }), execute: planMilestoneExecute, }; @@ -468,40 +484,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_plan_slice (gsd_slice_plan alias) ───────────────────────────── const planSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot plan slice." }], - details: { operation: "plan_slice", error: "db_unavailable" } as any, - }; - } - try { - const { handlePlanSlice } = await import("../tools/plan-slice.js"); - const result = await handlePlanSlice(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error planning slice: ${result.error}` }], - details: { operation: "plan_slice", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Planned slice ${result.sliceId} (${result.milestoneId})` }], - details: { - operation: "plan_slice", - milestoneId: result.milestoneId, - sliceId: result.sliceId, - planPath: result.planPath, - taskPlanPaths: result.taskPlanPaths, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `plan_slice tool failed: ${msg}`, { tool: "gsd_plan_slice", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error planning slice: ${msg}` }], - details: { operation: "plan_slice", error: msg } as any, - }; - } + return executePlanSlice(params, process.cwd()); }; const planSliceTool = { @@ -517,13 +500,10 @@ export function registerDbTools(pi: ExtensionAPI): void { "Use the canonical name gsd_plan_slice; gsd_slice_plan is only an alias.", ], parameters: Type.Object({ + // ── Core identification + content (required) ────────────────────── milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }), sliceId: Type.String({ description: "Slice ID (e.g. S01)" }), goal: Type.String({ description: "Slice goal" }), - successCriteria: Type.String({ description: "Slice success criteria block" }), - proofLevel: Type.String({ description: "Slice proof level" }), - integrationClosure: Type.String({ description: "Slice integration closure" }), - observabilityImpact: Type.String({ description: "Slice observability impact" }), tasks: Type.Array(Type.Object({ taskId: Type.String({ description: "Task ID (e.g. T01)" }), title: Type.String({ description: "Task title" }), @@ -535,6 +515,11 @@ export function registerDbTools(pi: ExtensionAPI): void { expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }), observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })), }), { description: "Planned tasks for the slice" }), + // ── Enrichment metadata (optional — defaults to empty) ──────────── + successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })), + proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })), + integrationClosure: Type.Optional(Type.String({ description: "Slice integration closure" })), + observabilityImpact: Type.Optional(Type.String({ description: "Slice observability impact" })), }), execute: planSliceExecute, }; @@ -615,40 +600,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_task_complete (gsd_complete_task alias) ──────────────────────── const taskCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot complete task." }], - details: { operation: "complete_task", error: "db_unavailable" } as any, - }; - } - try { - const { handleCompleteTask } = await import("../tools/complete-task.js"); - const result = await handleCompleteTask(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error completing task: ${result.error}` }], - details: { operation: "complete_task", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Completed task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }], - details: { - operation: "complete_task", - taskId: result.taskId, - sliceId: result.sliceId, - milestoneId: result.milestoneId, - summaryPath: result.summaryPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `complete_task tool failed: ${msg}`, { tool: "gsd_task_complete", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error completing task: ${msg}` }], - details: { operation: "complete_task", error: msg } as any, - }; - } + return executeTaskComplete(params, process.cwd()); }; const taskCompleteTool = { @@ -666,26 +618,31 @@ export function registerDbTools(pi: ExtensionAPI): void { "Idempotent — calling with the same params twice will upsert (INSERT OR REPLACE) without error.", ], parameters: Type.Object({ + // ── Core identification + content (required) ────────────────────── taskId: Type.String({ description: "Task ID (e.g. T01)" }), sliceId: Type.String({ description: "Slice ID (e.g. S01)" }), milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }), oneLiner: Type.String({ description: "One-line summary of what was accomplished" }), narrative: Type.String({ description: "Detailed narrative of what happened during the task" }), verification: Type.String({ description: "What was verified and how — commands run, tests passed, behavior confirmed" }), - deviations: Type.String({ description: "Deviations from the task plan, or 'None.'" }), - knownIssues: Type.String({ description: "Known issues discovered but not fixed, or 'None.'" }), - keyFiles: Type.Array(Type.String(), { description: "List of key files created or modified" }), - keyDecisions: Type.Array(Type.String(), { description: "List of key decisions made during this task" }), - blockerDiscovered: Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" }), - verificationEvidence: Type.Array( - Type.Object({ - command: Type.String({ description: "Verification command that was run" }), - exitCode: Type.Number({ description: "Exit code of the command" }), - verdict: Type.String({ description: "Pass/fail verdict (e.g. '✅ pass', '❌ fail')" }), - durationMs: Type.Number({ description: "Duration of the command in milliseconds" }), - }), + // ── Enrichment metadata (optional — defaults to empty) ──────────── + deviations: Type.Optional(Type.String({ description: "Deviations from the task plan, or 'None.'" })), + knownIssues: Type.Optional(Type.String({ description: "Known issues discovered but not fixed, or 'None.'" })), + keyFiles: Type.Optional(Type.Array(Type.String(), { description: "List of key files created or modified" })), + keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "List of key decisions made during this task" })), + blockerDiscovered: Type.Optional(Type.Boolean({ description: "Whether a plan-invalidating blocker was discovered" })), + verificationEvidence: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + command: Type.String({ description: "Verification command that was run" }), + exitCode: Type.Number({ description: "Exit code of the command" }), + verdict: Type.String({ description: "Pass/fail verdict (e.g. '✅ pass', '❌ fail')" }), + durationMs: Type.Number({ description: "Duration of the command in milliseconds" }), + }), + Type.String({ description: "Fallback: verification summary string" }), + ]), { description: "Array of verification evidence entries" }, - ), + )), }), execute: taskCompleteExecute, }; @@ -696,40 +653,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_slice_complete (gsd_complete_slice alias) ───────────────────── const sliceCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot complete slice." }], - details: { operation: "complete_slice", error: "db_unavailable" } as any, - }; - } - try { - const { handleCompleteSlice } = await import("../tools/complete-slice.js"); - const result = await handleCompleteSlice(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error completing slice: ${result.error}` }], - details: { operation: "complete_slice", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Completed slice ${result.sliceId} (${result.milestoneId})` }], - details: { - operation: "complete_slice", - sliceId: result.sliceId, - milestoneId: result.milestoneId, - summaryPath: result.summaryPath, - uatPath: result.uatPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `complete_slice tool failed: ${msg}`, { tool: "gsd_slice_complete", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error completing slice: ${msg}` }], - details: { operation: "complete_slice", error: msg } as any, - }; - } + return executeSliceComplete(params, process.cwd()); }; const sliceCompleteTool = { @@ -746,59 +670,76 @@ export function registerDbTools(pi: ExtensionAPI): void { "Idempotent — calling with the same params twice will not crash.", ], parameters: Type.Object({ + // ── Core identification + content (required) ────────────────────── sliceId: Type.String({ description: "Slice ID (e.g. S01)" }), milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }), sliceTitle: Type.String({ description: "Title of the slice" }), oneLiner: Type.String({ description: "One-line summary of what the slice accomplished" }), narrative: Type.String({ description: "Detailed narrative of what happened across all tasks" }), verification: Type.String({ description: "What was verified across all tasks" }), - deviations: Type.String({ description: "Deviations from the slice plan, or 'None.'" }), - knownLimitations: Type.String({ description: "Known limitations or gaps, or 'None.'" }), - followUps: Type.String({ description: "Follow-up work discovered during execution, or 'None.'" }), - keyFiles: Type.Array(Type.String(), { description: "Key files created or modified" }), - keyDecisions: Type.Array(Type.String(), { description: "Key decisions made during this slice" }), - patternsEstablished: Type.Array(Type.String(), { description: "Patterns established by this slice" }), - observabilitySurfaces: Type.Array(Type.String(), { description: "Observability surfaces added" }), - provides: Type.Array(Type.String(), { description: "What this slice provides to downstream slices" }), - requirementsSurfaced: Type.Array(Type.String(), { description: "New requirements surfaced" }), - drillDownPaths: Type.Array(Type.String(), { description: "Paths to task summaries for drill-down" }), - affects: Type.Array(Type.String(), { description: "Downstream slices affected" }), - requirementsAdvanced: Type.Array( - Type.Object({ - id: Type.String({ description: "Requirement ID" }), - how: Type.String({ description: "How it was advanced" }), - }), - { description: "Requirements advanced by this slice" }, - ), - requirementsValidated: Type.Array( - Type.Object({ - id: Type.String({ description: "Requirement ID" }), - proof: Type.String({ description: "What proof validates it" }), - }), - { description: "Requirements validated by this slice" }, - ), - requirementsInvalidated: Type.Array( - Type.Object({ - id: Type.String({ description: "Requirement ID" }), - what: Type.String({ description: "What changed" }), - }), - { description: "Requirements invalidated or re-scoped" }, - ), - filesModified: Type.Array( - Type.Object({ - path: Type.String({ description: "File path" }), - description: Type.String({ description: "What changed" }), - }), - { description: "Files modified with descriptions" }, - ), - requires: Type.Array( - Type.Object({ - slice: Type.String({ description: "Dependency slice ID" }), - provides: Type.String({ description: "What was consumed from it" }), - }), - { description: "Upstream slice dependencies consumed" }, - ), uatContent: Type.String({ description: "UAT test content (markdown body)" }), + // ── Enrichment metadata (optional — defaults to empty) ──────────── + deviations: Type.Optional(Type.String({ description: "Deviations from the slice plan, or 'None.'" })), + knownLimitations: Type.Optional(Type.String({ description: "Known limitations or gaps, or 'None.'" })), + followUps: Type.Optional(Type.String({ description: "Follow-up work discovered during execution, or 'None.'" })), + keyFiles: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Key files created or modified" })), + keyDecisions: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Key decisions made during this slice" })), + patternsEstablished: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Patterns established by this slice" })), + observabilitySurfaces: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Observability surfaces added" })), + provides: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "What this slice provides to downstream slices" })), + requirementsSurfaced: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "New requirements surfaced" })), + drillDownPaths: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Paths to task summaries for drill-down" })), + affects: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Downstream slices affected" })), + requirementsAdvanced: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + id: Type.String({ description: "Requirement ID" }), + how: Type.String({ description: "How it was advanced" }), + }), + Type.String({ description: "Fallback: 'ID — how' string" }), + ]), + { description: "Requirements advanced by this slice" }, + )), + requirementsValidated: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + id: Type.String({ description: "Requirement ID" }), + proof: Type.String({ description: "What proof validates it" }), + }), + Type.String({ description: "Fallback: 'ID — proof' string" }), + ]), + { description: "Requirements validated by this slice" }, + )), + requirementsInvalidated: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + id: Type.String({ description: "Requirement ID" }), + what: Type.String({ description: "What changed" }), + }), + Type.String({ description: "Fallback: 'ID — what' string" }), + ]), + { description: "Requirements invalidated or re-scoped" }, + )), + filesModified: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + path: Type.String({ description: "File path" }), + description: Type.String({ description: "What changed" }), + }), + Type.String({ description: "Fallback: file path string" }), + ]), + { description: "Files modified with descriptions" }, + )), + requires: Type.Optional(Type.Array( + Type.Union([ + Type.Object({ + slice: Type.String({ description: "Dependency slice ID" }), + provides: Type.String({ description: "What was consumed from it" }), + }), + Type.String({ description: "Fallback: slice ID string" }), + ]), + { description: "Upstream slice dependencies consumed" }, + )), }), execute: sliceCompleteExecute, }; @@ -806,43 +747,100 @@ export function registerDbTools(pi: ExtensionAPI): void { pi.registerTool(sliceCompleteTool); registerAlias(pi, sliceCompleteTool, "gsd_complete_slice", "gsd_slice_complete"); - // ─── gsd_complete_milestone ──────────────────────────────────────────── + // ─── gsd_skip_slice (#3477 / #3487) ─────────────────────────────────── - const milestoneCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { + const skipSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { const dbAvailable = await ensureDbOpen(); if (!dbAvailable) { return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot complete milestone." }], - details: { operation: "complete_milestone", error: "db_unavailable" } as any, + content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot skip slice." }], + details: { operation: "skip_slice", error: "db_unavailable" } as any, }; } try { - const { handleCompleteMilestone } = await import("../tools/complete-milestone.js"); - const result = await handleCompleteMilestone(params, process.cwd()); - if ("error" in result) { + const { getSlice, updateSliceStatus } = await import("../gsd-db.js"); + const { invalidateStateCache } = await import("../state.js"); + + const slice = getSlice(params.milestoneId, params.sliceId); + if (!slice) { return { - content: [{ type: "text" as const, text: `Error completing milestone: ${result.error}` }], - details: { operation: "complete_milestone", error: result.error } as any, + content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} not found in milestone ${params.milestoneId}` }], + details: { operation: "skip_slice", error: "slice_not_found" } as any, }; } + + if (slice.status === "complete" || slice.status === "done") { + return { + content: [{ type: "text" as const, text: `Error: Slice ${params.sliceId} is already complete — cannot skip.` }], + details: { operation: "skip_slice", error: "already_complete" } as any, + }; + } + + if (slice.status === "skipped") { + return { + content: [{ type: "text" as const, text: `Slice ${params.sliceId} is already skipped.` }], + details: { operation: "skip_slice", sliceId: params.sliceId, milestoneId: params.milestoneId } as any, + }; + } + + updateSliceStatus(params.milestoneId, params.sliceId, "skipped"); + invalidateStateCache(); + + // Rebuild STATE.md so it reflects the skip immediately (#3477). + // Without this, /gsd auto reads stale STATE.md and resumes the skipped slice. + try { + const basePath = process.cwd(); + const { rebuildState } = await import("../doctor.js"); + await rebuildState(basePath); + } catch (err) { + logError("tool", `skip_slice rebuildState failed: ${(err as Error).message}`, { tool: "gsd_skip_slice" }); + } + return { - content: [{ type: "text" as const, text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }], + content: [{ type: "text" as const, text: `Skipped slice ${params.sliceId} (${params.milestoneId}). Reason: ${params.reason ?? "User-directed skip"}. Auto-mode will advance past this slice.` }], details: { - operation: "complete_milestone", - milestoneId: result.milestoneId, - summaryPath: result.summaryPath, + operation: "skip_slice", + sliceId: params.sliceId, + milestoneId: params.milestoneId, + reason: params.reason, } as any, }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); - logError("tool", `complete_milestone tool failed: ${msg}`, { tool: "gsd_complete_milestone", error: String(err) }); + logError("tool", `skip_slice tool failed: ${msg}`, { tool: "gsd_skip_slice", error: String(err) }); return { - content: [{ type: "text" as const, text: `Error completing milestone: ${msg}` }], - details: { operation: "complete_milestone", error: msg } as any, + content: [{ type: "text" as const, text: `Error skipping slice: ${msg}` }], + details: { operation: "skip_slice", error: msg } as any, }; } }; + pi.registerTool({ + name: "gsd_skip_slice", + label: "Skip Slice", + description: + "Mark a slice as skipped so auto-mode advances past it without executing. " + + "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.", + promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)", + promptGuidelines: [ + "Use gsd_skip_slice when a slice should be bypassed — descoped, superseded, or no longer relevant.", + "Cannot skip a slice that is already complete.", + "Skipped slices satisfy downstream dependencies just like completed slices.", + ], + parameters: Type.Object({ + sliceId: Type.String({ description: "Slice ID (e.g. S02)" }), + milestoneId: Type.String({ description: "Milestone ID (e.g. M003)" }), + reason: Type.Optional(Type.String({ description: "Reason for skipping this slice" })), + }), + execute: skipSliceExecute, + }); + + // ─── gsd_complete_milestone ──────────────────────────────────────────── + + const milestoneCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { + return executeCompleteMilestone(params, process.cwd()); + }; + const milestoneCompleteTool = { name: "gsd_complete_milestone", label: "Complete Milestone", @@ -857,19 +855,21 @@ export function registerDbTools(pi: ExtensionAPI): void { "On success, returns summaryPath where the MILESTONE-SUMMARY.md was written.", ], parameters: Type.Object({ + // ── Core identification + content (required) ────────────────────── milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }), title: Type.String({ description: "Milestone title" }), oneLiner: Type.String({ description: "One-sentence summary of what the milestone achieved" }), narrative: Type.String({ description: "Detailed narrative of what happened during the milestone" }), - successCriteriaResults: Type.String({ description: "Markdown detailing how each success criterion was met or not met" }), - definitionOfDoneResults: Type.String({ description: "Markdown detailing how each definition-of-done item was met" }), - requirementOutcomes: Type.String({ description: "Markdown detailing requirement status transitions with evidence" }), - keyDecisions: Type.Array(Type.String(), { description: "Key architectural/pattern decisions made during the milestone" }), - keyFiles: Type.Array(Type.String(), { description: "Key files created or modified during the milestone" }), - lessonsLearned: Type.Array(Type.String(), { description: "Lessons learned during the milestone" }), + verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }), + // ── Enrichment metadata (optional — defaults to empty) ──────────── + successCriteriaResults: Type.Optional(Type.String({ description: "Markdown detailing how each success criterion was met or not met" })), + definitionOfDoneResults: Type.Optional(Type.String({ description: "Markdown detailing how each definition-of-done item was met" })), + requirementOutcomes: Type.Optional(Type.String({ description: "Markdown detailing requirement status transitions with evidence" })), + keyDecisions: Type.Optional(Type.Array(Type.String(), { description: "Key architectural/pattern decisions made during the milestone" })), + keyFiles: Type.Optional(Type.Array(Type.String(), { description: "Key files created or modified during the milestone" })), + lessonsLearned: Type.Optional(Type.Array(Type.String(), { description: "Lessons learned during the milestone" })), followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })), deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })), - verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }), }), execute: milestoneCompleteExecute, }; @@ -880,39 +880,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_validate_milestone (gsd_milestone_validate alias) ───────────── const milestoneValidateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot validate milestone." }], - details: { operation: "validate_milestone", error: "db_unavailable" } as any, - }; - } - try { - const { handleValidateMilestone } = await import("../tools/validate-milestone.js"); - const result = await handleValidateMilestone(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error validating milestone: ${result.error}` }], - details: { operation: "validate_milestone", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Validated milestone ${result.milestoneId} — verdict: ${result.verdict}. Written to ${result.validationPath}` }], - details: { - operation: "validate_milestone", - milestoneId: result.milestoneId, - verdict: result.verdict, - validationPath: result.validationPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `validate_milestone tool failed: ${msg}`, { tool: "gsd_validate_milestone", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error validating milestone: ${msg}` }], - details: { operation: "validate_milestone", error: msg } as any, - }; - } + return executeValidateMilestone(params, process.cwd()); }; const milestoneValidateTool = { @@ -949,40 +917,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_replan_slice (gsd_slice_replan alias) ───────────────────────── const replanSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot replan slice." }], - details: { operation: "replan_slice", error: "db_unavailable" } as any, - }; - } - try { - const { handleReplanSlice } = await import("../tools/replan-slice.js"); - const result = await handleReplanSlice(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error replanning slice: ${result.error}` }], - details: { operation: "replan_slice", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Replanned slice ${result.sliceId} (${result.milestoneId})` }], - details: { - operation: "replan_slice", - milestoneId: result.milestoneId, - sliceId: result.sliceId, - replanPath: result.replanPath, - planPath: result.planPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `replan_slice tool failed: ${msg}`, { tool: "gsd_replan_slice", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error replanning slice: ${msg}` }], - details: { operation: "replan_slice", error: msg } as any, - }; - } + return executeReplanSlice(params, process.cwd()); }; const replanSliceTool = { @@ -1029,40 +964,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ───────────────── const reassessRoadmapExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reassess roadmap." }], - details: { operation: "reassess_roadmap", error: "db_unavailable" } as any, - }; - } - try { - const { handleReassessRoadmap } = await import("../tools/reassess-roadmap.js"); - const result = await handleReassessRoadmap(params, process.cwd()); - if ("error" in result) { - return { - content: [{ type: "text" as const, text: `Error reassessing roadmap: ${result.error}` }], - details: { operation: "reassess_roadmap", error: result.error } as any, - }; - } - return { - content: [{ type: "text" as const, text: `Reassessed roadmap for milestone ${result.milestoneId} after ${result.completedSliceId}` }], - details: { - operation: "reassess_roadmap", - milestoneId: result.milestoneId, - completedSliceId: result.completedSliceId, - assessmentPath: result.assessmentPath, - roadmapPath: result.roadmapPath, - } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `reassess_roadmap tool failed: ${msg}`, { tool: "gsd_reassess_roadmap", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error reassessing roadmap: ${msg}` }], - details: { operation: "reassess_roadmap", error: msg } as any, - }; - } + return executeReassessRoadmap(params, process.cwd()); }; const reassessRoadmapTool = { @@ -1117,52 +1019,7 @@ export function registerDbTools(pi: ExtensionAPI): void { // ─── gsd_save_gate_result ────────────────────────────────────────────── const saveGateResultExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => { - const dbAvailable = await ensureDbOpen(); - if (!dbAvailable) { - return { - content: [{ type: "text" as const, text: "Error: GSD database is not available." }], - details: { operation: "save_gate_result", error: "db_unavailable" } as any, - }; - } - const validGates = ["Q3", "Q4", "Q5", "Q6", "Q7", "Q8"]; - if (!validGates.includes(params.gateId)) { - return { - content: [{ type: "text" as const, text: `Error: Invalid gateId "${params.gateId}". Must be one of: ${validGates.join(", ")}` }], - details: { operation: "save_gate_result", error: "invalid_gate_id" } as any, - }; - } - const validVerdicts = ["pass", "flag", "omitted"]; - if (!validVerdicts.includes(params.verdict)) { - return { - content: [{ type: "text" as const, text: `Error: Invalid verdict "${params.verdict}". Must be one of: ${validVerdicts.join(", ")}` }], - details: { operation: "save_gate_result", error: "invalid_verdict" } as any, - }; - } - try { - const { saveGateResult } = await import("../gsd-db.js"); - const { invalidateStateCache } = await import("../state.js"); - saveGateResult({ - milestoneId: params.milestoneId, - sliceId: params.sliceId, - gateId: params.gateId, - taskId: params.taskId ?? "", - verdict: params.verdict, - rationale: params.rationale, - findings: params.findings ?? "", - }); - invalidateStateCache(); - return { - content: [{ type: "text" as const, text: `Gate ${params.gateId} result saved: verdict=${params.verdict}` }], - details: { operation: "save_gate_result", gateId: params.gateId, verdict: params.verdict } as any, - }; - } catch (err) { - const msg = err instanceof Error ? err.message : String(err); - logError("tool", `gsd_save_gate_result failed: ${msg}`, { tool: "gsd_save_gate_result", error: String(err) }); - return { - content: [{ type: "text" as const, text: `Error saving gate result: ${msg}` }], - details: { operation: "save_gate_result", error: msg } as any, - }; - } + return executeSaveGateResult(params, process.cwd()); }; const saveGateResultTool = { diff --git a/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts b/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts index a261555a3..b4371f483 100644 --- a/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts +++ b/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts @@ -5,7 +5,7 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent"; import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent"; import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js"; -import { setLogBasePath } from "../workflow-logger.js"; +import { setLogBasePath, logWarning } from "../workflow-logger.js"; /** * Resolve the correct DB path for the current working directory. @@ -32,15 +32,52 @@ export function resolveProjectRootDbPath(basePath: string): string { return join(projectRoot, ".gsd", "gsd.db"); } + // External-state layout: ~/.gsd/projects//worktrees//... + // Resolve to ~/.gsd/projects//gsd.db (the canonical project DB) (#2952). + // Must be checked before the generic symlink-resolved handler: both match + // /.gsd/projects//worktrees/ but require different resolution targets. + const extRe = /[/\\]\.gsd[/\\]projects[/\\][a-f0-9]+[/\\]worktrees(?:[/\\]|$)/; + const extMatch = extRe.exec(basePath); + if (extMatch) { + const matchStr = extMatch[0]; + // Find the "/worktrees" portion within the match and slice up to it + const wtIdx = matchStr.search(/[/\\]worktrees(?:[/\\]|$)/); + const projectStateRoot = basePath.slice(0, extMatch.index + wtIdx); + return join(projectStateRoot, "gsd.db"); + } + + // Symlink-resolved layout: /.gsd/projects//worktrees/M001/... + // The project root is everything before /.gsd/projects/ (#2517) + const symlinkMarker = `${sep}.gsd${sep}projects${sep}`; + const symlinkIdx = basePath.indexOf(symlinkMarker); + if (symlinkIdx !== -1) { + const afterProjects = basePath.slice(symlinkIdx + symlinkMarker.length); + // Expect: /worktrees/... + const worktreeSeg = `${sep}worktrees${sep}`; + if (afterProjects.includes(worktreeSeg)) { + const projectRoot = basePath.slice(0, symlinkIdx); + return join(projectRoot, ".gsd", "gsd.db"); + } + } + + // Forward-slash variant for symlink-resolved layout + const fwdSymlinkMarker = "/.gsd/projects/"; + const fwdSymlinkIdx = basePath.indexOf(fwdSymlinkMarker); + if (fwdSymlinkIdx !== -1) { + const afterProjects = basePath.slice(fwdSymlinkIdx + fwdSymlinkMarker.length); + if (afterProjects.includes("/worktrees/")) { + const projectRoot = basePath.slice(0, fwdSymlinkIdx); + return join(projectRoot, ".gsd", "gsd.db"); + } + } + + return join(basePath, ".gsd", "gsd.db"); } -export async function ensureDbOpen(): Promise { +export async function ensureDbOpen(basePath: string = process.cwd()): Promise { try { const db = await import("../gsd-db.js"); - if (db.isDbAvailable()) return true; - - const basePath = process.cwd(); const dbPath = resolveProjectRootDbPath(basePath); const gsdDir = join(basePath, ".gsd"); @@ -67,9 +104,7 @@ export async function ensureDbOpen(): Promise { const { migrateFromMarkdown } = await import("../md-importer.js"); migrateFromMarkdown(basePath); } catch (err) { - process.stderr.write( - `gsd-db: ensureDbOpen auto-migration failed: ${(err as Error).message}\n`, - ); + logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${(err as Error).message}`); } } return opened; @@ -81,8 +116,10 @@ export async function ensureDbOpen(): Promise { return opened; } + logWarning("bootstrap", "ensureDbOpen failed — no .gsd directory found"); return false; - } catch { + } catch (err) { + logWarning("bootstrap", `ensureDbOpen failed: ${(err as Error).message ?? String(err)}`); return false; } } @@ -154,4 +191,3 @@ export function registerDynamicTools(pi: ExtensionAPI): void { }, } as any); } - diff --git a/src/resources/extensions/gsd/bootstrap/journal-tools.ts b/src/resources/extensions/gsd/bootstrap/journal-tools.ts index 7262d0b6d..9a1aa9dec 100644 --- a/src/resources/extensions/gsd/bootstrap/journal-tools.ts +++ b/src/resources/extensions/gsd/bootstrap/journal-tools.ts @@ -2,6 +2,7 @@ import { Type } from "@sinclair/typebox"; import type { ExtensionAPI } from "@gsd/pi-coding-agent"; import { queryJournal } from "../journal.js"; +import { logWarning } from "../workflow-logger.js"; export function registerJournalTools(pi: ExtensionAPI): void { pi.registerTool({ @@ -51,7 +52,7 @@ export function registerJournalTools(pi: ExtensionAPI): void { }; } catch (err) { const msg = err instanceof Error ? err.message : String(err); - process.stderr.write(`gsd-journal: gsd_journal_query tool failed: ${msg}\n`); + logWarning("tool", `gsd_journal_query tool failed: ${msg}`); return { content: [{ type: "text" as const, text: `Error querying journal: ${msg}` }], details: { operation: "journal_query", error: msg } as any, diff --git a/src/resources/extensions/gsd/bootstrap/notify-interceptor.ts b/src/resources/extensions/gsd/bootstrap/notify-interceptor.ts new file mode 100644 index 000000000..2ac10cef3 --- /dev/null +++ b/src/resources/extensions/gsd/bootstrap/notify-interceptor.ts @@ -0,0 +1,34 @@ +// GSD Extension — Notify Interceptor +// Wraps ctx.ui.notify() in-place to persist every notification through the +// notification store. Uses a WeakSet to prevent double-wrapping and handle +// UI context replacement on /reload gracefully. + +import type { ExtensionContext } from "@gsd/pi-coding-agent"; + +import { appendNotification, type NotifySeverity } from "../notification-store.js"; + +// Track which ui context objects have been wrapped to prevent double-install. +// WeakSet allows GC to collect replaced uiContext instances after /reload. +const _wrappedContexts = new WeakSet(); + +/** + * Install the notify interceptor on a context's UI object. + * Mutates ctx.ui.notify in place — the original is called after persistence. + * Safe to call multiple times; no-ops if already installed on the same ui object. + */ +export function installNotifyInterceptor(ctx: ExtensionContext): void { + if (_wrappedContexts.has(ctx.ui)) return; + + const originalNotify = ctx.ui.notify.bind(ctx.ui); + + (ctx.ui as any).notify = (message: string, type?: "info" | "warning" | "error" | "success"): void => { + try { + appendNotification(message, (type ?? "info") as NotifySeverity, "notify"); + } catch { + // Non-fatal — never let persistence break the UI + } + originalNotify(message, type); + }; + + _wrappedContexts.add(ctx.ui); +} diff --git a/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts b/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts index 35efdcbf5..d5f01f96d 100644 --- a/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts +++ b/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts @@ -5,6 +5,7 @@ import type { } from "@gsd/pi-coding-agent"; import { getAutoDashboardData, startAuto, type AutoDashboardData } from "../auto.js"; +import { resetTransientRetryState } from "./agent-end-recovery.js"; type AutoResumeSnapshot = Pick; @@ -42,6 +43,11 @@ export async function resumeAutoAfterProviderDelay( return "missing-base"; } + // Reset the transient retry counter before restarting — without this, + // consecutiveTransientCount accumulates across pause/resume cycles and + // permanently locks out auto-resume after MAX_TRANSIENT_AUTO_RESUMES errors. + resetTransientRetryState(); + await deps.startAuto( ctx as ExtensionCommandContext, pi, diff --git a/src/resources/extensions/gsd/bootstrap/query-tools.ts b/src/resources/extensions/gsd/bootstrap/query-tools.ts new file mode 100644 index 000000000..2741af75f --- /dev/null +++ b/src/resources/extensions/gsd/bootstrap/query-tools.ts @@ -0,0 +1,34 @@ +// GSD2 — Read-only query tools exposing DB state to the LLM via the WAL connection + +import { Type } from "@sinclair/typebox"; +import type { ExtensionAPI } from "@gsd/pi-coding-agent"; +import { ensureDbOpen } from "./dynamic-tools.js"; +import { executeMilestoneStatus } from "../tools/workflow-tool-executors.js"; + +export function registerQueryTools(pi: ExtensionAPI): void { + pi.registerTool({ + name: "gsd_milestone_status", + label: "Milestone Status", + description: + "Read the current status of a milestone and all its slices from the GSD database. " + + "Returns milestone metadata, per-slice status, and task counts per slice. " + + "Use this instead of querying .gsd/gsd.db directly via sqlite3 or better-sqlite3.", + promptSnippet: "Get milestone status, slice statuses, and task counts for a given milestoneId", + promptGuidelines: [ + "Use this tool — not sqlite3 or better-sqlite3 — to inspect milestone or slice state from the DB.", + ], + parameters: Type.Object({ + milestoneId: Type.String({ description: "Milestone ID to query (e.g. M001)" }), + }), + async execute(_toolCallId, params, _signal, _onUpdate, _ctx) { + const dbAvailable = await ensureDbOpen(); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot read milestone status." }], + details: { operation: "milestone_status", error: "db_unavailable" }, + }; + } + return executeMilestoneStatus(params); + }, + }); +} diff --git a/src/resources/extensions/gsd/bootstrap/register-extension.ts b/src/resources/extensions/gsd/bootstrap/register-extension.ts index 1e1b62f5a..024d4a72d 100644 --- a/src/resources/extensions/gsd/bootstrap/register-extension.ts +++ b/src/resources/extensions/gsd/bootstrap/register-extension.ts @@ -1,3 +1,5 @@ +// GSD2 — Extension registration: wires all GSD tools, commands, and hooks into pi + import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent"; import { registerGSDCommand } from "../commands.js"; @@ -6,6 +8,7 @@ import { registerWorktreeCommand } from "../worktree-command.js"; import { registerDbTools } from "./db-tools.js"; import { registerDynamicTools } from "./dynamic-tools.js"; import { registerJournalTools } from "./journal-tools.js"; +import { registerQueryTools } from "./query-tools.js"; import { registerHooks } from "./register-hooks.js"; import { registerShortcuts } from "./register-shortcuts.js"; @@ -33,7 +36,10 @@ function installEpipeGuard(): void { if (handleRecoverableExtensionProcessError(err)) { return; } - throw err; + // Log unhandled errors instead of re-throwing — throwing inside an + // uncaughtException handler is a fatal double-fault in Node.js (#3163). + process.stderr.write(`[gsd] uncaught extension error (non-fatal): ${err.message}\n`); + if (err.stack) process.stderr.write(`${err.stack}\n`); }; process.on("uncaughtException", _gsdEpipeGuard); } @@ -56,6 +62,7 @@ export function registerGsdExtension(pi: ExtensionAPI): void { registerDynamicTools(pi); registerDbTools(pi); registerJournalTools(pi); + registerQueryTools(pi); registerShortcuts(pi); registerHooks(pi); } diff --git a/src/resources/extensions/gsd/bootstrap/register-hooks.ts b/src/resources/extensions/gsd/bootstrap/register-hooks.ts index 4fd7a1292..438d4d9b0 100644 --- a/src/resources/extensions/gsd/bootstrap/register-hooks.ts +++ b/src/resources/extensions/gsd/bootstrap/register-hooks.ts @@ -6,18 +6,25 @@ import { isToolCallEventType } from "@gsd/pi-coding-agent"; import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js"; import { buildBeforeAgentStartResult } from "./system-context.js"; import { handleAgentEnd } from "./agent-end-recovery.js"; -import { clearDiscussionFlowState, isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js"; +import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js"; import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js"; +import { cleanupQuickBranch } from "../quick.js"; import { getDiscussionMilestoneId } from "../guided-flow.js"; import { loadToolApiKeys } from "../commands-config.js"; import { loadFile, saveFile, formatContinue } from "../files.js"; import { deriveState } from "../state.js"; -import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart } from "../auto.js"; +import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js"; import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js"; import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js"; import { saveActivityLog } from "../activity-log.js"; -import { startRtkStatusUpdates, stopRtkStatusUpdates } from "../rtk-status.js"; -import { rewriteCommandWithRtk } from "../../shared/rtk.js"; +import { resetAskUserQuestionsCache } from "../../ask-user-questions.js"; +import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult } from "../safety/evidence-collector.js"; +import { classifyCommand } from "../safety/destructive-guard.js"; +import { logWarning as safetyLogWarning } from "../workflow-logger.js"; +import { installNotifyInterceptor } from "./notify-interceptor.js"; +import { initNotificationStore } from "../notification-store.js"; +import { initNotificationWidget } from "../notification-widget.js"; +import { initHealthWidget } from "../health-widget.js"; // Skip the welcome screen on the very first session_start — cli.ts already // printed it before the TUI launched. Only re-print on /clear (subsequent sessions). @@ -29,19 +36,17 @@ async function syncServiceTierStatus(ctx: ExtensionContext): Promise { } export function registerHooks(pi: ExtensionAPI): void { - // Route all agent bash tool commands through RTK rewrite when opted in. - // This is a no-op when RTK is disabled or not installed. - pi.on("bash_transform", async (event) => { - const rewritten = rewriteCommandWithRtk(event.command); - if (rewritten === event.command) return undefined; - return { command: rewritten }; - }); - pi.on("session_start", async (_event, ctx) => { + initNotificationStore(process.cwd()); + installNotifyInterceptor(ctx); + initNotificationWidget(ctx); + initHealthWidget(ctx); resetWriteGateState(); resetToolCallLoopGuard(); + resetAskUserQuestionsCache(); await syncServiceTierStatus(ctx); - startRtkStatusUpdates(ctx); + const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js"); + prepareWorkflowMcpForProject(ctx, process.cwd()); // Apply show_token_cost preference (#1515) try { @@ -58,39 +63,33 @@ export function registerHooks(pi: ExtensionAPI): void { const { dirname } = await import("node:path"); const { printWelcomeScreen } = await import( join(dirname(gsdBinPath), "welcome-screen.js") - ) as { printWelcomeScreen: (opts: { version: string; modelName?: string; provider?: string }) => void }; - printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0" }); + ) as { printWelcomeScreen: (opts: { version: string; modelName?: string; provider?: string; remoteChannel?: string }) => void }; + + let remoteChannel: string | undefined; + try { + const { resolveRemoteConfig } = await import("../../remote-questions/config.js"); + const rc = resolveRemoteConfig(); + if (rc) remoteChannel = rc.channel; + } catch { /* non-fatal */ } + + printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0", remoteChannel }); } } catch { /* non-fatal */ } } loadToolApiKeys(); - try { - const [{ getRemoteConfigStatus }, { getLatestPromptSummary }] = await Promise.all([ - import("../../remote-questions/config.js"), - import("../../remote-questions/status.js"), - ]); - const status = getRemoteConfigStatus(); - const latest = getLatestPromptSummary(); - if (!status.includes("not configured")) { - const suffix = latest ? `\nLast remote prompt: ${latest.id} (${latest.status})` : ""; - ctx.ui.notify(`${status}${suffix}`, status.includes("disabled") ? "warning" : "info"); - } - } catch { - // ignore - } }); pi.on("session_switch", async (_event, ctx) => { + initNotificationStore(process.cwd()); + installNotifyInterceptor(ctx); resetWriteGateState(); resetToolCallLoopGuard(); + resetAskUserQuestionsCache(); clearDiscussionFlowState(); await syncServiceTierStatus(ctx); + const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js"); + prepareWorkflowMcpForProject(ctx, process.cwd()); loadToolApiKeys(); - startRtkStatusUpdates(ctx); - }); - - pi.on("session_fork", async (_event, ctx) => { - startRtkStatusUpdates(ctx); }); pi.on("before_agent_start", async (event, ctx: ExtensionContext) => { @@ -99,14 +98,31 @@ export function registerHooks(pi: ExtensionAPI): void { pi.on("agent_end", async (event, ctx: ExtensionContext) => { resetToolCallLoopGuard(); + resetAskUserQuestionsCache(); await handleAgentEnd(pi, event, ctx); }); + // Squash-merge quick-task branch back to the original branch after the + // agent turn completes (#2668). cleanupQuickBranch is a no-op when no + // quick-return state is pending, so this is safe to call on every turn. + pi.on("turn_end", async () => { + try { + cleanupQuickBranch(); + } catch { + // Best-effort: don't break the turn lifecycle if cleanup fails. + } + }); + pi.on("session_before_compact", async () => { - if (isAutoActive() || isAutoPaused()) { + // Only cancel compaction while auto-mode is actively running. + // Paused auto-mode should allow compaction — the user may be doing + // interactive work (#3165). + if (isAutoActive()) { return { cancel: true }; } const basePath = process.cwd(); + const { ensureDbOpen } = await import("./dynamic-tools.js"); + await ensureDbOpen(); const state = await deriveState(basePath); if (!state.activeMilestone || !state.activeSlice || !state.activeTask) return; if (state.phase !== "executing") return; @@ -139,7 +155,6 @@ export function registerHooks(pi: ExtensionAPI): void { }); pi.on("session_shutdown", async (_event, ctx: ExtensionContext) => { - stopRtkStatusUpdates(ctx); if (isParallelActive()) { try { await shutdownParallel(process.cwd()); @@ -155,12 +170,67 @@ export function registerHooks(pi: ExtensionAPI): void { }); pi.on("tool_call", async (event) => { + const discussionBasePath = process.cwd(); // ── Loop guard: block repeated identical tool calls ── const loopCheck = checkToolCallLoop(event.toolName, event.input as Record); if (loopCheck.block) { return { block: true, reason: loopCheck.reason }; } + // ── Discussion gate enforcement: track pending gate questions ───────── + // Only gate-shaped ask_user_questions calls should block execution. + // The gate stays pending until the user selects the approval option. + if (event.toolName === "ask_user_questions") { + const milestoneId = getDiscussionMilestoneId(discussionBasePath); + const inDiscussion = milestoneId !== null || isQueuePhaseActive(); + if (inDiscussion) { + const questions: any[] = (event.input as any)?.questions ?? []; + const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id; + if (typeof questionId === "string") { + setPendingGate(questionId); + } + } + } + + // ── Discussion gate enforcement: block tool calls while gate is pending ── + // If ask_user_questions was called with a gate ID but hasn't been confirmed, + // block all non-read-only tool calls to prevent the model from skipping gates. + if (getPendingGate()) { + const milestoneId = getDiscussionMilestoneId(discussionBasePath); + if (isToolCallEventType("bash", event)) { + const bashGuard = shouldBlockPendingGateBash( + event.input.command, + milestoneId, + isQueuePhaseActive(), + ); + if (bashGuard.block) return bashGuard; + } else { + const gateGuard = shouldBlockPendingGate( + event.toolName, + milestoneId, + isQueuePhaseActive(), + ); + if (gateGuard.block) return gateGuard; + } + } + + // ── Queue-mode execution guard (#2545): block source-code mutations ── + // When /gsd queue is active, the agent should only create milestones, + // not execute work. Block write/edit to non-.gsd/ paths and bash commands + // that would modify files. + if (isQueuePhaseActive()) { + let queueInput = ""; + if (isToolCallEventType("write", event)) { + queueInput = event.input.path; + } else if (isToolCallEventType("edit", event)) { + queueInput = event.input.path; + } else if (isToolCallEventType("bash", event)) { + queueInput = event.input.command; + } + const queueGuard = shouldBlockQueueExecution(event.toolName, queueInput, true); + if (queueGuard.block) return queueGuard; + } + // ── Single-writer engine: block direct writes to STATE.md ────────── // Covers write, edit, and bash tools to prevent bypass vectors. if (isToolCallEventType("write", event)) { @@ -186,26 +256,72 @@ export function registerHooks(pi: ExtensionAPI): void { const result = shouldBlockContextWrite( event.toolName, event.input.path, - getDiscussionMilestoneId(), - isDepthVerified(), + getDiscussionMilestoneId(discussionBasePath), isQueuePhaseActive(), ); if (result.block) return result; }); + // ── Safety harness: evidence collection + destructive command warnings ── + pi.on("tool_call", async (event, ctx) => { + if (!isAutoActive()) return; + safetyRecordToolCall(event.toolName, event.input as Record); + + // Destructive command classification (warn only, never block) + if (isToolCallEventType("bash", event)) { + const classification = classifyCommand(event.input.command); + if (classification.destructive) { + safetyLogWarning("safety", `destructive command: ${classification.labels.join(", ")}`, { + command: String(event.input.command).slice(0, 200), + }); + ctx.ui.notify( + `Destructive command detected: ${classification.labels.join(", ")}`, + "warning", + ); + } + } + }); + pi.on("tool_result", async (event) => { if (event.toolName !== "ask_user_questions") return; - const milestoneId = getDiscussionMilestoneId(); + const milestoneId = getDiscussionMilestoneId(process.cwd()); const queueActive = isQueuePhaseActive(); if (!milestoneId && !queueActive) return; const details = event.details as any; + + // ── Discussion gate enforcement: handle gate question responses ── + // If the result is cancelled or has no response, the pending gate stays active + // so the model is blocked from non-read-only tools until it re-asks. + // If the user responded at all (even "needs adjustment"), clear the pending gate + // because the user engaged — the prompt handles the re-ask-after-adjustment flow. + const questions: any[] = (event.input as any)?.questions ?? []; + const currentPendingGate = getPendingGate(); + if (currentPendingGate) { + if (details?.cancelled || !details?.response) { + // Gate stays pending — model will be blocked from non-read-only tools + // until it re-asks and gets a valid response + } else { + const pendingQuestion = questions.find((question) => question?.id === currentPendingGate); + if (pendingQuestion) { + const answer = details.response?.answers?.[currentPendingGate]; + if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) { + clearPendingGate(); + } + } + } + } + if (details?.cancelled || !details?.response) return; - const questions: any[] = (event.input as any)?.questions ?? []; for (const question of questions) { if (typeof question.id === "string" && question.id.includes("depth_verification")) { - markDepthVerified(); + // Only unlock the gate if the user selected the first option (confirmation). + // Cross-references against the question's defined options to reject free-form "Other" text. + const answer = details.response?.answers?.[question.id]; + if (isDepthConfirmationAnswer(answer?.selected, question.options)) { + markDepthVerified(extractDepthVerificationMilestoneId(question.id) ?? milestoneId); + } break; } } @@ -245,11 +361,23 @@ export function registerHooks(pi: ExtensionAPI): void { pi.on("tool_execution_start", async (event) => { if (!isAutoActive()) return; - markToolStart(event.toolCallId, event.toolName); + markToolStart(event.toolCallId); }); pi.on("tool_execution_end", async (event) => { markToolEnd(event.toolCallId); + // #2883: Capture tool invocation errors (malformed/truncated JSON arguments) + // so postUnitPreVerification can break the retry loop instead of re-dispatching. + if (event.isError && event.toolName.startsWith("gsd_")) { + const errorText = typeof event.result === "string" + ? event.result + : (typeof event.result?.content?.[0]?.text === "string" ? event.result.content[0].text : String(event.result)); + recordToolInvocationError(event.toolName, errorText); + } + // Safety harness: record tool execution results for evidence cross-referencing + if (isAutoActive()) { + safetyRecordToolResult(event.toolCallId, event.toolName, event.result, event.isError); + } }); pi.on("model_select", async (_event, ctx) => { @@ -257,14 +385,79 @@ export function registerHooks(pi: ExtensionAPI): void { }); pi.on("before_provider_request", async (event) => { - const modelId = event.model?.id; - if (!modelId) return; - const { getEffectiveServiceTier, supportsServiceTier } = await import("../service-tier.js"); - const tier = getEffectiveServiceTier(); - if (!tier || !supportsServiceTier(modelId)) return; const payload = event.payload as Record | null; if (!payload || typeof payload !== "object") return; + + // ── Observation Masking ───────────────────────────────────────────── + // Replace old tool results with placeholders to reduce context bloat. + // Only active during auto-mode when context_management.observation_masking is enabled. + if (isAutoActive()) { + try { + const { loadEffectiveGSDPreferences } = await import("../preferences.js"); + const prefs = loadEffectiveGSDPreferences(); + const cmConfig = prefs?.preferences.context_management; + + // Observation masking: replace old tool results with placeholders + if (cmConfig?.observation_masking !== false) { + const keepTurns = cmConfig?.observation_mask_turns ?? 8; + const { createObservationMask } = await import("../context-masker.js"); + const mask = createObservationMask(keepTurns); + const messages = payload.messages; + if (Array.isArray(messages)) { + payload.messages = mask(messages); + } + } + + // Tool result truncation: cap individual tool result content length. + // In pi-ai format, toolResult messages have role: "toolResult" and content: TextContent[]. + // Creates new objects to avoid mutating shared conversation state. + const maxChars = cmConfig?.tool_result_max_chars ?? 800; + const msgs = payload.messages; + if (Array.isArray(msgs)) { + payload.messages = msgs.map((msg: Record) => { + // Match toolResult messages (role: "toolResult", content is array of content blocks) + if (msg?.role === "toolResult" && Array.isArray(msg.content)) { + const blocks = msg.content as Array>; + const totalLen = blocks.reduce((sum: number, b) => sum + (typeof b.text === "string" ? b.text.length : 0), 0); + if (totalLen > maxChars) { + const truncated = blocks.map(b => { + if (typeof b.text === "string" && b.text.length > maxChars) { + return { ...b, text: b.text.slice(0, maxChars) + "\n…[truncated]" }; + } + return b; + }); + return { ...msg, content: truncated }; + } + } + return msg; + }); + } + } catch { /* non-fatal */ } + } + + // ── Service Tier ──────────────────────────────────────────────────── + const modelId = event.model?.id; + if (!modelId) return payload; + const { getEffectiveServiceTier, supportsServiceTier } = await import("../service-tier.js"); + const tier = getEffectiveServiceTier(); + if (!tier || !supportsServiceTier(modelId)) return payload; payload.service_tier = tier; return payload; }); + + // Capability-aware model routing hook (ADR-004) + // Extensions can override model selection by returning { modelId: "..." } + // Return undefined to let the built-in capability scoring proceed. + pi.on("before_model_select", async (_event) => { + // Default: no override — let capability scoring handle selection + return undefined; + }); + + // Tool set adaptation hook (ADR-005 Phase 4) + // Extensions can override tool set after model selection by returning { toolNames: [...] } + // Return undefined to let the built-in provider compatibility filtering proceed. + pi.on("adjust_tool_set", async (_event) => { + // Default: no override — let provider capability filtering handle tool set + return undefined; + }); } diff --git a/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts b/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts index 03156b52a..e3c947aff 100644 --- a/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts +++ b/src/resources/extensions/gsd/bootstrap/register-shortcuts.ts @@ -5,19 +5,22 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent"; import { Key } from "@gsd/pi-tui"; import { GSDDashboardOverlay } from "../dashboard-overlay.js"; +import { GSDNotificationOverlay } from "../notification-overlay.js"; import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js"; +import { projectRoot } from "../commands/context.js"; import { shortcutDesc } from "../../shared/mod.js"; export function registerShortcuts(pi: ExtensionAPI): void { pi.registerShortcut(Key.ctrlAlt("g"), { description: shortcutDesc("Open GSD dashboard", "/gsd status"), handler: async (ctx) => { - if (!existsSync(join(process.cwd(), ".gsd"))) { + const basePath = projectRoot(); + if (!existsSync(join(basePath, ".gsd"))) { ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info"); return; } - await ctx.ui.custom( - (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done()), + await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)), { overlay: true, overlayOptions: { @@ -31,16 +34,36 @@ export function registerShortcuts(pi: ExtensionAPI): void { }, }); + pi.registerShortcut(Key.ctrlAlt("n"), { + description: shortcutDesc("Open notification history", "/gsd notifications"), + handler: async (ctx) => { + await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)), + { + overlay: true, + overlayOptions: { + width: "80%", + minWidth: 60, + maxHeight: "88%", + anchor: "center", + backdrop: true, + }, + }, + ); + }, + }); + pi.registerShortcut(Key.ctrlAlt("p"), { description: shortcutDesc("Open parallel worker monitor", "/gsd parallel watch"), handler: async (ctx) => { - const parallelDir = join(process.cwd(), ".gsd", "parallel"); + const basePath = projectRoot(); + const parallelDir = join(basePath, ".gsd", "parallel"); if (!existsSync(parallelDir)) { ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info"); return; } - await ctx.ui.custom( - (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done()), + await ctx.ui.custom( + (tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true)), { overlay: true, overlayOptions: { diff --git a/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts b/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts new file mode 100644 index 000000000..3c770095d --- /dev/null +++ b/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts @@ -0,0 +1,57 @@ +/** + * Input sanitization for gsd_complete_milestone parameters. + * + * The Claude SDK deserializes tool-call JSON before the handler runs. + * When an LLM (especially smaller models like haiku) generates large markdown + * parameters, the JSON can arrive with subtly wrong types — numbers where + * strings are expected, null where arrays belong, string "true" instead of + * boolean true, etc. This sanitizer normalizes all fields so + * handleCompleteMilestone never crashes on type mismatches. + * + * See: https://github.com/gsd-build/gsd-2/issues/3013 + */ + +import type { CompleteMilestoneParams } from "../tools/complete-milestone.js"; + +/** + * Coerce an unknown value to a trimmed string. + * Returns "" for null / undefined. + */ +function toStr(v: unknown): string { + if (v == null) return ""; + return String(v).trim(); +} + +/** + * Coerce an unknown value to an array of trimmed, non-empty strings. + * - If already an array, filter/trim each element. + * - Otherwise return []. + */ +function toStrArray(v: unknown): string[] { + if (!Array.isArray(v)) return []; + return v + .map((item) => (item == null ? "" : String(item).trim())) + .filter((s) => s.length > 0); +} + +/** + * Sanitize raw params from the tool-call framework into well-typed + * CompleteMilestoneParams, tolerating type mismatches from LLM JSON quirks. + */ +export function sanitizeCompleteMilestoneParams(raw: Record): CompleteMilestoneParams { + return { + milestoneId: toStr(raw.milestoneId), + title: toStr(raw.title), + oneLiner: toStr(raw.oneLiner), + narrative: toStr(raw.narrative), + successCriteriaResults: toStr(raw.successCriteriaResults), + definitionOfDoneResults: toStr(raw.definitionOfDoneResults), + requirementOutcomes: toStr(raw.requirementOutcomes), + keyDecisions: toStrArray(raw.keyDecisions), + keyFiles: toStrArray(raw.keyFiles), + lessonsLearned: toStrArray(raw.lessonsLearned), + followUps: toStr(raw.followUps), + deviations: toStr(raw.deviations), + verificationPassed: raw.verificationPassed === true || raw.verificationPassed === "true", + }; +} diff --git a/src/resources/extensions/gsd/bootstrap/system-context.ts b/src/resources/extensions/gsd/bootstrap/system-context.ts index 0a8255fdc..3a336f9ee 100644 --- a/src/resources/extensions/gsd/bootstrap/system-context.ts +++ b/src/resources/extensions/gsd/bootstrap/system-context.ts @@ -1,23 +1,53 @@ -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, unlinkSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; import type { ExtensionContext } from "@gsd/pi-coding-agent"; +import { logWarning } from "../workflow-logger.js"; import { debugTime } from "../debug-logger.js"; -import { loadPrompt } from "../prompt-loader.js"; +import { loadPrompt, getTemplatesDir } from "../prompt-loader.js"; +import { readForensicsMarker } from "../forensics.js"; import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js"; +import { resolveSkillReference } from "../preferences-skills.js"; import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js"; +import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js"; import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js"; import { getActiveAutoWorktreeContext } from "../auto-worktree.js"; import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js"; import { deriveState } from "../state.js"; -import { formatOverridesSection, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js"; +import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js"; import { toPosixPath } from "../../shared/mod.js"; import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js"; +import { autoEnableCmuxPreferences } from "../commands-cmux.js"; const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd"); +/** + * Bundled skill triggers — resolved dynamically at runtime instead of + * hardcoding absolute paths in the system prompt template. Only skills + * that actually exist on disk are included in the table. (#3575) + */ +const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> = [ + { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" }, + { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" }, + { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" }, +]; + +function buildBundledSkillsTable(): string { + const cwd = process.cwd(); + const rows: string[] = []; + for (const { trigger, skill } of BUNDLED_SKILL_TRIGGERS) { + const resolution = resolveSkillReference(skill, cwd); + if (resolution.method === "unresolved") continue; // skill not installed — omit from prompt + rows.push(`| ${trigger} | \`${resolution.resolvedPath}\` |`); + } + if (rows.length === 0) { + return "*No bundled skills found. Install skills to `~/.agents/skills/` or `~/.claude/skills/`.*"; + } + return `| Trigger | Skill to load |\n|---|---|\n${rows.join("\n")}`; +} + function warnDeprecatedAgentInstructions(): void { const paths = [ join(gsdHome, "agent-instructions.md"), @@ -41,14 +71,22 @@ export async function buildBeforeAgentStartResult( if (!existsSync(join(process.cwd(), ".gsd"))) return undefined; const stopContextTimer = debugTime("context-inject"); - const systemContent = loadPrompt("system"); - const loadedPreferences = loadEffectiveGSDPreferences(); + const systemContent = loadPrompt("system", { + bundledSkillsTable: buildBundledSkillsTable(), + templatesDir: getTemplatesDir(), + shortcutDashboard: formatShortcut("Ctrl+Alt+G"), + shortcutShell: formatShortcut("Ctrl+Alt+B"), + }); + let loadedPreferences = loadEffectiveGSDPreferences(); if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) { markCmuxPromptShown(); - ctx.ui.notify( - "cmux detected. Run /gsd cmux on to enable sidebar metadata, notifications, and visual subagent splits for this project.", - "info", - ); + if (autoEnableCmuxPreferences()) { + loadedPreferences = loadEffectiveGSDPreferences(); + ctx.ui.notify( + "cmux detected — auto-enabled. Run /gsd cmux off to disable.", + "info", + ); + } } let preferenceBlock = ""; @@ -82,8 +120,8 @@ export async function buildBeforeAgentStartResult( memoryBlock = `\n\n${formatted}`; } } - } catch { - // non-fatal + } catch (e) { + logWarning("bootstrap", `memory block fetch failed: ${(e as Error).message}`); } let newSkillsBlock = ""; @@ -94,30 +132,68 @@ export async function buildBeforeAgentStartResult( } } + let codebaseBlock = ""; + try { + const codebaseOptions = loadedPreferences?.preferences?.codebase + ? { + excludePatterns: loadedPreferences.preferences.codebase.exclude_patterns, + maxFiles: loadedPreferences.preferences.codebase.max_files, + collapseThreshold: loadedPreferences.preferences.codebase.collapse_threshold, + } + : undefined; + ensureCodebaseMapFresh(process.cwd(), codebaseOptions); + } catch (e) { + logWarning("bootstrap", `CODEBASE refresh failed: ${(e as Error).message}`); + } + + const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE"); + const rawCodebase = readCodebaseMap(process.cwd()); + if (existsSync(codebasePath) && rawCodebase) { + try { + const rawContent = rawCodebase.trim(); + if (rawContent) { + // Cap injection size to ~2 000 tokens to avoid bloating every request. + // Full map is always available at .gsd/CODEBASE.md. + const MAX_CODEBASE_CHARS = 8_000; + const generatedMatch = rawContent.match(/Generated: (\S+)/); + const generatedAt = generatedMatch?.[1] ?? "unknown"; + const content = rawContent.length > MAX_CODEBASE_CHARS + ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*" + : rawContent; + codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`; + } + } catch (e) { + logWarning("bootstrap", `CODEBASE file read failed: ${(e as Error).message}`); + } + } + warnDeprecatedAgentInstructions(); const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd()); + + // Re-inject forensics context on follow-up turns (#2941) + const forensicsInjection = !injection ? buildForensicsContextInjection(process.cwd(), event.prompt) : null; + const worktreeBlock = buildWorktreeContextBlock(); - const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`; + const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`; stopContextTimer({ systemPromptSize: fullSystem.length, - injectionSize: injection?.length ?? 0, + injectionSize: injection?.length ?? forensicsInjection?.length ?? 0, hasPreferences: preferenceBlock.length > 0, hasNewSkills: newSkillsBlock.length > 0, }); + // Determine which context message to inject (guided execute takes priority) + const contextMessage = injection + ? { customType: "gsd-guided-context", content: injection, display: false as const } + : forensicsInjection + ? { customType: "gsd-forensics", content: forensicsInjection, display: false as const } + : null; + return { systemPrompt: fullSystem, - ...(injection - ? { - message: { - customType: "gsd-guided-context", - content: injection, - display: false as const, - }, - } - : {}), + ...(contextMessage ? { message: contextMessage } : {}), }; } @@ -133,8 +209,8 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st globalSizeKb = Buffer.byteLength(content, "utf-8") / 1024; globalKnowledge = content; } - } catch { - // skip + } catch (e) { + logWarning("bootstrap", `global knowledge file read failed: ${(e as Error).message}`); } } @@ -145,8 +221,8 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st try { const content = readFileSync(knowledgePath, "utf-8").trim(); if (content) projectKnowledge = content; - } catch { - // skip + } catch (e) { + logWarning("bootstrap", `project knowledge file read failed: ${(e as Error).message}`); } } @@ -209,7 +285,19 @@ function buildWorktreeContextBlock(): string { return ""; } +/** + * Low-entropy resume intent patterns — short phrases a user types to + * continue work after a pause, rate limit, or context reset (#3615). + * Tested against the trimmed, lowercased prompt with trailing punctuation stripped. + */ +const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/; + async function buildGuidedExecuteContextInjection(prompt: string, basePath: string): Promise { + const ensureStateDbOpen = async () => { + const { ensureDbOpen } = await import("./dynamic-tools.js"); + await ensureDbOpen(); + }; + const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i); if (executeMatch) { const [, taskId, taskTitle, sliceId, milestoneId] = executeMatch; @@ -219,12 +307,35 @@ async function buildGuidedExecuteContextInjection(prompt: string, basePath: stri const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i); if (resumeMatch) { const [, sliceId, milestoneId] = resumeMatch; + await ensureStateDbOpen(); const state = await deriveState(basePath); if (state.activeMilestone?.id === milestoneId && state.activeSlice?.id === sliceId && state.activeTask) { return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, state.activeTask.id, state.activeTask.title); } } + // Fallback: low-entropy resume prompt (e.g., "continue", "ok", "go ahead") + // during an active executing task — inject task context so the agent + // doesn't rebuild from scratch (#3615). + // Intent-gated: only fire for short, resume-like prompts to avoid hijacking + // control/help/diagnostic prompts with unrelated execution context. + // Phase-gated: only fire during "executing" to avoid misrouting during + // replanning, gate evaluation, or other non-execution phases. + const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, ""); + if (RESUME_INTENT_PATTERNS.test(trimmed)) { + await ensureStateDbOpen(); + const state = await deriveState(basePath); + if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) { + return buildTaskExecutionContextInjection( + basePath, + state.activeMilestone.id, + state.activeSlice.id, + state.activeTask.id, + state.activeTask.title, + ); + } + } + return null; } @@ -375,3 +486,43 @@ function oneLine(text: string): string { return text.replace(/\s+/g, " ").trim(); } +// ─── Forensics Context Re-injection (#2941) ────────────────────────────────── + +/** + * Check for an active forensics session and return the prompt content + * so it can be re-injected on follow-up turns. + */ +export function buildForensicsContextInjection(basePath: string, prompt: string): string | null { + const marker = readForensicsMarker(basePath); + if (!marker) return null; + + // Expire markers older than 2 hours to avoid stale context + const age = Date.now() - new Date(marker.createdAt).getTime(); + if (age > 2 * 60 * 60 * 1000) { + clearForensicsMarker(basePath); + return null; + } + + const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, ""); + if (trimmed && !RESUME_INTENT_PATTERNS.test(trimmed)) { + clearForensicsMarker(basePath); + return null; + } + + return marker.promptContent; +} + +/** + * Remove the active forensics marker file, e.g. when the investigation + * is complete or the session expires. + */ +export function clearForensicsMarker(basePath: string): void { + const markerPath = join(basePath, ".gsd", "runtime", "active-forensics.json"); + if (existsSync(markerPath)) { + try { + unlinkSync(markerPath); + } catch (e) { + logWarning("bootstrap", `unlinkSync forensics marker failed: ${(e as Error).message}`); + } + } +} diff --git a/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts b/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts index 695c7e746..4d325fbf1 100644 --- a/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts +++ b/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts @@ -16,8 +16,13 @@ import { createHash } from "node:crypto"; const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4; +/** Interactive/user-facing tools where even 1 duplicate is confusing. */ +const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]); +const MAX_CONSECUTIVE_STRICT = 1; + let consecutiveCount = 0; let lastSignature = ""; +let lastToolName = ""; let enabled = true; /** Hash tool name + args into a compact signature for comparison. */ @@ -55,9 +60,14 @@ export function checkToolCallLoop( } else { consecutiveCount = 1; lastSignature = sig; + lastToolName = toolName; } - if (consecutiveCount > MAX_CONSECUTIVE_IDENTICAL_CALLS) { + const threshold = STRICT_LOOP_TOOLS.has(toolName) + ? MAX_CONSECUTIVE_STRICT + : MAX_CONSECUTIVE_IDENTICAL_CALLS; + + if (consecutiveCount > threshold) { return { block: true, reason: @@ -75,6 +85,7 @@ export function checkToolCallLoop( export function resetToolCallLoopGuard(): void { consecutiveCount = 0; lastSignature = ""; + lastToolName = ""; enabled = true; } @@ -83,6 +94,7 @@ export function disableToolCallLoopGuard(): void { enabled = false; consecutiveCount = 0; lastSignature = ""; + lastToolName = ""; } /** Get current consecutive count for diagnostics. */ diff --git a/src/resources/extensions/gsd/bootstrap/write-gate.ts b/src/resources/extensions/gsd/bootstrap/write-gate.ts index 75a964021..b8e6cf8e5 100644 --- a/src/resources/extensions/gsd/bootstrap/write-gate.ts +++ b/src/resources/extensions/gsd/bootstrap/write-gate.ts @@ -1,10 +1,150 @@ -const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/; +import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; -let depthVerificationDone = false; +const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/; +const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i; +const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i; + +/** + * Path segment that identifies .gsd/ planning artifacts. + * Writes to these paths are allowed during queue mode. + */ +const GSD_DIR_RE = /(^|[/\\])\.gsd([/\\]|$)/; + +/** + * Read-only tool names that are always safe during queue mode. + */ +const QUEUE_SAFE_TOOLS = new Set([ + "read", "grep", "find", "ls", "glob", + // Discussion & planning tools + "ask_user_questions", + "gsd_milestone_generate_id", + "gsd_summary_save", + // Web research tools used during queue discussion + "search-the-web", "resolve_library", "get_library_docs", "fetch_page", + "search_and_read", +]); + +/** + * Bash commands that are read-only / investigative — safe during queue mode. + * Matches the leading command in a bash invocation. + */ +const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s)/; + +const verifiedDepthMilestones = new Set(); let activeQueuePhase = false; +/** + * Discussion gate enforcement state. + * + * When ask_user_questions is called with a recognized gate question ID, + * we track the pending gate. Until the gate is confirmed (user selects the + * first/recommended option), all non-read-only tool calls are blocked. + * This mechanically prevents the model from rationalizing past failed or + * cancelled gate questions. + */ +let pendingGateId: string | null = null; + +/** + * Recognized gate question ID patterns. + * These appear in discuss.md (depth/requirements/roadmap). + */ +const GATE_QUESTION_PATTERNS = [ + "depth_verification", +] as const; + +/** + * Tools that are safe to call while a gate is pending. + * Includes read-only tools and ask_user_questions itself (so the model can re-ask). + */ +const GATE_SAFE_TOOLS = new Set([ + "ask_user_questions", + "read", "grep", "find", "ls", "glob", + "search-the-web", "resolve_library", "get_library_docs", "fetch_page", + "search_and_read", +]); + +export interface WriteGateSnapshot { + verifiedDepthMilestones: string[]; + activeQueuePhase: boolean; + pendingGateId: string | null; +} + +function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): boolean { + return env.GSD_PERSIST_WRITE_GATE_STATE === "1"; +} + +function writeGateSnapshotPath(basePath: string = process.cwd()): string { + return join(basePath, ".gsd", "runtime", "write-gate-state.json"); +} + +function currentWriteGateSnapshot(): WriteGateSnapshot { + return { + verifiedDepthMilestones: [...verifiedDepthMilestones].sort(), + activeQueuePhase, + pendingGateId, + }; +} + +function persistWriteGateSnapshot(basePath: string = process.cwd()): void { + if (!shouldPersistWriteGateSnapshot()) return; + const path = writeGateSnapshotPath(basePath); + mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true }); + const tempPath = `${path}.tmp`; + writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8"); + renameSync(tempPath, path); +} + +function clearPersistedWriteGateSnapshot(basePath: string = process.cwd()): void { + if (!shouldPersistWriteGateSnapshot()) return; + const path = writeGateSnapshotPath(basePath); + try { + unlinkSync(path); + } catch { + // swallow + } +} + +function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot { + const record = value && typeof value === "object" ? value as Record : {}; + const verified = Array.isArray(record.verifiedDepthMilestones) + ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string") + : []; + return { + verifiedDepthMilestones: [...new Set(verified)].sort(), + activeQueuePhase: record.activeQueuePhase === true, + pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null, + }; +} + +export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot { + const path = writeGateSnapshotPath(basePath); + if (!existsSync(path)) return currentWriteGateSnapshot(); + try { + return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8"))); + } catch { + return currentWriteGateSnapshot(); + } +} + export function isDepthVerified(): boolean { - return depthVerificationDone; + return verifiedDepthMilestones.size > 0; +} + +/** + * Check whether a specific milestone has passed depth verification. + */ +export function isMilestoneDepthVerified(milestoneId: string | null | undefined): boolean { + if (!milestoneId) return false; + return verifiedDepthMilestones.has(milestoneId); +} + +export function isMilestoneDepthVerifiedInSnapshot( + snapshot: WriteGateSnapshot, + milestoneId: string | null | undefined, +): boolean { + if (!milestoneId) return false; + return snapshot.verifiedDepthMilestones.includes(milestoneId); } export function isQueuePhaseActive(): boolean { @@ -13,39 +153,314 @@ export function isQueuePhaseActive(): boolean { export function setQueuePhaseActive(active: boolean): void { activeQueuePhase = active; + persistWriteGateSnapshot(); } export function resetWriteGateState(): void { - depthVerificationDone = false; + verifiedDepthMilestones.clear(); + pendingGateId = null; + persistWriteGateSnapshot(); } export function clearDiscussionFlowState(): void { - depthVerificationDone = false; + verifiedDepthMilestones.clear(); activeQueuePhase = false; + pendingGateId = null; + clearPersistedWriteGateSnapshot(); } -export function markDepthVerified(): void { - depthVerificationDone = true; +export function markDepthVerified(milestoneId?: string | null, basePath: string = process.cwd()): void { + if (!milestoneId) return; + verifiedDepthMilestones.add(milestoneId); + persistWriteGateSnapshot(basePath); +} + +/** + * Check whether a question ID matches a recognized gate pattern. + */ +export function isGateQuestionId(questionId: string): boolean { + return GATE_QUESTION_PATTERNS.some(pattern => questionId.includes(pattern)); +} + +/** + * Extract the milestone ID embedded in a depth-verification question id. + * Prompts are expected to use ids like `depth_verification_M001_confirm`. + */ +export function extractDepthVerificationMilestoneId(questionId: string): string | null { + const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE); + return match?.[1] ?? null; +} + +/** + * Extract the milestone ID from a milestone CONTEXT file path. + */ +function extractContextMilestoneId(inputPath: string): string | null { + const match = inputPath.match(CONTEXT_MILESTONE_RE); + return match?.[1] ?? null; +} + +/** + * Mark a gate as pending (called when ask_user_questions is invoked with a gate ID). + */ +export function setPendingGate(gateId: string): void { + pendingGateId = gateId; + persistWriteGateSnapshot(); +} + +/** + * Clear the pending gate (called when the user confirms). + */ +export function clearPendingGate(): void { + pendingGateId = null; + persistWriteGateSnapshot(); +} + +/** + * Get the currently pending gate, if any. + */ +export function getPendingGate(): string | null { + return pendingGateId; +} + +/** + * Check whether a tool call should be blocked because a discussion gate + * is pending (ask_user_questions was called but not confirmed). + * + * Returns { block: true, reason } if the tool should be blocked. + * Read-only tools and ask_user_questions itself are always allowed. + */ +export function shouldBlockPendingGate( + toolName: string, + milestoneId: string | null, + queuePhaseActive?: boolean, +): { block: boolean; reason?: string } { + return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive); +} + +export function shouldBlockPendingGateInSnapshot( + snapshot: WriteGateSnapshot, + toolName: string, + _milestoneId: string | null, + _queuePhaseActive?: boolean, +): { block: boolean; reason?: string } { + if (!snapshot.pendingGateId) return { block: false }; + + if (GATE_SAFE_TOOLS.has(toolName)) return { block: false }; + + // Bash read-only commands are also safe + if (toolName === "bash") return { block: false }; // bash is checked separately below + + return { + block: true, + reason: [ + `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`, + `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`, + `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`, + `did not match a provided option, you MUST re-ask — never rationalize past the block.`, + `Do NOT proceed, do NOT use alternative approaches, do NOT skip the gate.`, + ].join(" "), + }; +} + +/** + * Check whether a bash command should be blocked because a discussion gate is pending. + * Read-only bash commands are allowed; mutating commands are blocked. + */ +export function shouldBlockPendingGateBash( + command: string, + milestoneId: string | null, + queuePhaseActive?: boolean, +): { block: boolean; reason?: string } { + return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive); +} + +export function shouldBlockPendingGateBashInSnapshot( + snapshot: WriteGateSnapshot, + command: string, + _milestoneId: string | null, + _queuePhaseActive?: boolean, +): { block: boolean; reason?: string } { + if (!snapshot.pendingGateId) return { block: false }; + + // Allow read-only bash commands + if (BASH_READ_ONLY_RE.test(command)) return { block: false }; + + return { + block: true, + reason: [ + `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`, + `You MUST re-call ask_user_questions with the gate question before running mutating commands.`, + `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`, + `did not match a provided option, you MUST re-ask — never rationalize past the block.`, + ].join(" "), + }; +} + +/** + * Check whether a depth_verification answer confirms the discussion is complete. + * Uses structural validation: the selected answer must exactly match the first + * option label from the question definition (the confirmation option by convention). + * This rejects free-form "Other" text, decline options, and garbage input without + * coupling to any specific label substring. + * + * @param selected The answer's selected value from details.response.answers[id].selected + * @param options The question's options array from event.input.questions[n].options + */ +export function isDepthConfirmationAnswer( + selected: unknown, + options?: Array<{ label?: string }>, +): boolean { + const value = Array.isArray(selected) ? selected[0] : selected; + if (typeof value !== "string" || !value) return false; + + // If options are available, structurally validate: selected must exactly match + // the first option (confirmation) label. Rejects free-form "Other" and decline options. + if (Array.isArray(options) && options.length > 0) { + const confirmLabel = options[0]?.label; + return typeof confirmLabel === "string" && value === confirmLabel; + } + + // Fallback when options aren't available (e.g., older call sites): + // accept only if it contains "(Recommended)" — the prompt convention suffix. + return value.includes("(Recommended)"); } export function shouldBlockContextWrite( toolName: string, inputPath: string, milestoneId: string | null, - depthVerified: boolean, - queuePhaseActive?: boolean, + _queuePhaseActive?: boolean, ): { block: boolean; reason?: string } { if (toolName !== "write") return { block: false }; - - const inDiscussion = milestoneId !== null; - const inQueue = queuePhaseActive ?? false; - if (!inDiscussion && !inQueue) return { block: false }; if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false }; - if (depthVerified) return { block: false }; + + const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId; + if (!targetMilestoneId) { + return { + block: true, + reason: [ + `HARD BLOCK: Cannot write milestone CONTEXT.md without knowing which milestone it belongs to.`, + `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`, + `Required action: call ask_user_questions with question id containing "depth_verification" and the milestone id.`, + ].join(" "), + }; + } + + if (isMilestoneDepthVerified(targetMilestoneId)) return { block: false }; return { block: true, - reason: `Blocked: Cannot write to milestone CONTEXT.md during discussion phase without depth verification. Call ask_user_questions with question id "depth_verification" first to confirm discussion depth before writing context.`, + reason: [ + `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`, + `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`, + `Required action: call ask_user_questions with question id containing "depth_verification".`, + `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`, + `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`, + ].join(" "), }; } +/** + * Check whether a gsd_summary_save CONTEXT artifact should be blocked. + * Slice-level CONTEXT artifacts are allowed; milestone-level CONTEXT writes + * require the milestone to be depth-verified first. + */ +export function shouldBlockContextArtifactSave( + artifactType: string, + milestoneId: string | null, + sliceId?: string | null, +): { block: boolean; reason?: string } { + return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId); +} + +export function shouldBlockContextArtifactSaveInSnapshot( + snapshot: WriteGateSnapshot, + artifactType: string, + milestoneId: string | null, + sliceId?: string | null, +): { block: boolean; reason?: string } { + if (artifactType !== "CONTEXT") return { block: false }; + if (sliceId) return { block: false }; + if (!milestoneId) { + return { + block: true, + reason: [ + `HARD BLOCK: Cannot save milestone CONTEXT without a milestone_id.`, + `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`, + ].join(" "), + }; + } + if (isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return { block: false }; + + return { + block: true, + reason: [ + `HARD BLOCK: Cannot save milestone CONTEXT without depth verification for ${milestoneId}.`, + `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`, + `Required action: call ask_user_questions with question id containing "depth_verification_${milestoneId}".`, + `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`, + ].join(" "), + }; +} + +/** + * Queue-mode execution guard (#2545). + * + * When the queue phase is active, the agent should only create planning + * artifacts (milestones, CONTEXT.md, QUEUE.md, etc.) — never execute work. + * This function blocks write/edit/bash tool calls that would modify source + * code outside of .gsd/. + * + * @param toolName The tool being called (write, edit, bash, etc.) + * @param input For write/edit: the file path. For bash: the command string. + * @param queuePhaseActive Whether the queue phase is currently active. + * @returns { block, reason } — block=true if the call should be rejected. + */ +export function shouldBlockQueueExecution( + toolName: string, + input: string, + queuePhaseActive: boolean, +): { block: boolean; reason?: string } { + return shouldBlockQueueExecutionInSnapshot(currentWriteGateSnapshot(), toolName, input, queuePhaseActive); +} + +export function shouldBlockQueueExecutionInSnapshot( + snapshot: WriteGateSnapshot, + toolName: string, + input: string, + queuePhaseActive: boolean = snapshot.activeQueuePhase, +): { block: boolean; reason?: string } { + if (!queuePhaseActive) return { block: false }; + + // Always-safe tools (read-only, discussion, planning) + if (QUEUE_SAFE_TOOLS.has(toolName)) return { block: false }; + + // write/edit — allow if targeting .gsd/ planning artifacts + if (toolName === "write" || toolName === "edit") { + if (GSD_DIR_RE.test(input)) return { block: false }; + return { + block: true, + reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` + + `Cannot ${toolName} to "${input}" during queue mode. ` + + `Write CONTEXT.md files and update PROJECT.md/QUEUE.md instead.`, + }; + } + + // bash — allow read-only/investigative commands, block everything else + if (toolName === "bash") { + if (BASH_READ_ONLY_RE.test(input)) return { block: false }; + return { + block: true, + reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. ` + + `Cannot run "${input.slice(0, 80)}${input.length > 80 ? "…" : ""}" during queue mode. ` + + `Use read-only commands (cat, grep, git log, etc.) to investigate, then write planning artifacts.`, + }; + } + + // Unknown tools — block by default in queue mode so custom tools cannot + // bypass execution restrictions. + return { + block: true, + reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. Unknown tools are not permitted during queue mode.`, + }; +} diff --git a/src/resources/extensions/gsd/captures.ts b/src/resources/extensions/gsd/captures.ts index 72447876e..2de7278b7 100644 --- a/src/resources/extensions/gsd/captures.ts +++ b/src/resources/extensions/gsd/captures.ts @@ -15,7 +15,7 @@ import { gsdRoot } from "./paths.js"; // ─── Types ──────────────────────────────────────────────────────────────────── -export type Classification = "quick-task" | "inject" | "defer" | "replan" | "note"; +export type Classification = "quick-task" | "inject" | "defer" | "replan" | "note" | "stop" | "backtrack"; export interface CaptureEntry { id: string; @@ -26,6 +26,7 @@ export interface CaptureEntry { resolution?: string; rationale?: string; resolvedAt?: string; + resolvedInMilestone?: string; executed?: boolean; } @@ -41,7 +42,7 @@ export interface TriageResult { const CAPTURES_FILENAME = "CAPTURES.md"; const VALID_CLASSIFICATIONS: readonly string[] = [ - "quick-task", "inject", "defer", "replan", "note", + "quick-task", "inject", "defer", "replan", "note", "stop", "backtrack", ]; // ─── Path Resolution ────────────────────────────────────────────────────────── @@ -176,6 +177,7 @@ export function markCaptureResolved( classification: Classification, resolution: string, rationale: string, + milestoneId?: string, ): void { const filePath = resolveCapturesPath(basePath); if (!existsSync(filePath)) return; @@ -206,13 +208,17 @@ export function markCaptureResolved( `**Rationale:** ${rationale}`, `**Resolved:** ${resolvedAt}`, ]; + if (milestoneId) { + newFields.push(`**Milestone:** ${milestoneId}`); + } - // Remove any existing classification/resolution/rationale/resolved fields + // Remove any existing classification/resolution/rationale/resolved/milestone fields // (in case of re-triage) section = section.replace(/\*\*Classification:\*\*\s*.+\n?/g, ""); section = section.replace(/\*\*Resolution:\*\*\s*.+\n?/g, ""); section = section.replace(/\*\*Rationale:\*\*\s*.+\n?/g, ""); section = section.replace(/\*\*Resolved:\*\*\s*.+\n?/g, ""); + section = section.replace(/\*\*Milestone:\*\*\s*.+\n?/g, ""); // Add new fields after Status line section = section.trimEnd() + "\n" + newFields.join("\n") + "\n"; @@ -255,18 +261,139 @@ export function markCaptureExecuted(basePath: string, captureId: string): void { * Load resolved captures that have actionable classifications (inject, replan, * quick-task) but have NOT yet been executed. * These are captures whose resolutions need to be carried out. + * + * When `currentMilestoneId` is provided, captures resolved in a *different* + * milestone are treated as stale and excluded. This prevents quick-task + * captures from a prior milestone re-executing after the underlying issues + * were already fixed by planned milestone work (#2872). + * + * Captures that have no `resolvedInMilestone` (legacy captures resolved before + * this field was introduced) are always included for backward compatibility. */ -export function loadActionableCaptures(basePath: string): CaptureEntry[] { +export function loadActionableCaptures(basePath: string, currentMilestoneId?: string): CaptureEntry[] { return loadAllCaptures(basePath).filter( c => c.status === "resolved" && !c.executed && (c.classification === "inject" || c.classification === "replan" || - c.classification === "quick-task"), + c.classification === "quick-task") && + // Staleness gate: exclude captures resolved in a different milestone (#2872) + (!currentMilestoneId || + !c.resolvedInMilestone || + c.resolvedInMilestone === currentMilestoneId), ); } +/** + * Load unexecuted stop captures — user directives to halt auto-mode. + * These are checked in the pre-dispatch guard pipeline (runGuards) to + * pause auto-mode before the next unit is dispatched. + */ +export function loadStopCaptures(basePath: string): CaptureEntry[] { + return loadAllCaptures(basePath).filter( + c => c.status === "resolved" && !c.executed && + (c.classification === "stop" || c.classification === "backtrack"), + ); +} + +/** + * Load unexecuted backtrack captures specifically — captures directing + * auto-mode to abandon current milestone and return to a previous one. + */ +export function loadBacktrackCaptures(basePath: string): CaptureEntry[] { + return loadAllCaptures(basePath).filter( + c => c.status === "resolved" && !c.executed && c.classification === "backtrack", + ); +} + +/** + * Revert captures that were silenced by non-triage agents. + * + * When an execute-task or other non-triage agent writes `**Status:** resolved` + * to CAPTURES.md, it bypasses the triage pipeline entirely. This function + * detects such captures (resolved but missing the Classification field that + * triage always writes) and reverts them to pending so the triage sidecar + * picks them up properly. + * + * Returns the number of captures reverted. + */ +export function revertExecutorResolvedCaptures(basePath: string): number { + const filePath = resolveCapturesPath(basePath); + if (!existsSync(filePath)) return 0; + + let content = readFileSync(filePath, "utf-8"); + let reverted = 0; + + const all = loadAllCaptures(basePath); + for (const capture of all) { + // A properly triaged capture has both resolved status AND a classification. + // An executor-silenced capture has resolved status but NO classification. + if (capture.status === "resolved" && !capture.classification) { + const sectionRegex = new RegExp( + `(### ${escapeRegex(capture.id)}\\n(?:(?!### ).)*?)(?=### |$)`, + "s", + ); + const match = sectionRegex.exec(content); + if (match) { + let section = match[1]; + section = section.replace( + /\*\*Status:\*\*\s*resolved/i, + "**Status:** pending", + ); + content = content.replace(sectionRegex, section); + reverted++; + } + } + } + + if (reverted > 0) { + writeFileSync(filePath, content, "utf-8"); + } + + return reverted; +} + +/** + * Retroactively stamp a capture with a milestone ID. + * + * Used by executeTriageResolutions() as a safety net when the triage LLM + * resolves a capture without writing the **Milestone:** field. This ensures + * the staleness gate in loadActionableCaptures() works correctly even for + * captures resolved before the prompt was updated (#2872). + */ +export function stampCaptureMilestone(basePath: string, captureId: string, milestoneId: string): void { + const filePath = resolveCapturesPath(basePath); + if (!existsSync(filePath)) return; + + const content = readFileSync(filePath, "utf-8"); + + const sectionRegex = new RegExp( + `(### ${escapeRegex(captureId)}\\n(?:(?!### ).)*?)(?=### |$)`, + "s", + ); + const match = sectionRegex.exec(content); + if (!match) return; + + let section = match[1]; + + // Only stamp if not already present + if (/\*\*Milestone:\*\*/.test(section)) return; + + // Insert after the Resolved field (or at end of section) + const resolvedFieldEnd = section.search(/\*\*Resolved:\*\*\s*.+\n?/); + if (resolvedFieldEnd !== -1) { + const resolvedMatch = section.match(/\*\*Resolved:\*\*\s*.+\n?/); + const insertPos = resolvedFieldEnd + (resolvedMatch?.[0]?.length ?? 0); + section = section.slice(0, insertPos) + `**Milestone:** ${milestoneId}\n` + section.slice(insertPos); + } else { + section = section.trimEnd() + "\n" + `**Milestone:** ${milestoneId}` + "\n"; + } + + const updated = content.replace(sectionRegex, section); + writeFileSync(filePath, updated, "utf-8"); +} + // ─── Parser ─────────────────────────────────────────────────────────────────── /** @@ -291,6 +418,7 @@ function parseCapturesContent(content: string): CaptureEntry[] { const resolution = extractBoldField(body, "Resolution"); const rationale = extractBoldField(body, "Rationale"); const resolvedAt = extractBoldField(body, "Resolved"); + const milestoneId = extractBoldField(body, "Milestone"); const executedAt = extractBoldField(body, "Executed"); if (!text || !timestamp) continue; @@ -308,6 +436,7 @@ function parseCapturesContent(content: string): CaptureEntry[] { ...(resolution ? { resolution } : {}), ...(rationale ? { rationale } : {}), ...(resolvedAt ? { resolvedAt } : {}), + ...(milestoneId ? { resolvedInMilestone: milestoneId } : {}), ...(executedAt ? { executed: true } : {}), }); } diff --git a/src/resources/extensions/gsd/codebase-generator.ts b/src/resources/extensions/gsd/codebase-generator.ts new file mode 100644 index 000000000..b291c3c1f --- /dev/null +++ b/src/resources/extensions/gsd/codebase-generator.ts @@ -0,0 +1,616 @@ +/** + * GSD Codebase Map Generator + * + * Produces .gsd/CODEBASE.md — a structural table of contents for the project. + * Gives fresh agent contexts instant orientation without filesystem exploration. + * + * Generation: walk `git ls-files`, group by directory, output with descriptions. + * Maintenance: agent updates descriptions as it works; incremental update preserves them. + */ + +import { createHash } from "node:crypto"; +import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"; +import { join, dirname, extname } from "node:path"; + +import { execSync } from "node:child_process"; +import { gsdRoot } from "./paths.js"; + +// ─── Types ─────────────────────────────────────────────────────────────────── + +export interface CodebaseMapOptions { + excludePatterns?: string[]; + maxFiles?: number; + collapseThreshold?: number; +} + +export interface CodebaseMapMetadata { + generatedAt: string; + fingerprint: string; + fileCount: number; + truncated: boolean; +} + +export interface EnsureCodebaseMapOptions { + ttlMs?: number; + maxAgeMs?: number; + force?: boolean; +} + +export interface EnsureCodebaseMapResult { + status: "generated" | "updated" | "fresh" | "empty"; + fileCount: number; + truncated: boolean; + generatedAt: string | null; + fingerprint: string | null; + reason?: string; +} + +interface FileEntry { + path: string; + description: string; +} + +interface DirectoryGroup { + path: string; + files: FileEntry[]; + collapsed: boolean; +} + +interface ResolvedCodebaseMapOptions { + excludes: string[]; + maxFiles: number; + collapseThreshold: number; + optionSignature: string; +} + +interface EnumeratedFiles { + files: string[]; + truncated: boolean; +} + +// ─── Defaults ──────────────────────────────────────────────────────────────── + +const DEFAULT_EXCLUDES = [ + // ── AI / tooling meta ── + ".agents/", + ".gsd/", + ".planning/", + ".plans/", + ".claude/", + ".cursor/", + ".bg-shell/", + + // ── Editor / IDE ── + ".vscode/", + ".idea/", + + // ── VCS ── + ".git/", + + // ── Dependencies & build artifacts ── + "node_modules/", + "dist/", + "build/", + ".next/", + "coverage/", + "__pycache__/", + ".venv/", + "venv/", + "vendor/", + "target/", + + // ── Misc ── + ".cache/", + "tmp/", +]; + +const DEFAULT_MAX_FILES = 500; +const DEFAULT_COLLAPSE_THRESHOLD = 20; +const DEFAULT_REFRESH_TTL_MS = 30_000; +const DEFAULT_MAX_AGE_MS = 15 * 60_000; +const CODEBASE_METADATA_PREFIX = " comment blocks to preserve + * descriptions for files in collapsed directories across incremental updates. + */ +export function parseCodebaseMap(content: string): Map { + const descriptions = new Map(); + let inCollapsedBlock = false; + + for (const line of content.split("\n")) { + // Track collapsed-description comment blocks + if (line.trimStart().startsWith("")) { + inCollapsedBlock = false; + continue; + } + + // Match: - `path/to/file.ts` — Description here + const match = line.match(/^- `(.+?)` — (.+)$/); + if (match) { + descriptions.set(match[1], match[2]); + continue; + } + + // Match: - `path/to/file.ts` (no description) — only outside collapsed blocks + if (!inCollapsedBlock) { + const bareMatch = line.match(/^- `(.+?)`\s*$/); + if (bareMatch) { + descriptions.set(bareMatch[1], ""); + } + } + } + return descriptions; +} + +export function parseCodebaseMapMetadata(content: string): CodebaseMapMetadata | null { + const metaLine = content + .split("\n") + .find((line) => line.trimStart().startsWith(CODEBASE_METADATA_PREFIX)); + if (!metaLine) return null; + + const trimmed = metaLine.trim(); + const jsonStart = CODEBASE_METADATA_PREFIX.length; + const jsonEnd = trimmed.lastIndexOf(" -->"); + if (jsonEnd <= jsonStart) return null; + + try { + const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd)); + if ( + typeof parsed?.generatedAt === "string" + && typeof parsed?.fingerprint === "string" + && typeof parsed?.fileCount === "number" + && typeof parsed?.truncated === "boolean" + ) { + return parsed as CodebaseMapMetadata; + } + } catch { + // Ignore malformed metadata and treat the map as stale. + } + return null; +} + +// ─── File Enumeration ──────────────────────────────────────────────────────── + +function shouldExclude(filePath: string, excludes: string[]): boolean { + for (const pattern of excludes) { + if (pattern.endsWith("/")) { + if (filePath.startsWith(pattern) || filePath.includes(`/${pattern}`)) return true; + } else if (filePath === pattern || filePath.endsWith(`/${pattern}`)) { + return true; + } + } + // Skip binary/lock files + const ext = extname(filePath).toLowerCase(); + if ([".lock", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf", ".eot", ".svg"].includes(ext)) { + return true; + } + return false; +} + +function lsFiles(basePath: string): string[] { + try { + const result = execSync("git ls-files", { cwd: basePath, encoding: "utf-8", timeout: 10000 }); + return result.split("\n").filter(Boolean); + } catch { + return []; + } +} + +/** + * Enumerate tracked files, applying exclusions and the maxFiles cap. + * Returns both the file list and whether truncation occurred. + */ +function enumerateFiles(basePath: string, excludes: string[], maxFiles: number): { files: string[]; truncated: boolean } { + const allFiles = lsFiles(basePath); + const filtered = allFiles.filter((f) => !shouldExclude(f, excludes)); + const truncated = filtered.length > maxFiles; + return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated }; +} + +function resolveGeneratorOptions(options?: CodebaseMapOptions): ResolvedCodebaseMapOptions { + const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])]; + const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES; + const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD; + return { + excludes, + maxFiles, + collapseThreshold, + optionSignature: JSON.stringify({ + excludes, + maxFiles, + collapseThreshold, + }), + }; +} + +function computeCodebaseFingerprint( + files: string[], + resolved: ResolvedCodebaseMapOptions, + truncated: boolean, +): string { + return createHash("sha1") + .update(JSON.stringify({ + files, + truncated, + optionSignature: resolved.optionSignature, + })) + .digest("hex"); +} + +// ─── Grouping ──────────────────────────────────────────────────────────────── + +function groupByDirectory( + files: string[], + descriptions: Map, + collapseThreshold: number, +): DirectoryGroup[] { + const dirMap = new Map(); + + for (const file of files) { + const dir = dirname(file); + const dirKey = dir === "." ? "" : dir; + if (!dirMap.has(dirKey)) { + dirMap.set(dirKey, []); + } + dirMap.get(dirKey)!.push({ + path: file, + description: descriptions.get(file) ?? "", + }); + } + + const groups: DirectoryGroup[] = []; + const sortedDirs = [...dirMap.keys()].sort(); + + for (const dir of sortedDirs) { + const dirFiles = dirMap.get(dir)!; + dirFiles.sort((a, b) => a.path.localeCompare(b.path)); + + groups.push({ + path: dir, + files: dirFiles, + collapsed: dirFiles.length > collapseThreshold, + }); + } + + return groups; +} + +// ─── Rendering ─────────────────────────────────────────────────────────────── + +function renderCodebaseMap( + groups: DirectoryGroup[], + totalFiles: number, + truncated: boolean, + metadata: CodebaseMapMetadata, +): string { + const lines: string[] = []; + const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0); + + lines.push("# Codebase Map"); + lines.push(""); + lines.push(`Generated: ${metadata.generatedAt} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`); + lines.push(`${CODEBASE_METADATA_PREFIX}${JSON.stringify(metadata)} -->`); + if (truncated) { + lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`); + } + lines.push(""); + + for (const group of groups) { + const heading = group.path || "(root)"; + lines.push(`### ${heading}/`); + + if (group.collapsed) { + // Summarize collapsed directories + const extensions = new Map(); + for (const f of group.files) { + const ext = extname(f.path) || "(no ext)"; + extensions.set(ext, (extensions.get(ext) ?? 0) + 1); + } + const extSummary = [...extensions.entries()] + .sort((a, b) => b[1] - a[1]) + .map(([ext, count]) => `${count} ${ext}`) + .join(", "); + lines.push(`- *(${group.files.length} files: ${extSummary})*`); + + // Preserve any existing descriptions in a hidden comment block so + // incremental updates can recover them via parseCodebaseMap. + const descLines = group.files + .filter((f) => f.description) + .map((f) => `- \`${f.path}\` — ${f.description}`); + if (descLines.length > 0) { + lines.push(""); + } + } else { + for (const file of group.files) { + if (file.description) { + lines.push(`- \`${file.path}\` — ${file.description}`); + } else { + lines.push(`- \`${file.path}\``); + } + } + } + lines.push(""); + } + + return lines.join("\n"); +} + +function buildCodebaseMap( + basePath: string, + resolved: ResolvedCodebaseMapOptions, + existingDescriptions?: Map, + enumerated?: EnumeratedFiles, +): { + content: string; + fileCount: number; + truncated: boolean; + files: string[]; + fingerprint: string; + generatedAt: string; +} { + const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles); + const descriptions = existingDescriptions ?? new Map(); + const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold); + const generatedAt = new Date().toISOString().split(".")[0] + "Z"; + const metadata: CodebaseMapMetadata = { + generatedAt, + fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated), + fileCount: listed.files.length, + truncated: listed.truncated, + }; + const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata); + + return { + content, + fileCount: listed.files.length, + truncated: listed.truncated, + files: listed.files, + fingerprint: metadata.fingerprint, + generatedAt, + }; +} + +// ─── Public API ────────────────────────────────────────────────────────────── + +/** + * Generate a fresh CODEBASE.md from scratch. + * Preserves existing descriptions if `existingDescriptions` is provided. + */ +export function generateCodebaseMap( + basePath: string, + options?: CodebaseMapOptions, + existingDescriptions?: Map, +): { content: string; fileCount: number; truncated: boolean; files: string[]; fingerprint: string; generatedAt: string } { + const resolved = resolveGeneratorOptions(options); + return buildCodebaseMap(basePath, resolved, existingDescriptions); +} + +/** + * Incremental update: re-scan files, preserve existing descriptions, + * add new files, remove deleted files. + */ +export function updateCodebaseMap( + basePath: string, + options?: CodebaseMapOptions, +): { + content: string; + added: number; + removed: number; + unchanged: number; + fileCount: number; + truncated: boolean; + fingerprint: string; + generatedAt: string; +} { + const codebasePath = join(gsdRoot(basePath), "CODEBASE.md"); + const resolved = resolveGeneratorOptions(options); + + // Load existing descriptions + let existingDescriptions = new Map(); + if (existsSync(codebasePath)) { + const existing = readFileSync(codebasePath, "utf-8"); + existingDescriptions = parseCodebaseMap(existing); + } + + const existingFiles = new Set(existingDescriptions.keys()); + + // Generate new map preserving descriptions — reuse the returned file list + // to avoid a second enumeration (prevents race between content and stats). + const result = buildCodebaseMap(basePath, resolved, existingDescriptions); + const currentSet = new Set(result.files); + + // Count changes + let added = 0; + let removed = 0; + + for (const f of result.files) { + if (!existingFiles.has(f)) added++; + } + for (const f of existingFiles) { + if (!currentSet.has(f)) removed++; + } + + return { + content: result.content, + added, + removed, + unchanged: result.files.length - added, + fileCount: result.fileCount, + truncated: result.truncated, + fingerprint: result.fingerprint, + generatedAt: result.generatedAt, + }; +} + +function clearFreshnessCache(basePath: string): void { + for (const key of freshnessCache.keys()) { + if (key === basePath || key.startsWith(`${basePath}::`)) { + freshnessCache.delete(key); + } + } +} + +export function ensureCodebaseMapFresh( + basePath: string, + options?: CodebaseMapOptions, + ensureOptions?: EnsureCodebaseMapOptions, +): EnsureCodebaseMapResult { + const resolved = resolveGeneratorOptions(options); + const cacheKey = `${basePath}::${resolved.optionSignature}`; + const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS; + const maxAgeMs = ensureOptions?.maxAgeMs ?? DEFAULT_MAX_AGE_MS; + const force = ensureOptions?.force === true; + const now = Date.now(); + + if (!force && ttlMs > 0) { + const cached = freshnessCache.get(cacheKey); + if (cached && now - cached.checkedAt < ttlMs) { + return cached.result; + } + } + + const existing = readCodebaseMap(basePath); + const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles); + const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated); + + const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => { + freshnessCache.set(cacheKey, { checkedAt: now, result }); + return result; + }; + + if (!existing) { + const generated = buildCodebaseMap(basePath, resolved, undefined, listed); + if (generated.fileCount > 0) { + writeCodebaseMap(basePath, generated.content); + return cacheAndReturn({ + status: "generated", + fileCount: generated.fileCount, + truncated: generated.truncated, + generatedAt: generated.generatedAt, + fingerprint: generated.fingerprint, + reason: "missing", + }); + } + return cacheAndReturn({ + status: "empty", + fileCount: 0, + truncated: false, + generatedAt: null, + fingerprint, + reason: "no-tracked-files", + }); + } + + const metadata = parseCodebaseMapMetadata(existing); + const existingDescriptions = parseCodebaseMap(existing); + const ageMs = metadata ? now - Date.parse(metadata.generatedAt) : Number.POSITIVE_INFINITY; + const staleReason = + !metadata ? "missing-metadata" + : metadata.fingerprint !== fingerprint ? "files-changed" + : metadata.fileCount !== listed.files.length ? "file-count-changed" + : metadata.truncated !== listed.truncated ? "truncation-changed" + : maxAgeMs > 0 && Number.isFinite(ageMs) && ageMs > maxAgeMs ? "expired" + : undefined; + + if (!staleReason) { + return cacheAndReturn({ + status: "fresh", + fileCount: metadata?.fileCount ?? listed.files.length, + truncated: metadata?.truncated ?? listed.truncated, + generatedAt: metadata?.generatedAt ?? null, + fingerprint: metadata?.fingerprint ?? fingerprint, + }); + } + + const updated = buildCodebaseMap(basePath, resolved, existingDescriptions, listed); + if (updated.fileCount > 0) { + writeCodebaseMap(basePath, updated.content); + return cacheAndReturn({ + status: "updated", + fileCount: updated.fileCount, + truncated: updated.truncated, + generatedAt: updated.generatedAt, + fingerprint: updated.fingerprint, + reason: staleReason, + }); + } + + return cacheAndReturn({ + status: "empty", + fileCount: 0, + truncated: false, + generatedAt: null, + fingerprint, + reason: staleReason, + }); +} + +/** + * Write CODEBASE.md to .gsd/ directory. + */ +export function writeCodebaseMap(basePath: string, content: string): string { + const root = gsdRoot(basePath); + mkdirSync(root, { recursive: true }); + const outPath = join(root, "CODEBASE.md"); + writeFileSync(outPath, content, "utf-8"); + clearFreshnessCache(basePath); + return outPath; +} + +/** + * Read existing CODEBASE.md, or return null if it doesn't exist. + */ +export function readCodebaseMap(basePath: string): string | null { + const codebasePath = join(gsdRoot(basePath), "CODEBASE.md"); + if (!existsSync(codebasePath)) return null; + try { + return readFileSync(codebasePath, "utf-8"); + } catch { + return null; + } +} + +/** + * Get stats about the codebase map. + */ +export function getCodebaseMapStats(basePath: string): { + exists: boolean; + fileCount: number; + describedCount: number; + undescribedCount: number; + generatedAt: string | null; +} { + const content = readCodebaseMap(basePath); + if (!content) { + return { exists: false, fileCount: 0, describedCount: 0, undescribedCount: 0, generatedAt: null }; + } + + // Parse total file count from the header line (accurate even for collapsed dirs) + const fileCountMatch = content.match(/Files:\s*(\d+)/); + const totalFiles = fileCountMatch ? parseInt(fileCountMatch[1], 10) : 0; + + // Use parseCodebaseMap to count described files (includes collapsed-description blocks) + const descriptions = parseCodebaseMap(content); + const described = [...descriptions.values()].filter((d) => d.length > 0).length; + const dateMatch = content.match(/Generated: (\S+)/); + + return { + exists: true, + fileCount: totalFiles, + describedCount: described, + undescribedCount: totalFiles - described, + generatedAt: dateMatch?.[1] ?? null, + }; +} diff --git a/src/resources/extensions/gsd/commands-bootstrap.ts b/src/resources/extensions/gsd/commands-bootstrap.ts index 9a973c2d9..0f5c55cd1 100644 --- a/src/resources/extensions/gsd/commands-bootstrap.ts +++ b/src/resources/extensions/gsd/commands-bootstrap.ts @@ -45,6 +45,7 @@ const TOP_LEVEL_SUBCOMMANDS = [ { cmd: "start", desc: "Start a workflow template" }, { cmd: "templates", desc: "List available workflow templates" }, { cmd: "extensions", desc: "Manage extensions" }, + { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache" }, ] as const; function filterStartsWith( @@ -218,6 +219,15 @@ function getGsdArgumentCompletions(prefix: string) { ], "extensions"); } + if (parts[0] === "codebase" && parts.length <= 2) { + return filterStartsWith(partial, [ + { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" }, + { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately" }, + { cmd: "stats", desc: "Show codebase-map coverage and generation time" }, + { cmd: "help", desc: "Show usage and subcommands" }, + ], "codebase"); + } + if (parts[0] === "doctor" && parts.length <= 2) { return filterStartsWith(partial, [ { cmd: "fix", desc: "Auto-fix detected issues" }, diff --git a/src/resources/extensions/gsd/commands-cmux.ts b/src/resources/extensions/gsd/commands-cmux.ts index e00f2dea2..a1b8f5ee4 100644 --- a/src/resources/extensions/gsd/commands-cmux.ts +++ b/src/resources/extensions/gsd/commands-cmux.ts @@ -1,5 +1,5 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent"; -import { existsSync, readFileSync } from "node:fs"; +import { existsSync, readFileSync, writeFileSync } from "node:fs"; import { clearCmuxSidebar, CmuxClient, detectCmuxEnvironment, resolveCmuxConfig } from "../cmux/index.js"; import { saveFile } from "./files.js"; import { @@ -9,6 +9,37 @@ import { } from "./preferences.js"; import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js"; +/** + * Auto-enable cmux in project preferences when detected but never configured. + * Called at boot (before agent start) — no ExtensionCommandContext needed. + * Returns true if preferences were written, false if skipped. + */ +export function autoEnableCmuxPreferences(): boolean { + const path = getProjectGSDPreferencesPath(); + if (!existsSync(path)) return false; + + const existing = loadProjectGSDPreferences(); + const prefs: Record = existing?.preferences ? { ...existing.preferences } : { version: 1 }; + prefs.cmux = { + enabled: true, + notifications: true, + sidebar: true, + splits: false, + browser: false, + ...((prefs.cmux as Record | undefined) ?? {}), + }; + (prefs.cmux as Record).enabled = true; + prefs.version = prefs.version || 1; + + const frontmatter = serializePreferencesToFrontmatter(prefs); + let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n"; + const preserved = extractBodyAfterFrontmatter(readFileSync(path, "utf-8")); + if (preserved) body = preserved; + + writeFileSync(path, `---\n${frontmatter}---${body}`, "utf-8"); + return true; +} + function extractBodyAfterFrontmatter(content: string): string | null { const start = content.startsWith("---\n") ? 4 : content.startsWith("---\r\n") ? 5 : -1; if (start === -1) return null; diff --git a/src/resources/extensions/gsd/commands-codebase.ts b/src/resources/extensions/gsd/commands-codebase.ts new file mode 100644 index 000000000..20967e03f --- /dev/null +++ b/src/resources/extensions/gsd/commands-codebase.ts @@ -0,0 +1,197 @@ +/** + * GSD Command — /gsd codebase + * + * Generate and manage the codebase map (.gsd/CODEBASE.md). + * Subcommands: generate, update, stats, help + */ + +import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent"; + +import { + generateCodebaseMap, + updateCodebaseMap, + writeCodebaseMap, + getCodebaseMapStats, + readCodebaseMap, +} from "./codebase-generator.js"; +import { loadEffectiveGSDPreferences } from "./preferences.js"; +import type { CodebaseMapOptions } from "./codebase-generator.js"; + +const USAGE = + "Usage: /gsd codebase [generate|update|stats]\n\n" + + " generate [--max-files N] [--collapse-threshold N] — Generate or regenerate CODEBASE.md\n" + + " update [--max-files N] [--collapse-threshold N] — Refresh the CODEBASE.md cache immediately\n" + + " stats — Show file count, coverage, and generation time\n" + + " help — Show this help\n\n" + + "With no subcommand, shows stats if a map exists or help if not.\n" + + "GSD also refreshes CODEBASE.md automatically before prompt injection and after completed units when tracked files change.\n\n" + + "Configure defaults via preferences.md:\n" + + " codebase:\n" + + " exclude_patterns: [\"docs/\", \"fixtures/\"]\n" + + " max_files: 1000\n" + + " collapse_threshold: 15"; + +export async function handleCodebase( + args: string, + ctx: ExtensionCommandContext, + _pi: ExtensionAPI, +): Promise { + const basePath = process.cwd(); + const parts = args.trim().split(/\s+/); + const sub = parts[0] ?? ""; + + switch (sub) { + case "generate": { + const options = resolveCodebaseOptions(args, ctx); + if (options === false) return; // validation failed, message already shown + + const existing = readCodebaseMap(basePath); + const existingDescriptions = existing + ? (await import("./codebase-generator.js")).parseCodebaseMap(existing) + : undefined; + + const result = generateCodebaseMap(basePath, options, existingDescriptions); + + if (result.fileCount === 0) { + ctx.ui.notify( + "Codebase map generated with 0 files.\n" + + "Is this a git repository? Run 'git ls-files' to verify.", + "warning", + ); + return; + } + + const outPath = writeCodebaseMap(basePath, result.content); + ctx.ui.notify( + `Codebase map generated: ${result.fileCount} files\n` + + `Written to: ${outPath}` + + (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""), + "success", + ); + return; + } + + case "update": { + const existing = readCodebaseMap(basePath); + if (!existing) { + ctx.ui.notify( + "No codebase map found. Run /gsd codebase generate to create one.", + "warning", + ); + return; + } + + const options = resolveCodebaseOptions(args, ctx); + if (options === false) return; + + const result = updateCodebaseMap(basePath, options); + writeCodebaseMap(basePath, result.content); + + ctx.ui.notify( + `Codebase map updated: ${result.fileCount} files\n` + + ` Added: ${result.added} | Removed: ${result.removed} | Unchanged: ${result.unchanged}` + + (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""), + "success", + ); + return; + } + + case "stats": { + showStats(basePath, ctx); + return; + } + + case "help": + ctx.ui.notify(USAGE, "info"); + return; + + case "": { + // Safe default: show stats if map exists, help if not + const existing = readCodebaseMap(basePath); + if (existing) { + showStats(basePath, ctx); + } else { + ctx.ui.notify(USAGE, "info"); + } + return; + } + + default: + ctx.ui.notify( + `Unknown subcommand "${sub}".\n\n${USAGE}`, + "warning", + ); + } +} + +function showStats(basePath: string, ctx: ExtensionCommandContext): void { + const stats = getCodebaseMapStats(basePath); + if (!stats.exists) { + ctx.ui.notify("No codebase map found. Run /gsd codebase generate to create one.", "info"); + return; + } + + const coverage = stats.fileCount > 0 + ? Math.round((stats.describedCount / stats.fileCount) * 100) + : 0; + + ctx.ui.notify( + `Codebase Map Stats:\n` + + ` Files: ${stats.fileCount}\n` + + ` Described: ${stats.describedCount} (${coverage}%)\n` + + ` Undescribed: ${stats.undescribedCount}\n` + + ` Generated: ${stats.generatedAt ?? "unknown"}\n\n` + + (stats.undescribedCount > 0 + ? `Tip: Auto-refresh keeps the cache current, but /gsd codebase update forces an immediate refresh.` + : `Coverage is complete.`), + "info", + ); +} + +/** + * Resolve codebase map options by merging preferences with CLI flags. + * CLI flags override preferences; preferences override built-in defaults. + * Returns false if validation failed (error already shown to user). + */ +function resolveCodebaseOptions(args: string, ctx: ExtensionCommandContext): CodebaseMapOptions | false { + // Load preferences defaults + const prefs = loadEffectiveGSDPreferences()?.preferences?.codebase; + + // Parse CLI flags + const maxFilesStr = extractFlag(args, "--max-files"); + const collapseStr = extractFlag(args, "--collapse-threshold"); + + // Validate --max-files + let maxFiles: number | undefined; + if (maxFilesStr) { + maxFiles = parseInt(maxFilesStr, 10); + if (isNaN(maxFiles) || maxFiles < 1) { + ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning"); + return false; + } + } + + // Validate --collapse-threshold + let collapseThreshold: number | undefined; + if (collapseStr) { + collapseThreshold = parseInt(collapseStr, 10); + if (isNaN(collapseThreshold) || collapseThreshold < 1) { + ctx.ui.notify("--collapse-threshold must be a positive integer (e.g. --collapse-threshold 15).", "warning"); + return false; + } + } + + return { + // CLI flags override preferences + maxFiles: maxFiles ?? prefs?.max_files, + collapseThreshold: collapseThreshold ?? prefs?.collapse_threshold, + excludePatterns: prefs?.exclude_patterns, + }; +} + +function extractFlag(args: string, flag: string): string | undefined { + const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const regex = new RegExp(`${escaped}[=\\s]+(\\S+)`); + const match = args.match(regex); + return match?.[1]; +} diff --git a/src/resources/extensions/gsd/commands-extensions.ts b/src/resources/extensions/gsd/commands-extensions.ts index e63f90405..05b867e4f 100644 --- a/src/resources/extensions/gsd/commands-extensions.ts +++ b/src/resources/extensions/gsd/commands-extensions.ts @@ -105,7 +105,7 @@ function discoverManifests(): Map { const manifests = new Map(); if (!existsSync(extDir)) return manifests; for (const entry of readdirSync(extDir, { withFileTypes: true })) { - if (!entry.isDirectory()) continue; + if (!entry.isDirectory() && !entry.isSymbolicLink()) continue; const m = readManifest(join(extDir, entry.name)); if (m) manifests.set(m.id, m); } diff --git a/src/resources/extensions/gsd/commands-handlers.ts b/src/resources/extensions/gsd/commands-handlers.ts index e87e89bbc..1797b2cd9 100644 --- a/src/resources/extensions/gsd/commands-handlers.ts +++ b/src/resources/extensions/gsd/commands-handlers.ts @@ -20,10 +20,31 @@ import { selectDoctorScope, filterDoctorIssues, } from "./doctor.js"; -import { isAutoActive } from "./auto.js"; +import { isAutoActive, checkRemoteAutoSession } from "./auto.js"; +import { getAutoWorktreePath } from "./auto-worktree.js"; import { projectRoot } from "./commands/context.js"; import { loadPrompt } from "./prompt-loader.js"; +const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest"; +const UPDATE_FETCH_TIMEOUT_MS = 5000; + +async function fetchLatestVersionForCommand(): Promise { + const controller = new AbortController(); + const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS); + + try { + const res = await fetch(UPDATE_REGISTRY_URL, { signal: controller.signal }); + if (!res.ok) return null; + const data = (await res.json()) as { version?: string }; + const latest = typeof data.version === "string" ? data.version.trim().replace(/^v/, "") : ""; + return latest.length > 0 ? latest : null; + } catch { + return null; + } finally { + clearTimeout(timeout); + } +} + export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void { const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md"); const workflow = readFileSync(workflowPath, "utf-8"); @@ -42,21 +63,27 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, ); } -export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise { +/** Parse doctor command args into structured flags and positionals (pure, no I/O). */ +export function parseDoctorArgs(args: string) { const trimmed = args.trim(); - // Extract flags before positional parsing const jsonMode = trimmed.includes("--json"); const dryRun = trimmed.includes("--dry-run"); + const fixFlag = trimmed.includes("--fix"); const includeBuild = trimmed.includes("--build"); const includeTests = trimmed.includes("--test"); - const stripped = trimmed.replace(/--json|--dry-run|--build|--test/g, "").trim(); + const stripped = trimmed.replace(/--json|--dry-run|--build|--test|--fix/g, "").trim(); const parts = stripped ? stripped.split(/\s+/) : []; const mode = parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit" ? parts[0] : "doctor"; const requestedScope = mode === "doctor" ? parts[0] : parts[1]; + return { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope }; +} + +export async function handleDoctor(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise { + const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args); const scope = await selectDoctorScope(projectRoot(), requestedScope); const effectiveScope = mode === "audit" ? requestedScope : scope; const report = await runGSDDoctor(projectRoot(), { - fix: mode === "fix" || mode === "heal" || dryRun, + fix: mode === "fix" || mode === "heal" || dryRun || fixFlag, dryRun, scope: effectiveScope, includeBuild, @@ -222,7 +249,19 @@ export async function handleSteer(change: string, ctx: ExtensionCommandContext, const sid = state.activeSlice?.id ?? "none"; const tid = state.activeTask?.id ?? "none"; const appliedAt = `${mid}/${sid}/${tid}`; - await appendOverride(basePath, change, appliedAt); + + // Resolve the correct target path: only route to a worktree when auto-mode + // is actively running there (in-process or remote). A worktree directory may + // exist from a previous session without being the active runtime path — + // writing there without a live session would silently drop the override. + const autoRunning = isAutoActive() || checkRemoteAutoSession(basePath).running; + const wtPath = autoRunning && mid !== "none" + ? getAutoWorktreePath(basePath, mid) + : null; + const targetPath = wtPath ?? basePath; + await appendOverride(targetPath, change, appliedAt); + + const overrideLoc = wtPath ? "worktree `.gsd/OVERRIDES.md`" : "`.gsd/OVERRIDES.md`"; if (isAutoActive()) { pi.sendMessage({ @@ -232,14 +271,14 @@ export async function handleSteer(change: string, ctx: ExtensionCommandContext, "", `**Override:** ${change}`, "", - "This override has been saved to `.gsd/OVERRIDES.md` and will be injected into all future task prompts.", + `This override has been saved to ${overrideLoc} and will be injected into all future task prompts.`, "A document rewrite unit will run before the next task to propagate this change across all active plan documents.", "", "If you are mid-task, finish your current work respecting this override. The next dispatched unit will be a document rewrite.", ].join("\n"), display: false, }, { triggerTurn: true }); - ctx.ui.notify(`Override registered: "${change}". Will be applied before next task dispatch.`, "info"); + ctx.ui.notify(`Override registered (${overrideLoc}): "${change}". Will be applied before next task dispatch.`, "info"); } else { pi.sendMessage({ customType: "gsd-hard-steer", @@ -248,13 +287,13 @@ export async function handleSteer(change: string, ctx: ExtensionCommandContext, "", `**Override:** ${change}`, "", - "This override has been saved to `.gsd/OVERRIDES.md`.", - "Before continuing, read `.gsd/OVERRIDES.md` and update the current plan documents to reflect this change.", + `This override has been saved to ${overrideLoc}.`, + `Before continuing, read ${overrideLoc} and update the current plan documents to reflect this change.`, "Focus on: active slice plan, incomplete task plans, and DECISIONS.md.", ].join("\n"), display: false, }, { triggerTurn: true }); - ctx.ui.notify(`Override registered: "${change}". Update plan documents to reflect this change.`, "info"); + ctx.ui.notify(`Override registered (${overrideLoc}): "${change}". Update plan documents to reflect this change.`, "info"); } } @@ -375,13 +414,8 @@ export async function handleUpdate(ctx: ExtensionCommandContext): Promise ctx.ui.notify(`Current version: v${current}\nChecking npm registry...`, "info"); - let latest: string; - try { - latest = execSync(`npm view ${NPM_PACKAGE} version`, { - encoding: "utf-8", - stdio: ["ignore", "pipe", "ignore"], - }).trim(); - } catch { + const latest = await fetchLatestVersionForCommand(); + if (!latest) { ctx.ui.notify("Failed to reach npm registry. Check your network connection.", "error"); return; } diff --git a/src/resources/extensions/gsd/commands-inspect.ts b/src/resources/extensions/gsd/commands-inspect.ts index 87eb494b1..5421c00bf 100644 --- a/src/resources/extensions/gsd/commands-inspect.ts +++ b/src/resources/extensions/gsd/commands-inspect.ts @@ -8,6 +8,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent"; import { existsSync } from "node:fs"; import { join } from "node:path"; import { gsdRoot } from "./paths.js"; +import { logWarning } from "./workflow-logger.js"; import { getErrorMessage } from "./error-utils.js"; export interface InspectData { @@ -92,7 +93,7 @@ export async function handleInspect(ctx: ExtensionCommandContext): Promise ctx.ui.notify(formatInspectOutput(data), "info"); } catch (err) { - process.stderr.write(`gsd-db: /gsd inspect failed: ${getErrorMessage(err)}\n`); + logWarning("command", `/gsd inspect failed: ${getErrorMessage(err)}`); ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error"); } } diff --git a/src/resources/extensions/gsd/commands-maintenance.ts b/src/resources/extensions/gsd/commands-maintenance.ts index d2661a605..09d9df9dc 100644 --- a/src/resources/extensions/gsd/commands-maintenance.ts +++ b/src/resources/extensions/gsd/commands-maintenance.ts @@ -7,12 +7,14 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent"; import { deriveState } from "./state.js"; import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js"; +import { logWarning } from "./workflow-logger.js"; export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePath: string): Promise { let branches: string[]; try { branches = nativeBranchList(basePath, "gsd/*"); - } catch { + } catch (e) { + logWarning("command", `branch list failed: ${(e as Error).message}`); ctx.ui.notify("No GSD branches to clean up.", "info"); return; } @@ -23,7 +25,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa let merged: string[]; try { merged = nativeBranchListMerged(basePath, mainBranch, "gsd/*"); - } catch { + } catch (e) { + logWarning("command", `merged branch list failed: ${(e as Error).message}`); merged = []; } @@ -33,8 +36,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa try { nativeBranchDelete(basePath, branch, false); deletedMerged++; - } catch { - /* skip branches that cannot be deleted */ + } catch (e) { + logWarning("command", `branch delete failed for ${branch}: ${(e as Error).message}`); } } @@ -66,7 +69,7 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa try { nativeBranchDelete(basePath, branch, true); deletedStaleMilestones++; - } catch { /* non-fatal */ } + } catch (e) { logWarning("command", `stale milestone branch delete failed for ${branch}: ${(e as Error).message}`); } continue; } } @@ -77,7 +80,8 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa let roadmapContent: string | null = null; try { roadmapContent = await loadFile(roadmapPath); - } catch { + } catch (e) { + logWarning("command", `loadFile failed for ${roadmapPath}: ${(e as Error).message}`); roadmapContent = null; } if (!roadmapContent) continue; @@ -85,12 +89,12 @@ export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePa try { nativeBranchDelete(basePath, branch, true); deletedStaleMilestones++; - } catch { - /* non-fatal */ + } catch (e) { + logWarning("command", `milestone branch delete failed for ${branch}: ${(e as Error).message}`); } } - } catch { - /* non-fatal */ + } catch (e) { + logWarning("command", `stale milestone cleanup failed: ${(e as Error).message}`); } const summary: string[] = []; @@ -122,7 +126,8 @@ export async function handleCleanupSnapshots(ctx: ExtensionCommandContext, baseP let refs: string[]; try { refs = nativeForEachRef(basePath, "refs/gsd/snapshots/"); - } catch { + } catch (e) { + logWarning("command", `snapshot ref list failed: ${(e as Error).message}`); ctx.ui.notify("No snapshot refs to clean up.", "info"); return; } @@ -147,8 +152,8 @@ export async function handleCleanupSnapshots(ctx: ExtensionCommandContext, baseP try { nativeUpdateRef(basePath, old); pruned++; - } catch { - /* skip individual failures */ + } catch (e) { + logWarning("command", `snapshot ref update failed for ${old}: ${(e as Error).message}`); } } } @@ -164,7 +169,8 @@ export async function handleCleanupWorktrees(ctx: ExtensionCommandContext, baseP let statuses; try { statuses = getAllWorktreeHealth(basePath); - } catch { + } catch (e) { + logWarning("command", `worktree health inspection failed: ${(e as Error).message}`); ctx.ui.notify("Failed to inspect worktrees.", "error"); return; } @@ -197,7 +203,8 @@ export async function handleCleanupWorktrees(ctx: ExtensionCommandContext, baseP removeWorktree(basePath, wt.name, { deleteBranch: true }); lines.push(` ✓ ${wt.name} removed (branch ${wt.branch} deleted)`); removed++; - } catch { + } catch (e) { + logWarning("command", `worktree removal failed for ${wt.name}: ${(e as Error).message}`); lines.push(` ✗ ${wt.name} failed to remove`); } } @@ -246,7 +253,7 @@ export async function handleSkip(unitArg: string, ctx: ExtensionCommandContext, if (fileExists(completedKeysFile)) { keys = JSON.parse(readFile(completedKeysFile, "utf-8")); } - } catch { /* start fresh */ } + } catch (e) { logWarning("command", `completed-units.json parse failed: ${(e as Error).message}`); } // Normalize: accept "execute-task/M001/S01/T03", "M001/S01/T03", or just "T03" let skipKey = unitArg; @@ -371,7 +378,8 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC hashList = readdirSync(projectsDir, { withFileTypes: true }) .filter(e => e.isDirectory()) .map(e => e.name); - } catch { + } catch (e) { + logWarning("command", `readdir failed for project-state directory: ${(e as Error).message}`); ctx.ui.notify(`Failed to read project-state directory at ${projectsDir}.`, "error"); return; } @@ -454,7 +462,8 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC try { fsRmSync(pathJoin(projectsDir, e.hash), { recursive: true, force: true }); removed++; - } catch { + } catch (err) { + logWarning("command", `project cleanup rm failed for ${e.hash}: ${(err as Error).message}`); failed.push(e.hash); } } @@ -529,7 +538,7 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri ctx.ui.notify(lines.join("\n"), "success"); } catch (err) { const msg = err instanceof Error ? err.message : String(err); - process.stderr.write(`gsd-recover: failed: ${msg}\n`); + logWarning("command", `recover failed: ${msg}`); ctx.ui.notify(`gsd recover failed: ${msg}`, "error"); } } diff --git a/src/resources/extensions/gsd/commands-mcp-status.ts b/src/resources/extensions/gsd/commands-mcp-status.ts index 560e58d03..c574f6daf 100644 --- a/src/resources/extensions/gsd/commands-mcp-status.ts +++ b/src/resources/extensions/gsd/commands-mcp-status.ts @@ -7,12 +7,15 @@ * /gsd mcp — Overview of all servers (alias: /gsd mcp status) * /gsd mcp status — Same as bare /gsd mcp * /gsd mcp check — Detailed status for a specific server + * /gsd mcp init [dir] — Write project-local GSD workflow MCP config */ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent"; import { existsSync, readFileSync } from "node:fs"; -import { join } from "node:path"; +import { join, resolve } from "node:path"; + +import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js"; // ─── Types ────────────────────────────────────────────────────────────────── @@ -28,6 +31,28 @@ export interface McpServerDetail extends McpServerStatus { tools: string[]; } +export function formatMcpInitResult( + status: "created" | "updated" | "unchanged", + configPath: string, + targetPath: string, +): string { + const summary = + status === "created" + ? "Created project MCP config." + : status === "updated" + ? "Updated project MCP config." + : "Project MCP config is already up to date."; + + return [ + summary, + "", + `Project: ${targetPath}`, + `Config: ${configPath}`, + "", + "Claude Code can now load the GSD workflow MCP server from this folder.", + ].join("\n"); +} + // ─── Config reader (standalone — does not import mcp-client internals) ────── interface McpServerRawConfig { @@ -94,6 +119,7 @@ export function formatMcpStatusReport(servers: McpServerStatus[]): string { "No MCP servers configured.", "", "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.", + "Tip: run /gsd mcp init . to write the local GSD workflow MCP config.", "See: https://modelcontextprotocol.io/quickstart", ].join("\n"); } @@ -153,12 +179,31 @@ export async function handleMcpStatus( args: string, ctx: ExtensionCommandContext, ): Promise { - const trimmed = args.trim().toLowerCase(); + const trimmed = args.trim(); + const lowered = trimmed.toLowerCase(); const configs = readMcpConfigs(); + // /gsd mcp init [dir] + if (!lowered || lowered === "status") { + // handled below + } else if (lowered === "init" || lowered.startsWith("init ")) { + const rawPath = trimmed.slice("init".length).trim(); + const targetPath = resolve(rawPath || "."); + try { + const result = ensureProjectWorkflowMcpConfig(targetPath); + ctx.ui.notify(formatMcpInitResult(result.status, result.configPath, targetPath), "info"); + } catch (err) { + ctx.ui.notify( + `Failed to prepare MCP config for ${targetPath}: ${err instanceof Error ? err.message : String(err)}`, + "error", + ); + } + return; + } + // /gsd mcp check - if (trimmed.startsWith("check ")) { - const serverName = args.trim().slice("check ".length).trim(); + if (lowered.startsWith("check ")) { + const serverName = trimmed.slice("check ".length).trim(); const config = configs.find((c) => c.name === serverName); if (!config) { const available = configs.map((c) => c.name).join(", ") || "(none)"; @@ -202,7 +247,7 @@ export async function handleMcpStatus( } // /gsd mcp or /gsd mcp status - if (!trimmed || trimmed === "status") { + if (!lowered || lowered === "status") { // Build status for each server const statuses: McpServerStatus[] = []; @@ -239,9 +284,10 @@ export async function handleMcpStatus( // Unknown subcommand ctx.ui.notify( - "Usage: /gsd mcp [status|check ]\n\n" + + "Usage: /gsd mcp [status|check |init [dir]]\n\n" + " status Show all MCP server statuses (default)\n" + - " check Detailed status for a specific server", + " check Detailed status for a specific server\n" + + " init [dir] Write .mcp.json for the local GSD workflow MCP server", "warning", ); } diff --git a/src/resources/extensions/gsd/commands-prefs-wizard.ts b/src/resources/extensions/gsd/commands-prefs-wizard.ts index 98d12be78..f94a78010 100644 --- a/src/resources/extensions/gsd/commands-prefs-wizard.ts +++ b/src/resources/extensions/gsd/commands-prefs-wizard.ts @@ -165,10 +165,10 @@ export function buildCategorySummaries(prefs: Record): Record | undefined; + const models = prefs.models as Record | undefined; let modelsSummary = "(not configured)"; if (models && Object.keys(models).length > 0) { - const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${model}`); + const parts = Object.entries(models).map(([phase, model]) => `${phase}: ${formatConfiguredModel(model)}`); modelsSummary = parts.join(", "); } @@ -184,11 +184,23 @@ export function buildCategorySummaries(prefs: Record): Record | undefined; + const staleThreshold = prefs.stale_commit_threshold_minutes; + const absorbSnapshots = git?.absorb_snapshot_commits; let gitSummary = "(defaults)"; - if (git && Object.keys(git).length > 0) { - const branch = git.main_branch ?? "main"; - const push = git.auto_push ? "on" : "off"; - gitSummary = `main: ${branch}, push: ${push}`; + { + const parts: string[] = []; + if (git && Object.keys(git).length > 0) { + const branch = git.main_branch ?? "main"; + const push = git.auto_push ? "on" : "off"; + parts.push(`main: ${branch}, push: ${push}`); + } + if (staleThreshold !== undefined) { + parts.push(`stale: ${staleThreshold === 0 ? "off" : `${staleThreshold}m`}`); + } + if (absorbSnapshots !== undefined) { + parts.push(`absorb: ${absorbSnapshots ? "on" : "off"}`); + } + if (parts.length > 0) gitSummary = parts.join(", "); } // Skills @@ -243,9 +255,38 @@ export function buildCategorySummaries(prefs: Record): Record): Promise { - const modelPhases = ["research", "planning", "execution", "completion"] as const; - const models: Record = (prefs.models as Record) ?? {}; + const modelPhases = [ + "research", + "planning", + "discuss", + "execution", + "execution_simple", + "completion", + "validation", + "subagent", + ] as const; + const models: Record = (prefs.models as Record) ?? {}; const availableModels = ctx.modelRegistry.getAvailable(); if (availableModels.length > 0) { @@ -265,15 +306,22 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record a.id.localeCompare(b.id)); } - // Build provider menu with model counts + // Display names for providers in the preferences wizard UI. + const PROVIDER_DISPLAY_NAMES: Record = { anthropic: "anthropic-api" }; + const displayName = (p: string) => PROVIDER_DISPLAY_NAMES[p] ?? p; + + // Build provider menu with model counts (display name → real name lookup) + const displayToReal = new Map(); const providerOptions = providers.map(p => { const count = byProvider.get(p)!.length; - return `${p} (${count} models)`; + const label = `${displayName(p)} (${count} models)`; + displayToReal.set(label, p); + return label; }); providerOptions.push("(keep current)", "(clear)", "(type manually)"); for (const phase of modelPhases) { - const current = models[phase] ?? ""; + const current = formatConfiguredModel(models[phase]); const phaseLabel = `Model for ${phase} phase${current ? ` (current: ${current})` : ""}`; // Step 1: pick provider @@ -298,25 +346,25 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record m.id); modelOptions.push("(keep current)", "(clear)"); - const modelChoice = await ctx.ui.select(`${phaseLabel} — ${providerName}:`, modelOptions); + const modelChoice = await ctx.ui.select(`${phaseLabel} — ${displayName(providerName)}:`, modelOptions); if (modelChoice && typeof modelChoice === "string" && modelChoice !== "(keep current)") { if (modelChoice === "(clear)") { delete models[phase]; } else { - models[phase] = modelChoice; + models[phase] = toPersistedModelId(providerName, modelChoice); } } } } else { for (const phase of modelPhases) { - const current = models[phase] ?? ""; + const current = formatConfiguredModel(models[phase]); const input = await ctx.ui.input( `Model for ${phase} phase${current ? ` (current: ${current})` : ""}:`, current || "e.g. claude-sonnet-4-20250514", @@ -333,6 +381,8 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record 0) { prefs.models = models; + } else { + delete prefs.models; } } @@ -469,9 +519,39 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record 0) { prefs.git = git; } + + // stale_commit_threshold_minutes (top-level pref, shown in Git section) + const currentThreshold = prefs.stale_commit_threshold_minutes; + const thresholdStr = currentThreshold !== undefined ? String(currentThreshold) : ""; + const thresholdInput = await ctx.ui.input( + `Stale commit threshold (minutes, 0 to disable)${thresholdStr ? ` (current: ${thresholdStr})` : " (default: 30)"}:`, + thresholdStr || "30", + ); + if (thresholdInput !== null && thresholdInput !== undefined) { + const val = thresholdInput.trim(); + const parsed = tryParseInteger(val); + if (val && parsed !== null && parsed >= 0) { + prefs.stale_commit_threshold_minutes = parsed; + } else if (val && parsed === null) { + ctx.ui.notify(`Invalid value "${val}" — must be a whole number. Keeping previous value.`, "warning"); + } else if (!val && currentThreshold !== undefined) { + delete prefs.stale_commit_threshold_minutes; + } + } } async function configureSkills(ctx: ExtensionCommandContext, prefs: Record): Promise { diff --git a/src/resources/extensions/gsd/commands/catalog.ts b/src/resources/extensions/gsd/commands/catalog.ts index 7d688d41c..29858541e 100644 --- a/src/resources/extensions/gsd/commands/catalog.ts +++ b/src/resources/extensions/gsd/commands/catalog.ts @@ -15,7 +15,7 @@ export interface GsdCommandDefinition { type CompletionMap = Record; export const GSD_COMMAND_DESCRIPTION = - "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink"; + "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications"; export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [ { cmd: "help", desc: "Categorized command reference with descriptions" }, @@ -41,6 +41,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [ { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" }, { cmd: "export", desc: "Export milestone/slice results" }, { cmd: "cleanup", desc: "Remove merged branches or snapshots" }, + { cmd: "model", desc: "Switch the active session model or open a picker" }, { cmd: "mode", desc: "Switch workflow mode (solo/team)" }, { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" }, { cmd: "config", desc: "Set API keys for external tools" }, @@ -48,6 +49,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [ { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" }, { cmd: "run-hook", desc: "Manually trigger a specific hook" }, { cmd: "skill-health", desc: "Skill lifecycle dashboard" }, + { cmd: "notifications", desc: "View, filter, and clear persistent notification history" }, { cmd: "doctor", desc: "Runtime health checks with auto-fix" }, { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" }, { cmd: "forensics", desc: "Examine execution logs" }, @@ -68,9 +70,10 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [ { cmd: "templates", desc: "List available workflow templates" }, { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" }, { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" }, - { cmd: "mcp", desc: "MCP server status and connectivity check (status, check )" }, + { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" }, { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" }, { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" }, + { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" }, ]; const NESTED_COMPLETIONS: CompletionMap = { @@ -109,6 +112,11 @@ const NESTED_COMPLETIONS: CompletionMap = { { cmd: "keys", desc: "Manage API keys" }, { cmd: "prefs", desc: "Configure global preferences" }, ], + notifications: [ + { cmd: "clear", desc: "Clear all notifications" }, + { cmd: "tail", desc: "Show last N notifications (default: 20)" }, + { cmd: "filter", desc: "Filter by severity (error|warning|info|success)" }, + ], logs: [ { cmd: "debug", desc: "List or view debug log files" }, { cmd: "tail", desc: "Show last N activity log summaries" }, @@ -193,6 +201,7 @@ const NESTED_COMPLETIONS: CompletionMap = { mcp: [ { cmd: "status", desc: "Show all MCP server statuses (default)" }, { cmd: "check", desc: "Detailed status for a specific server" }, + { cmd: "init", desc: "Write .mcp.json for the local GSD workflow MCP server" }, ], doctor: [ { cmd: "fix", desc: "Auto-fix detected issues" }, @@ -225,6 +234,16 @@ const NESTED_COMPLETIONS: CompletionMap = { { cmd: "pause", desc: "Pause custom workflow auto-mode" }, { cmd: "resume", desc: "Resume paused custom workflow auto-mode" }, ], + codebase: [ + { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" }, + { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" }, + { cmd: "generate --collapse-threshold", desc: "Generate with custom collapse threshold (default: 20)" }, + { cmd: "update", desc: "Refresh the CODEBASE.md cache immediately (preserves descriptions)" }, + { cmd: "update --max-files", desc: "Update with custom file limit" }, + { cmd: "update --collapse-threshold", desc: "Update with custom collapse threshold" }, + { cmd: "stats", desc: "Show file count, description coverage, and generation time" }, + { cmd: "help", desc: "Show usage and available subcommands" }, + ], }; function filterOptions( diff --git a/src/resources/extensions/gsd/commands/context.ts b/src/resources/extensions/gsd/commands/context.ts index 7bbaa5790..f4a5aa423 100644 --- a/src/resources/extensions/gsd/commands/context.ts +++ b/src/resources/extensions/gsd/commands/context.ts @@ -13,7 +13,13 @@ export interface GsdDispatchContext { } export function projectRoot(): string { - const cwd = process.cwd(); + let cwd: string; + try { + cwd = process.cwd(); + } catch { + // cwd directory was deleted (e.g. worktree teardown) — fall back to HOME (#3598) + cwd = process.env.HOME ?? "/"; + } const root = resolveProjectRoot(cwd); if (root !== cwd) { assertSafeDirectory(cwd); diff --git a/src/resources/extensions/gsd/commands/dispatcher.ts b/src/resources/extensions/gsd/commands/dispatcher.ts index 9f28cbbaa..a3d11344b 100644 --- a/src/resources/extensions/gsd/commands/dispatcher.ts +++ b/src/resources/extensions/gsd/commands/dispatcher.ts @@ -14,7 +14,7 @@ export async function handleGSDCommand( const trimmed = (typeof args === "string" ? args : "").trim(); const handlers = [ - () => handleCoreCommand(trimmed, ctx), + () => handleCoreCommand(trimmed, ctx, pi), () => handleAutoCommand(trimmed, ctx, pi), () => handleParallelCommand(trimmed, ctx, pi), () => handleWorkflowCommand(trimmed, ctx, pi), @@ -29,4 +29,3 @@ export async function handleGSDCommand( ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning"); } - diff --git a/src/resources/extensions/gsd/commands/handlers/core.ts b/src/resources/extensions/gsd/commands/handlers/core.ts index c915f0486..e6824815c 100644 --- a/src/resources/extensions/gsd/commands/handlers/core.ts +++ b/src/resources/extensions/gsd/commands/handlers/core.ts @@ -1,4 +1,5 @@ -import type { ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent"; +import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent"; +import type { Model } from "@gsd/pi-ai"; import type { GSDState } from "../../types.js"; import { computeProgressScore, formatProgressLine } from "../../progress-score.js"; @@ -8,6 +9,7 @@ import { runEnvironmentChecks } from "../../doctor-environment.js"; import { deriveState } from "../../state.js"; import { handleCmux } from "../../commands-cmux.js"; import { projectRoot } from "../context.js"; +import { formatShortcut } from "../../files.js"; export function showHelp(ctx: ExtensionCommandContext): void { const lines = [ @@ -24,11 +26,12 @@ export function showHelp(ctx: ExtensionCommandContext): void { " /gsd new-milestone Create milestone from headless context (used by gsd headless)", "", "VISIBILITY", - " /gsd status Show progress dashboard (Ctrl+Alt+G)", + ` /gsd status Show progress dashboard (${formatShortcut("Ctrl+Alt+G")})`, " /gsd visualize Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)", " /gsd queue Show queued/dispatched units and execution order", " /gsd history View execution history [--cost] [--phase] [--model] [N]", " /gsd changelog Show categorized release notes [version]", + ` /gsd notifications View persistent notification history [clear|tail|filter] (${formatShortcut("Ctrl+Alt+N")})`, "", "COURSE CORRECTION", " /gsd steer Apply user override to active work", @@ -42,19 +45,22 @@ export function showHelp(ctx: ExtensionCommandContext): void { "", "PROJECT KNOWLEDGE", " /gsd knowledge Add rule, pattern, or lesson to KNOWLEDGE.md", + " /gsd codebase [generate|update|stats] Manage the CODEBASE.md cache used in prompt context", "", "SETUP & CONFIGURATION", " /gsd init Project init wizard — detect, configure, bootstrap .gsd/", " /gsd setup Global setup status [llm|search|remote|keys|prefs]", + " /gsd model Switch active session model [provider/model|model-id]", " /gsd mode Set workflow mode (solo/team) [global|project]", " /gsd prefs Manage preferences [global|project|status|wizard|setup|import-claude]", " /gsd cmux Manage cmux integration [status|on|off|notifications|sidebar|splits|browser]", " /gsd config Set API keys for external tools", " /gsd keys API key manager [list|add|remove|test|rotate|doctor]", + " /gsd show-config Show effective configuration (models, routing, toggles)", " /gsd hooks Show post-unit hook configuration", " /gsd extensions Manage extensions [list|enable|disable|info]", " /gsd fast Toggle OpenAI service tier [on|off|flex|status]", - " /gsd mcp MCP server status and connectivity [status|check ]", + " /gsd mcp MCP server status and connectivity [status|check |init [dir]]", "", "MAINTENANCE", " /gsd doctor Diagnose and repair .gsd/ state [audit|fix|heal] [scope]", @@ -70,6 +76,9 @@ export function showHelp(ctx: ExtensionCommandContext): void { export async function handleStatus(ctx: ExtensionCommandContext): Promise { const basePath = projectRoot(); + // Open DB in cold sessions so status uses DB-backed state, not filesystem fallback (#3385) + const { ensureDbOpen } = await import("../../bootstrap/dynamic-tools.js"); + await ensureDbOpen(); const state = await deriveState(basePath); if (state.registry.length === 0) { @@ -78,8 +87,8 @@ export async function handleStatus(ctx: ExtensionCommandContext): Promise } const { GSDDashboardOverlay } = await import("../../dashboard-overlay.js"); - const result = await ctx.ui.custom( - (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done()), + const result = await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDDashboardOverlay(tui, theme, () => done(true)), { overlay: true, overlayOptions: { @@ -107,8 +116,8 @@ export async function handleVisualize(ctx: ExtensionCommandContext): Promise( - (tui, theme, _kb, done) => new GSDVisualizerOverlay(tui, theme, () => done()), + const result = await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDVisualizerOverlay(tui, theme, () => done(true)), { overlay: true, overlayOptions: { @@ -173,7 +182,133 @@ export async function handleSetup(args: string, ctx: ExtensionCommandContext): P ); } -export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandContext): Promise { +function sortModelsForSelection(models: Model[], currentModel: Model | undefined): Model[] { + return [...models].sort((a, b) => { + const aCurrent = currentModel && a.provider === currentModel.provider && a.id === currentModel.id; + const bCurrent = currentModel && b.provider === currentModel.provider && b.id === currentModel.id; + if (aCurrent && !bCurrent) return -1; + if (!aCurrent && bCurrent) return 1; + const providerCmp = a.provider.localeCompare(b.provider); + if (providerCmp !== 0) return providerCmp; + return a.id.localeCompare(b.id); + }); +} + +function buildProviderModelGroups( + models: Model[], + currentModel: Model | undefined, +): Map[]> { + const byProvider = new Map[]>(); + + for (const model of sortModelsForSelection(models, currentModel)) { + let group = byProvider.get(model.provider); + if (!group) { + group = []; + byProvider.set(model.provider, group); + } + group.push(model); + } + return byProvider; +} + +async function selectModelByProvider( + title: string, + models: Model[], + ctx: ExtensionCommandContext, + currentModel: Model | undefined, +): Promise | undefined> { + const byProvider = buildProviderModelGroups(models, currentModel); + const providerOptions = Array.from(byProvider.entries()).map(([provider, group]) => + `${provider} (${group.length} model${group.length === 1 ? "" : "s"})`, + ); + providerOptions.push("(cancel)"); + + const providerChoice = await ctx.ui.select(`${title} — choose provider:`, providerOptions); + if (!providerChoice || typeof providerChoice !== "string" || providerChoice === "(cancel)") return undefined; + + const providerName = providerChoice.replace(/ \(\d+ models?\)$/, ""); + const providerModels = byProvider.get(providerName); + if (!providerModels || providerModels.length === 0) return undefined; + + const optionToModel = new Map>(); + const modelOptions = providerModels.map((model) => { + const isCurrent = currentModel && model.provider === currentModel.provider && model.id === currentModel.id; + const label = `${isCurrent ? "* " : ""}${model.id}`; + optionToModel.set(label, model); + return label; + }); + modelOptions.push("(cancel)"); + + const modelChoice = await ctx.ui.select(`${title} — ${providerName}:`, modelOptions); + if (!modelChoice || typeof modelChoice !== "string" || modelChoice === "(cancel)") return undefined; + return optionToModel.get(modelChoice); +} + +async function resolveRequestedModel( + query: string, + ctx: ExtensionCommandContext, +): Promise | undefined> { + const { resolveModelId } = await import("../../auto-model-selection.js"); + const models = ctx.modelRegistry.getAvailable(); + const exact = resolveModelId(query, models, ctx.model?.provider); + if (exact) return exact; + + const lowerQuery = query.toLowerCase(); + const partialMatches = models.filter((model) => + model.id.toLowerCase().includes(lowerQuery) + || `${model.provider}/${model.id}`.toLowerCase().includes(lowerQuery), + ); + + if (partialMatches.length === 1) return partialMatches[0]; + if (partialMatches.length === 0 || !ctx.hasUI) return undefined; + return selectModelByProvider(`Multiple models match "${query}"`, partialMatches, ctx, ctx.model); +} + +async function handleModel(trimmedArgs: string, ctx: ExtensionCommandContext, pi: ExtensionAPI | undefined): Promise { + const availableModels = ctx.modelRegistry.getAvailable(); + if (availableModels.length === 0) { + ctx.ui.notify("No available models found. Check provider auth and model discovery.", "warning"); + return; + } + if (!pi) { + ctx.ui.notify("Model switching is unavailable in this context.", "warning"); + return; + } + + const trimmed = trimmedArgs.trim(); + let targetModel: Model | undefined; + + if (!trimmed) { + if (!ctx.hasUI) { + const current = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "(none)"; + ctx.ui.notify(`Current model: ${current}\nUsage: /gsd model `, "info"); + return; + } + + targetModel = await selectModelByProvider("Select session model:", availableModels, ctx, ctx.model); + } else { + targetModel = await resolveRequestedModel(trimmed, ctx); + } + + if (!targetModel) { + ctx.ui.notify(`Model "${trimmed}" not found. Use /gsd model with an exact provider/model or a unique model ID.`, "warning"); + return; + } + + const ok = await pi.setModel(targetModel); + if (!ok) { + ctx.ui.notify(`No API key for ${targetModel.provider}/${targetModel.id}`, "warning"); + return; + } + + ctx.ui.notify(`Model: ${targetModel.provider}/${targetModel.id}`, "info"); +} + +export async function handleCoreCommand( + trimmed: string, + ctx: ExtensionCommandContext, + pi?: ExtensionAPI, +): Promise { if (trimmed === "help" || trimmed === "h" || trimmed === "?") { showHelp(ctx); return true; @@ -197,6 +332,10 @@ export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandCo ctx.ui.notify(`Widget: ${getWidgetMode()}`, "info"); return true; } + if (trimmed === "model" || trimmed.startsWith("model ")) { + await handleModel(trimmed.replace(/^model\s*/, "").trim(), ctx, pi); + return true; + } if (trimmed === "mode" || trimmed.startsWith("mode ")) { const modeArgs = trimmed.replace(/^mode\s*/, "").trim(); const scope = modeArgs === "project" ? "project" : "global"; @@ -213,6 +352,25 @@ export async function handleCoreCommand(trimmed: string, ctx: ExtensionCommandCo await handleCmux(trimmed.replace(/^cmux\s*/, "").trim(), ctx); return true; } + if (trimmed === "show-config") { + const { GSDConfigOverlay, formatConfigText } = await import("../../config-overlay.js"); + const result = await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDConfigOverlay(tui, theme, () => done(true)), + { + overlay: true, + overlayOptions: { + width: "65%", + minWidth: 55, + maxHeight: "85%", + anchor: "center", + }, + }, + ); + if (result === undefined) { + ctx.ui.notify(formatConfigText(), "info"); + } + return true; + } if (trimmed === "setup" || trimmed.startsWith("setup ")) { await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx); return true; diff --git a/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts b/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts new file mode 100644 index 000000000..16d30d49a --- /dev/null +++ b/src/resources/extensions/gsd/commands/handlers/notifications-handler.ts @@ -0,0 +1,140 @@ +// GSD Extension — /gsd notifications Command Handler +// View, filter, and clear the persistent notification history. + +import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent"; + +import { + readNotifications, + clearNotifications, + getUnreadCount, + suppressPersistence, + unsuppressPersistence, + type NotifySeverity, +} from "../../notification-store.js"; +import { GSDNotificationOverlay } from "../../notification-overlay.js"; + +function severityIcon(severity: NotifySeverity): string { + switch (severity) { + case "error": return "✗"; + case "warning": return "⚠"; + case "success": return "✓"; + case "info": + default: return "●"; + } +} + +function formatTimestamp(ts: string): string { + try { + const d = new Date(ts); + return d.toLocaleString("en-US", { hour12: false, month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" }); + } catch { + return ts.slice(0, 19); + } +} + +export async function handleNotificationsCommand( + args: string, + ctx: ExtensionCommandContext, + pi: ExtensionAPI, +): Promise { + // /gsd notifications clear + if (args === "clear") { + clearNotifications(); + // Suppress persistence so the confirmation toast doesn't re-populate the store + suppressPersistence(); + try { + ctx.ui.notify("All notifications cleared.", "success"); + } finally { + unsuppressPersistence(); + } + return true; + } + + // /gsd notifications tail [N] + if (args === "tail" || args.startsWith("tail ")) { + const countStr = args.replace(/^tail\s*/, "").trim(); + const count = countStr ? parseInt(countStr, 10) : 20; + const n = isNaN(count) || count < 1 ? 20 : Math.min(count, 100); + const entries = readNotifications().slice(0, n); + + if (entries.length === 0) { + ctx.ui.notify("No notifications.", "info"); + return true; + } + + const lines = entries.map((e) => + `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`, + ); + ctx.ui.notify(`Last ${entries.length} notification(s):\n${lines.join("\n")}`, "info"); + return true; + } + + // /gsd notifications filter + if (args.startsWith("filter ")) { + const severity = args.replace(/^filter\s+/, "").trim().toLowerCase(); + if (!["error", "warning", "info", "success"].includes(severity)) { + ctx.ui.notify("Usage: /gsd notifications filter ", "warning"); + return true; + } + const entries = readNotifications().filter((e) => e.severity === severity); + + if (entries.length === 0) { + ctx.ui.notify(`No ${severity} notifications.`, "info"); + return true; + } + + const lines = entries.slice(0, 20).map((e) => + `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`, + ); + const suffix = entries.length > 20 ? `\n... and ${entries.length - 20} more` : ""; + ctx.ui.notify(`${severity} notifications (${entries.length}):\n${lines.join("\n")}${suffix}`, "info"); + return true; + } + + // /gsd notifications (no args) — open overlay in TUI, or print summary + if (args === "" || args === "status") { + // Try overlay first (TUI mode) + if (ctx.hasUI) { + try { + await ctx.ui.custom( + (tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done()), + { + overlay: true, + overlayOptions: { + width: "80%", + minWidth: 60, + maxHeight: "88%", + anchor: "center", + backdrop: true, + }, + }, + ); + return true; + } catch { + // Fall through to text output if overlay fails + } + } + + // Text fallback (RPC/headless mode) + const unread = getUnreadCount(); + const entries = readNotifications().slice(0, 10); + if (entries.length === 0) { + ctx.ui.notify("No notifications.", "info"); + return true; + } + + const lines = entries.map((e) => + `${severityIcon(e.severity)} [${formatTimestamp(e.ts)}] ${e.message}`, + ); + const header = unread > 0 ? `${unread} unread — ` : ""; + ctx.ui.notify(`${header}Recent notifications:\n${lines.join("\n")}`, "info"); + return true; + } + + // Unknown subcommand + ctx.ui.notify( + "Usage: /gsd notifications [clear|tail [N]|filter ]", + "warning", + ); + return true; +} diff --git a/src/resources/extensions/gsd/commands/handlers/ops.ts b/src/resources/extensions/gsd/commands/handlers/ops.ts index a1996dfef..532a4b4ec 100644 --- a/src/resources/extensions/gsd/commands/handlers/ops.ts +++ b/src/resources/extensions/gsd/commands/handlers/ops.ts @@ -178,6 +178,11 @@ Examples: await dispatchDirectPhase(ctx, pi, phase, projectRoot()); return true; } + if (trimmed === "notifications" || trimmed.startsWith("notifications ")) { + const { handleNotificationsCommand } = await import("./notifications-handler.js"); + await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi); + return true; + } if (trimmed === "inspect") { await handleInspect(ctx); return true; @@ -206,5 +211,10 @@ Examples: await handleRethink(trimmed, ctx, pi); return true; } + if (trimmed === "codebase" || trimmed.startsWith("codebase ")) { + const { handleCodebase } = await import("../../commands-codebase.js"); + await handleCodebase(trimmed.replace(/^codebase\s*/, "").trim(), ctx, pi); + return true; + } return false; } diff --git a/src/resources/extensions/gsd/commands/index.ts b/src/resources/extensions/gsd/commands/index.ts index 38f55e0bb..c07476532 100644 --- a/src/resources/extensions/gsd/commands/index.ts +++ b/src/resources/extensions/gsd/commands/index.ts @@ -8,7 +8,13 @@ export function registerGSDCommand(pi: ExtensionAPI): void { getArgumentCompletions: getGsdArgumentCompletions, handler: async (args: string, ctx: ExtensionCommandContext) => { const { handleGSDCommand } = await import("./dispatcher.js"); - await handleGSDCommand(args, ctx, pi); + const { setStderrLoggingEnabled } = await import("../workflow-logger.js"); + const previousStderrSetting = setStderrLoggingEnabled(false); + try { + await handleGSDCommand(args, ctx, pi); + } finally { + setStderrLoggingEnabled(previousStderrSetting); + } }, }); } diff --git a/src/resources/extensions/gsd/complexity-classifier.ts b/src/resources/extensions/gsd/complexity-classifier.ts index 73e505958..82027227f 100644 --- a/src/resources/extensions/gsd/complexity-classifier.ts +++ b/src/resources/extensions/gsd/complexity-classifier.ts @@ -16,6 +16,7 @@ export interface ClassificationResult { tier: ComplexityTier; reason: string; downgraded: boolean; // true if budget pressure lowered the tier + taskMetadata?: TaskMetadata; } export interface TaskMetadata { @@ -35,15 +36,17 @@ const UNIT_TYPE_TIERS: Record = { "complete-slice": "light", "run-uat": "light", - // Tier 2 — Standard: research, routine planning, discussion + // Tier 2 — Standard: research, routine discussion "discuss-milestone": "standard", "discuss-slice": "standard", "research-milestone": "standard", "research-slice": "standard", - "plan-milestone": "standard", - "plan-slice": "standard", - // Tier 3 — Heavy: execution, replanning (requires deep reasoning) + // Tier 3 — Heavy: planning, execution, replanning (requires deep reasoning) + // Planning is heavy so it uses the best configured model (e.g. Opus) and is + // not downgraded by dynamic routing when a capable model is configured. + "plan-milestone": "heavy", + "plan-slice": "heavy", "execute-task": "standard", // default standard, upgraded by metadata "replan-slice": "heavy", "reassess-roadmap": "heavy", @@ -69,17 +72,20 @@ export function classifyUnitComplexity( ): ClassificationResult { // Hook units default to light if (unitType.startsWith("hook/")) { - const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false }; + const result: ClassificationResult = { tier: "light", reason: "hook unit", downgraded: false, taskMetadata: undefined }; return applyBudgetPressure(result, budgetPct); } // Start with the default tier for this unit type let tier = UNIT_TYPE_TIERS[unitType] ?? "standard"; let reason = `unit type: ${unitType}`; + let taskMeta: TaskMetadata | undefined; // For execute-task, analyze task metadata for complexity signals if (unitType === "execute-task") { - const taskAnalysis = analyzeTaskComplexity(unitId, basePath, metadata); + // Extract metadata once and reuse throughout to avoid double-extraction + taskMeta = metadata ?? extractTaskMetadata(unitId, basePath); + const taskAnalysis = analyzeTaskComplexity(unitId, basePath, taskMeta); tier = taskAnalysis.tier; reason = taskAnalysis.reason; } @@ -94,14 +100,15 @@ export function classifyUnitComplexity( } // Adaptive learning: check if history suggests bumping the tier - const tags = metadata?.tags ?? extractTaskMetadata(unitId, basePath).tags; + // Use already-extracted taskMeta.tags if available to avoid double-extraction + const tags = taskMeta?.tags ?? metadata?.tags; const adaptiveAdjustment = getAdaptiveTierAdjustment(unitType, tier, tags); if (adaptiveAdjustment && tierOrdinal(adaptiveAdjustment) > tierOrdinal(tier)) { reason = `${reason} (adaptive: high failure rate at ${tier})`; tier = adaptiveAdjustment; } - const result: ClassificationResult = { tier, reason, downgraded: false }; + const result: ClassificationResult = { tier, reason, downgraded: false, taskMetadata: taskMeta }; return applyBudgetPressure(result, budgetPct); } @@ -185,8 +192,8 @@ function analyzePlanComplexity( // Check if this is a milestone-level plan (more complex) vs single slice const { milestone: mid, slice: sid } = parseUnitId(unitId); if (!sid) { - // Milestone-level planning is always at least standard - return { tier: "standard", reason: "milestone-level planning" }; + // Milestone-level planning is always heavy — requires full context and best model + return { tier: "heavy", reason: "milestone-level planning" }; } // For slice planning, try to read the context/research to gauge complexity @@ -210,7 +217,7 @@ function analyzePlanComplexity( /** * Extract task metadata from the task plan file on disk. */ -function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata { +export function extractTaskMetadata(unitId: string, basePath: string): TaskMetadata { const meta: TaskMetadata = {}; const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId); if (!mid || !sid || !tid) return meta; diff --git a/src/resources/extensions/gsd/config-overlay.ts b/src/resources/extensions/gsd/config-overlay.ts new file mode 100644 index 000000000..1b9cf2852 --- /dev/null +++ b/src/resources/extensions/gsd/config-overlay.ts @@ -0,0 +1,331 @@ +/** + * GSD Configuration Overlay + * + * Read-only TUI overlay showing the effective GSD configuration: + * token profile, model assignments, dynamic routing, git settings, + * budget, workflow toggles, and preference file sources. + * Opened via `/gsd show-config` or `/gsd config`. + */ + +import type { Theme } from "@gsd/pi-coding-agent"; +import { matchesKey, Key, truncateToWidth } from "@gsd/pi-tui"; + +import { + loadEffectiveGSDPreferences, + loadGlobalGSDPreferences, + loadProjectGSDPreferences, + getGlobalGSDPreferencesPath, + getProjectGSDPreferencesPath, + resolveDynamicRoutingConfig, + resolveEffectiveProfile, + resolveModelWithFallbacksForUnit, + resolveAutoSupervisorConfig, +} from "./preferences.js"; + +// ─── Data Collection ────────────────────────────────────────────────────── + +interface ConfigSection { + title: string; + rows: Array<{ label: string; value: string; accent?: boolean }>; +} + +function collectConfigSections(): ConfigSection[] { + const sections: ConfigSection[] = []; + + const globalPrefs = loadGlobalGSDPreferences(); + const projectPrefs = loadProjectGSDPreferences(); + const effective = loadEffectiveGSDPreferences(); + const prefs = effective?.preferences; + + // ─── Sources ───────────────────────────────────────────────────────── + sections.push({ + title: "Sources", + rows: [ + { label: "Global", value: globalPrefs ? globalPrefs.path : `(none) ${getGlobalGSDPreferencesPath()}` }, + { label: "Project", value: projectPrefs ? projectPrefs.path : `(none) ${getProjectGSDPreferencesPath()}` }, + ], + }); + + // ─── Profile ───────────────────────────────────────────────────────── + const profile = resolveEffectiveProfile(); + const profileRows: ConfigSection["rows"] = [ + { label: "Token profile", value: `${profile}${!prefs?.token_profile ? " (default)" : ""}`, accent: true }, + ]; + if (prefs?.mode) profileRows.push({ label: "Workflow mode", value: prefs.mode }); + sections.push({ title: "Profile", rows: profileRows }); + + // ─── Models ────────────────────────────────────────────────────────── + const unitTypes: Array<[string, string]> = [ + ["research", "research-milestone"], + ["planning", "plan-milestone"], + ["discuss", "discuss-milestone"], + ["execution", "execute-task"], + ["completion", "complete-slice"], + ["validation", "run-uat"], + ]; + + const modelRows: ConfigSection["rows"] = []; + for (const [label, unitType] of unitTypes) { + const resolved = resolveModelWithFallbacksForUnit(unitType); + if (resolved) { + let val = resolved.primary; + if (resolved.fallbacks.length > 0) { + val += ` \u2192 ${resolved.fallbacks.join(" \u2192 ")}`; + } + modelRows.push({ label, value: val }); + } else { + modelRows.push({ label, value: "(inherit)" }); + } + } + + // subagent is a direct config key + const models = prefs?.models as Record | undefined; + const subVal = models?.subagent; + if (subVal) { + const model = typeof subVal === "string" ? subVal : (subVal as { model?: string })?.model ?? "?"; + modelRows.push({ label: "subagent", value: model }); + } else { + modelRows.push({ label: "subagent", value: "(inherit)" }); + } + + sections.push({ title: "Models", rows: modelRows }); + + // ─── Dynamic Routing ───────────────────────────────────────────────── + const routing = resolveDynamicRoutingConfig(); + const routingRows: ConfigSection["rows"] = [ + { label: "Enabled", value: routing.enabled ? "yes" : "no", accent: routing.enabled }, + ]; + if (routing.enabled) { + routingRows.push({ label: "Escalate on fail", value: routing.escalate_on_failure !== false ? "yes" : "no" }); + routingRows.push({ label: "Budget pressure", value: routing.budget_pressure !== false ? "yes" : "no" }); + routingRows.push({ label: "Cross-provider", value: routing.cross_provider !== false ? "yes" : "no" }); + if (routing.tier_models) { + const tm = routing.tier_models; + if (tm.light) routingRows.push({ label: "[L] light", value: tm.light }); + if (tm.standard) routingRows.push({ label: "[S] standard", value: tm.standard }); + if (tm.heavy) routingRows.push({ label: "[H] heavy", value: tm.heavy }); + } + } + sections.push({ title: "Dynamic Routing", rows: routingRows }); + + // ─── Git ───────────────────────────────────────────────────────────── + if (prefs?.git) { + const g = prefs.git; + const gitRows: ConfigSection["rows"] = []; + if (g.isolation !== undefined) gitRows.push({ label: "Isolation", value: String(g.isolation) }); + if (g.auto_push !== undefined) gitRows.push({ label: "Auto push", value: String(g.auto_push) }); + if (g.push_branches !== undefined) gitRows.push({ label: "Push branches", value: String(g.push_branches) }); + if (g.merge_strategy) gitRows.push({ label: "Merge strategy", value: g.merge_strategy }); + if (g.main_branch) gitRows.push({ label: "Main branch", value: g.main_branch }); + if (g.remote) gitRows.push({ label: "Remote", value: g.remote }); + if (gitRows.length > 0) sections.push({ title: "Git", rows: gitRows }); + } + + // ─── Budget ────────────────────────────────────────────────────────── + if (prefs?.budget_ceiling !== undefined || prefs?.budget_enforcement) { + const budgetRows: ConfigSection["rows"] = []; + if (prefs.budget_ceiling !== undefined) budgetRows.push({ label: "Ceiling", value: `$${prefs.budget_ceiling}` }); + if (prefs.budget_enforcement) budgetRows.push({ label: "Enforcement", value: String(prefs.budget_enforcement) }); + sections.push({ title: "Budget", rows: budgetRows }); + } + + // ─── Auto Supervisor ───────────────────────────────────────────────── + if (prefs?.auto_supervisor) { + const sup = resolveAutoSupervisorConfig(); + const supRows: ConfigSection["rows"] = []; + if (sup.model) supRows.push({ label: "Model", value: sup.model }); + supRows.push({ label: "Soft timeout", value: `${sup.soft_timeout_minutes}m` }); + supRows.push({ label: "Idle timeout", value: `${sup.idle_timeout_minutes}m` }); + supRows.push({ label: "Hard timeout", value: `${sup.hard_timeout_minutes}m` }); + sections.push({ title: "Auto Supervisor", rows: supRows }); + } + + // ─── Toggles ───────────────────────────────────────────────────────── + const toggleRows: ConfigSection["rows"] = []; + if (prefs?.phases) { + const p = prefs.phases; + if (p.skip_research) toggleRows.push({ label: "skip_research", value: "on" }); + if (p.skip_reassess) toggleRows.push({ label: "skip_reassess", value: "on" }); + if (p.skip_slice_research) toggleRows.push({ label: "skip_slice_research", value: "on" }); + if (p.skip_milestone_validation) toggleRows.push({ label: "skip_milestone_validation", value: "on" }); + if (p.require_slice_discussion) toggleRows.push({ label: "require_slice_discussion", value: "on" }); + } + if (prefs?.uat_dispatch) toggleRows.push({ label: "uat_dispatch", value: "on" }); + if (prefs?.auto_visualize) toggleRows.push({ label: "auto_visualize", value: "on" }); + if (prefs?.auto_report === false) toggleRows.push({ label: "auto_report", value: "off" }); + if (prefs?.show_token_cost) toggleRows.push({ label: "show_token_cost", value: "on" }); + if (prefs?.forensics_dedup) toggleRows.push({ label: "forensics_dedup", value: "on" }); + if (prefs?.unique_milestone_ids) toggleRows.push({ label: "unique_milestone_ids", value: "on" }); + if (prefs?.service_tier) toggleRows.push({ label: "service_tier", value: prefs.service_tier }); + if (prefs?.search_provider && prefs.search_provider !== "auto") toggleRows.push({ label: "search_provider", value: prefs.search_provider }); + if (prefs?.context_selection) toggleRows.push({ label: "context_selection", value: prefs.context_selection }); + if (prefs?.widget_mode && prefs.widget_mode !== "full") toggleRows.push({ label: "widget_mode", value: prefs.widget_mode }); + if (prefs?.experimental?.rtk) toggleRows.push({ label: "experimental.rtk", value: "on" }); + if (toggleRows.length > 0) sections.push({ title: "Toggles", rows: toggleRows }); + + // ─── Parallel ──────────────────────────────────────────────────────── + if (prefs?.parallel) { + const pc = prefs.parallel; + const parallelRows: ConfigSection["rows"] = []; + if (pc.max_workers !== undefined) parallelRows.push({ label: "Max workers", value: String(pc.max_workers) }); + if (pc.merge_strategy) parallelRows.push({ label: "Merge strategy", value: pc.merge_strategy }); + if (pc.auto_merge) parallelRows.push({ label: "Auto merge", value: pc.auto_merge }); + if (parallelRows.length > 0) sections.push({ title: "Parallel", rows: parallelRows }); + } + + // ─── Hooks ─────────────────────────────────────────────────────────── + const postHooks = prefs?.post_unit_hooks?.filter(h => h.enabled !== false) ?? []; + const preHooks = prefs?.pre_dispatch_hooks?.filter(h => h.enabled !== false) ?? []; + if (postHooks.length > 0 || preHooks.length > 0) { + const hookRows: ConfigSection["rows"] = []; + if (preHooks.length > 0) hookRows.push({ label: "Pre-dispatch", value: `${preHooks.length} active` }); + if (postHooks.length > 0) hookRows.push({ label: "Post-unit", value: `${postHooks.length} active` }); + sections.push({ title: "Hooks", rows: hookRows }); + } + + // ─── Warnings ──────────────────────────────────────────────────────── + const warnings = [ + ...(globalPrefs?.warnings ?? []), + ...(projectPrefs?.warnings ?? []), + ]; + if (warnings.length > 0) { + sections.push({ + title: "Warnings", + rows: warnings.map(w => ({ label: "\u26a0", value: w })), + }); + } + + return sections; +} + +// ─── Plain Text Formatter (headless/RPC fallback) ───────────────────────── + +export function formatConfigText(): string { + const sections = collectConfigSections(); + const lines: string[] = ["GSD Configuration\n"]; + + let maxLabel = 0; + for (const section of sections) { + for (const row of section.rows) { + if (row.label.length > maxLabel) maxLabel = row.label.length; + } + } + const pad = Math.min(maxLabel + 2, 24); + + for (const section of sections) { + lines.push(""); + lines.push(section.title.toUpperCase()); + for (const row of section.rows) { + lines.push(` ${row.label.padEnd(pad)}${row.value}`); + } + } + + return lines.join("\n"); +} + +// ─── Overlay Class ──────────────────────────────────────────────────────── + +export class GSDConfigOverlay { + private tui: { requestRender: () => void }; + private theme: Theme; + private onClose: () => void; + private sections: ConfigSection[]; + private cachedLines?: string[]; + private scrollOffset = 0; + private disposed = false; + + constructor( + tui: { requestRender: () => void }, + theme: Theme, + onClose: () => void, + ) { + this.tui = tui; + this.theme = theme; + this.onClose = onClose; + this.sections = collectConfigSections(); + } + + invalidate(): void { + this.cachedLines = undefined; + } + + dispose(): void { + this.disposed = true; + } + + handleInput(data: string): void { + if (matchesKey(data, Key.escape) || data === "q") { + this.dispose(); + this.onClose(); + return; + } + if (matchesKey(data, Key.down) || data === "j") { + this.scrollOffset++; + this.cachedLines = undefined; + this.tui.requestRender(); + return; + } + if (matchesKey(data, Key.up) || data === "k") { + this.scrollOffset = Math.max(0, this.scrollOffset - 1); + this.cachedLines = undefined; + this.tui.requestRender(); + return; + } + if (matchesKey(data, Key.pageDown)) { + this.scrollOffset += 10; + this.cachedLines = undefined; + this.tui.requestRender(); + return; + } + if (matchesKey(data, Key.pageUp)) { + this.scrollOffset = Math.max(0, this.scrollOffset - 10); + this.cachedLines = undefined; + this.tui.requestRender(); + return; + } + } + + render(width: number): string[] { + if (this.cachedLines) return this.cachedLines; + + const t = this.theme; + const w = Math.max(width, 50); + const allLines: string[] = []; + + // Header + allLines.push(t.bold(t.fg("accent", " GSD Configuration "))); + allLines.push(t.fg("muted", "\u2500".repeat(w))); + + // Find max label width for alignment + let maxLabel = 0; + for (const section of this.sections) { + for (const row of section.rows) { + if (row.label.length > maxLabel) maxLabel = row.label.length; + } + } + const labelPad = Math.min(maxLabel + 2, 24); + + for (const section of this.sections) { + allLines.push(""); + allLines.push(t.bold(t.fg("accent", ` ${section.title}`))); + + for (const row of section.rows) { + const label = t.fg("muted", ` ${row.label.padEnd(labelPad)}`); + const value = row.accent ? t.bold(row.value) : row.value; + allLines.push(truncateToWidth(`${label}${value}`, w)); + } + } + + allLines.push(""); + allLines.push(t.fg("muted", ` ${"\u2500".repeat(w - 4)}`)); + allLines.push(t.fg("muted", " esc/q close \u2502 \u2191\u2193/jk scroll \u2502 /gsd prefs to edit")); + + // Apply scroll + const maxScroll = Math.max(0, allLines.length - 20); + this.scrollOffset = Math.min(this.scrollOffset, maxScroll); + const visible = allLines.slice(this.scrollOffset); + + this.cachedLines = visible; + return visible; + } +} diff --git a/src/resources/extensions/gsd/constants.ts b/src/resources/extensions/gsd/constants.ts index 636f2d808..15812dc93 100644 --- a/src/resources/extensions/gsd/constants.ts +++ b/src/resources/extensions/gsd/constants.ts @@ -19,3 +19,47 @@ export const DIR_CACHE_MAX = 200; /** Max parse-cache entries before eviction. */ export const CACHE_MAX = 50; + +// ─── Tool Scoping ───────────────────────────────────────────────────────────── + +/** + * GSD tools allowed during discuss flows (#2949). + * + * xAI/Grok (and potentially other providers with grammar-based constrained + * decoding) return "Grammar is too complex" (HTTP 400) when the combined + * tool schemas exceed their internal grammar limit. The full GSD tool set + * registers ~33 tools with deeply nested schemas; discuss flows only need + * a small subset. + * + * By scoping tools to this allowlist during discuss dispatches, the grammar + * sent to the provider stays well under provider limits. + * + * Included tools and why: + * - gsd_summary_save: writes CONTEXT.md artifacts (all discuss prompts) + * - gsd_save_summary: alias for above + * - gsd_decision_save: records decisions (discuss.md output phase) + * - gsd_save_decision: alias for above + * - gsd_plan_milestone: writes roadmap (discuss.md single/multi milestone) + * - gsd_milestone_plan: alias for above + * - gsd_milestone_generate_id: generates milestone IDs (discuss.md multi-milestone) + * - gsd_generate_milestone_id: alias for above + * - gsd_requirement_update: updates requirements during discuss + * - gsd_update_requirement: alias for above + */ +export const DISCUSS_TOOLS_ALLOWLIST: readonly string[] = [ + // Context / summary writing + "gsd_summary_save", + "gsd_save_summary", + // Decision recording + "gsd_decision_save", + "gsd_save_decision", + // Milestone planning (needed for discuss.md output phase) + "gsd_plan_milestone", + "gsd_milestone_plan", + // Milestone ID generation (multi-milestone flow) + "gsd_milestone_generate_id", + "gsd_generate_milestone_id", + // Requirement updates + "gsd_requirement_update", + "gsd_update_requirement", +]; diff --git a/src/resources/extensions/gsd/context-masker.ts b/src/resources/extensions/gsd/context-masker.ts new file mode 100644 index 000000000..824c3a91e --- /dev/null +++ b/src/resources/extensions/gsd/context-masker.ts @@ -0,0 +1,74 @@ +/** + * Observation masking for GSD auto-mode sessions. + * + * Replaces tool result content older than N turns with a placeholder. + * Reduces context bloat between compactions with zero LLM overhead. + * Preserves message ordering, roles, and all assistant/user messages. + * + * Operates on the pi-ai Message[] format (post-convertToLlm, pre-provider): + * - toolResult messages: { role: "toolResult", content: TextContent[] } + * - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] } + * and start with "Ran `" from bashExecutionToText. + */ + +interface MaskableMessage { + role: string; + content: unknown; + type?: string; + [key: string]: unknown; +} + +const MASK_PLACEHOLDER = "[result masked — within summarized history]"; +const MASK_CONTENT_BLOCK = [{ type: "text" as const, text: MASK_PLACEHOLDER }]; + +function findTurnBoundary(messages: MaskableMessage[], keepRecentTurns: number): number { + let turnsSeen = 0; + for (let i = messages.length - 1; i >= 0; i--) { + const m = messages[i]; + // In the LLM payload, genuine user turns have role "user". + // Tool results have role "toolResult" and are excluded by this check. + if (m.role === "user") { + // Skip bash-result user messages (converted from bashExecution) — these aren't real user turns + if (isBashResultUserMessage(m)) continue; + turnsSeen++; + if (turnsSeen >= keepRecentTurns) return i; + } + } + return 0; +} + +/** + * Detect user messages that originated from bashExecution. + * After convertToLlm, these are {role: "user", content: [{type:"text", text:"Ran `cmd`\n..."}]}. + * The bashExecutionToText format always starts with "Ran `". + */ +function isBashResultUserMessage(m: MaskableMessage): boolean { + if (m.role !== "user" || !Array.isArray(m.content)) return false; + const first = m.content[0]; + return first && typeof first === "object" && "text" in first && + typeof first.text === "string" && first.text.startsWith("Ran `"); +} + +function isMaskableMessage(m: MaskableMessage): boolean { + // Tool result messages (role: "toolResult" in pi-ai format) + if (m.role === "toolResult") return true; + // Bash-result user messages (converted from bashExecution by convertToLlm) + if (isBashResultUserMessage(m)) return true; + return false; +} + +export function createObservationMask(keepRecentTurns: number = 8) { + return (messages: MaskableMessage[]): MaskableMessage[] => { + const boundary = findTurnBoundary(messages, keepRecentTurns); + if (boundary === 0) return messages; + + return messages.map((m, i) => { + if (i >= boundary) return m; + if (isMaskableMessage(m)) { + // Content may be string or array of content blocks — always replace with array + return { ...m, content: MASK_CONTENT_BLOCK }; + } + return m; + }); + }; +} diff --git a/src/resources/extensions/gsd/context-store.ts b/src/resources/extensions/gsd/context-store.ts index b23f1e855..df938555a 100644 --- a/src/resources/extensions/gsd/context-store.ts +++ b/src/resources/extensions/gsd/context-store.ts @@ -15,6 +15,7 @@ export interface DecisionQueryOpts { } export interface RequirementQueryOpts { + milestoneId?: string; sliceId?: string; status?: string; } @@ -67,7 +68,8 @@ export function queryDecisions(opts?: DecisionQueryOpts): Decision[] { /** * Query active (non-superseded) requirements with optional filters. - * - sliceId: filters where primary_owner LIKE '%sliceId%' OR supporting_slices LIKE '%sliceId%' + * - milestoneId: combined with sliceId for precise filtering (e.g. %M005/S01%) + * - sliceId: filters where primary_owner LIKE '%pattern%' OR supporting_slices LIKE '%pattern%' * - status: filters where status = :status (exact match) * * Returns [] if DB is not available. Never throws. @@ -81,9 +83,19 @@ export function queryRequirements(opts?: RequirementQueryOpts): Requirement[] { const clauses: string[] = ['superseded_by IS NULL']; const params: Record = {}; - if (opts?.sliceId) { + // Combined milestone+slice filtering for precise scoping + if (opts?.milestoneId && opts?.sliceId) { + // Use combined pattern like %M005/S01% to avoid cross-milestone contamination + clauses.push('(primary_owner LIKE :combined_pattern OR supporting_slices LIKE :combined_pattern)'); + params[':combined_pattern'] = `%${opts.milestoneId}/${opts.sliceId}%`; + } else if (opts?.sliceId) { + // Slice-only filtering (legacy behavior) clauses.push('(primary_owner LIKE :slice_pattern OR supporting_slices LIKE :slice_pattern)'); params[':slice_pattern'] = `%${opts.sliceId}%`; + } else if (opts?.milestoneId) { + // Milestone-only filtering + clauses.push('(primary_owner LIKE :milestone_pattern OR supporting_slices LIKE :milestone_pattern)'); + params[':milestone_pattern'] = `%${opts.milestoneId}%`; } if (opts?.status) { @@ -194,3 +206,156 @@ export function queryArtifact(path: string): string | null { export function queryProject(): string | null { return queryArtifact('PROJECT.md'); } + +// ─── Knowledge Query ─────────────────────────────────────────────────────── + +/** + * Filter KNOWLEDGE.md sections by keyword matching. + * Uses H2 sections, matches keywords case-insensitively against: + * 1. Section header text + * 2. First paragraph of section content (up to first blank line or next heading) + * + * Per D020, returns empty string (not null) when no matches found. + * This signals "no relevant knowledge" vs "file not found". + * + * @param content - Full KNOWLEDGE.md content + * @param keywords - Keywords to match (case-insensitive) + * @returns Concatenated matching sections with H2 headers, or empty string + */ +export async function queryKnowledge(content: string, keywords: string[]): Promise { + if (!content || keywords.length === 0) return ''; + + // Lazy import to avoid circular dependency + const { extractAllSections } = await import('./files.js'); + + const sections = extractAllSections(content, 2); + if (sections.size === 0) return ''; + + // Normalize keywords for case-insensitive matching + const normalizedKeywords = keywords.map(k => k.toLowerCase()); + + const matchingSections: string[] = []; + + for (const [header, body] of sections) { + // Extract first paragraph: everything up to first blank line or next heading + const firstParagraph = body.split(/\n\s*\n|\n#/)[0] || ''; + + // Check if any keyword matches header or first paragraph + const headerLower = header.toLowerCase(); + const paragraphLower = firstParagraph.toLowerCase(); + + const matches = normalizedKeywords.some(kw => + headerLower.includes(kw) || paragraphLower.includes(kw) + ); + + if (matches) { + matchingSections.push(`## ${header}\n\n${body}`); + } + } + + return matchingSections.join('\n\n'); +} + +// ─── Roadmap Excerpt Formatter ───────────────────────────────────────────── + +/** + * Format a minimal roadmap excerpt for prompt injection. + * Parses the slice table from roadmap content, extracts: + * 1. Header row + separator + * 2. Predecessor row (if sliceId depends on one via the Depends column) + * 3. Target slice row + * 4. Reference directive pointing to full roadmap path + * + * Per D021, this minimizes injected content while preserving dependency awareness. + * Returns empty string if sliceId is not found in the table. + * Never throws. + * + * @param roadmapContent - Full content of the M###-ROADMAP.md file + * @param sliceId - Target slice ID (e.g. 'S02') + * @param roadmapPath - Optional path for reference directive (defaults to generic) + */ +export function formatRoadmapExcerpt( + roadmapContent: string, + sliceId: string, + roadmapPath = 'ROADMAP.md', +): string { + if (!roadmapContent || !sliceId) return ''; + + const lines = roadmapContent.split('\n'); + + // Find the slice table header: | ID | Slice | ... (case insensitive) + let headerIndex = -1; + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (line && /^\s*\|\s*ID\s*\|\s*Slice\s*\|/i.test(line)) { + headerIndex = i; + break; + } + } + + if (headerIndex === -1) return ''; + + // The separator should be the next line (|---|---|...) + const separatorIndex = headerIndex + 1; + if (separatorIndex >= lines.length) return ''; + + const headerLine = lines[headerIndex]; + const separatorLine = lines[separatorIndex]; + + // Validate separator line looks like |---|---|... (may include : for alignment) + if (!separatorLine || !/^\s*\|[\s:\-|]+\|/.test(separatorLine)) return ''; + + // Parse table rows after separator + interface SliceRow { + line: string; + id: string; + depends: string; + } + + const sliceRows: SliceRow[] = []; + for (let i = separatorIndex + 1; i < lines.length; i++) { + const line = lines[i]; + if (!line || !line.trim().startsWith('|')) break; // End of table + + // Parse row: | ID | Slice | Risk | Depends | Done | After this | + const cells = line.split('|').map(c => c.trim()); + // cells[0] is empty (before first |), cells[1] is ID, etc. + if (cells.length < 5) continue; + + const id = cells[1] || ''; + const depends = cells[4] || ''; // Depends column (0-indexed: empty, ID, Slice, Risk, Depends, ...) + + sliceRows.push({ line, id, depends }); + } + + // Find target slice row + const targetRow = sliceRows.find(r => r.id === sliceId); + if (!targetRow) return ''; + + // Find predecessor if target depends on one + // Depends column may contain: '—', 'S01', 'S01, S02', etc. + let predecessorRow: SliceRow | undefined; + const dependsRaw = targetRow.depends; + if (dependsRaw && dependsRaw !== '—' && dependsRaw !== '-') { + // Extract first dependency (e.g. 'S01' from 'S01, S02') + const depMatch = dependsRaw.match(/S\d+/); + if (depMatch) { + predecessorRow = sliceRows.find(r => r.id === depMatch[0]); + } + } + + // Build excerpt + const excerptLines: string[] = [headerLine!, separatorLine!]; + + if (predecessorRow) { + excerptLines.push(predecessorRow.line); + } + + excerptLines.push(targetRow.line); + + // Add reference directive + excerptLines.push(''); + excerptLines.push(`> See full roadmap: ${roadmapPath}`); + + return excerptLines.join('\n'); +} diff --git a/src/resources/extensions/gsd/custom-verification.ts b/src/resources/extensions/gsd/custom-verification.ts index 4d60c507b..77d76d30e 100644 --- a/src/resources/extensions/gsd/custom-verification.ts +++ b/src/resources/extensions/gsd/custom-verification.ts @@ -17,6 +17,7 @@ * - The frozen DEFINITION.yaml on disk is the single source of truth for step policies. */ +import { logWarning } from "./workflow-logger.js"; import { readFileSync, existsSync, statSync } from "node:fs"; import { join, resolve, sep } from "node:path"; import { spawnSync } from "node:child_process"; @@ -130,8 +131,8 @@ function handleContentHeuristic( if (!new RegExp(verify.pattern).test(content)) { return "pause"; } - } catch { - // Invalid regex at runtime — treat as verification failure + } catch (e) { + logWarning("engine", `content-heuristic regex failed: ${(e as Error).message}`); return "pause"; } } diff --git a/src/resources/extensions/gsd/custom-workflow-engine.ts b/src/resources/extensions/gsd/custom-workflow-engine.ts index 8c2a168ea..0b1266326 100644 --- a/src/resources/extensions/gsd/custom-workflow-engine.ts +++ b/src/resources/extensions/gsd/custom-workflow-engine.ts @@ -34,6 +34,7 @@ import { import { injectContext } from "./context-injector.js"; import type { WorkflowDefinition, StepDefinition } from "./definition-loader.js"; import { parseUnitId } from "./unit-id.js"; +import { withFileLock } from "./file-lock.js"; /** Read and parse the frozen DEFINITION.yaml from a run directory. */ export function readFrozenDefinition(runDir: string): WorkflowDefinition { @@ -179,22 +180,28 @@ export class CustomWorkflowEngine implements WorkflowEngine { state: EngineState, completedStep: CompletedStep, ): Promise { - const graph = state.raw as WorkflowGraph; + const graphPath = join(this.runDir, "GRAPH.yaml"); - // Extract stepId from "/" - const { milestone, slice, task } = parseUnitId(completedStep.unitId); - const stepId = task ?? slice ?? milestone; + return await withFileLock(graphPath, () => { + // Re-read the graph from disk so we do not overwrite concurrent + // workflow edits with a stale in-memory snapshot from deriveState(). + const graph = readGraph(this.runDir); - const updatedGraph = markStepComplete(graph, stepId); - writeGraph(this.runDir, updatedGraph); + // Extract stepId from "/" + const { milestone, slice, task } = parseUnitId(completedStep.unitId); + const stepId = task ?? slice ?? milestone; - const allDone = updatedGraph.steps.every( - (s) => s.status === "complete" || s.status === "expanded", - ); + const updatedGraph = markStepComplete(graph, stepId); + writeGraph(this.runDir, updatedGraph); - return { - outcome: allDone ? "milestone-complete" : "continue", - }; + const allDone = updatedGraph.steps.every( + (s) => s.status === "complete" || s.status === "expanded", + ); + + return { + outcome: allDone ? "milestone-complete" : "continue", + }; + }); } /** diff --git a/src/resources/extensions/gsd/db-writer.ts b/src/resources/extensions/gsd/db-writer.ts index 489b0d915..14bcb75b5 100644 --- a/src/resources/extensions/gsd/db-writer.ts +++ b/src/resources/extensions/gsd/db-writer.ts @@ -227,6 +227,143 @@ export async function nextDecisionId(): Promise { } } +// ─── Next Requirement ID ───────────────────────────────────────────────── + +/** + * Compute the next requirement ID from the current DB state. + * Queries MAX(CAST(SUBSTR(id, 2) AS INTEGER)) from requirements table. + * Returns R001 if no requirements exist. Zero-pads to 3 digits. + */ +export async function nextRequirementId(): Promise { + try { + const db = await import('./gsd-db.js'); + const adapter = db._getAdapter(); + if (!adapter) return 'R001'; + + const row = adapter + .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements') + .get(); + + const maxNum = row ? (row['max_num'] as number | null) : null; + if (maxNum == null || isNaN(maxNum)) return 'R001'; + + const next = maxNum + 1; + return `R${String(next).padStart(3, '0')}`; + } catch (err) { + logError('manifest', 'nextRequirementId failed', { fn: 'nextRequirementId', error: String((err as Error).message) }); + return 'R001'; + } +} + +// ─── Save Requirement to DB + Regenerate Markdown ──────────────────────── + +export interface SaveRequirementFields { + class: string; + status?: string; + description: string; + why: string; + source: string; + primary_owner?: string; + supporting_slices?: string; + validation?: string; + notes?: string; +} + +/** + * Save a new requirement to DB and regenerate REQUIREMENTS.md. + * Auto-assigns the next ID via nextRequirementId(). + * + * The ID computation and insert are wrapped in a single transaction + * to prevent parallel race conditions (same pattern as saveDecisionToDb). + * + * Returns the assigned ID. + */ +export async function saveRequirementToDb( + fields: SaveRequirementFields, + basePath: string, +): Promise<{ id: string }> { + try { + const db = await import('./gsd-db.js'); + + // Atomic ID assignment + insert inside a transaction. + const id = db.transaction(() => { + const adapter = db._getAdapter(); + if (!adapter) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); + + const row = adapter + .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements') + .get(); + const maxNum = row ? (row['max_num'] as number | null) : null; + const nextId = (maxNum == null || isNaN(maxNum)) + ? 'R001' + : `R${String(maxNum + 1).padStart(3, '0')}`; + + const requirement: Requirement = { + id: nextId, + class: fields.class, + status: fields.status ?? 'active', + description: fields.description, + why: fields.why, + source: fields.source, + primary_owner: fields.primary_owner ?? '', + supporting_slices: fields.supporting_slices ?? '', + validation: fields.validation ?? '', + notes: fields.notes ?? '', + full_content: '', + superseded_by: null, + }; + + db.upsertRequirement(requirement); + return nextId; + }); + + // Fetch all requirements for full file regeneration + const adapter = db._getAdapter(); + let allRequirements: Requirement[] = []; + if (adapter) { + const rows = adapter.prepare('SELECT * FROM requirements ORDER BY id').all(); + allRequirements = rows.map(row => ({ + id: row['id'] as string, + class: row['class'] as string, + status: row['status'] as string, + description: row['description'] as string, + why: row['why'] as string, + source: row['source'] as string, + primary_owner: row['primary_owner'] as string, + supporting_slices: row['supporting_slices'] as string, + validation: row['validation'] as string, + notes: row['notes'] as string, + full_content: row['full_content'] as string, + superseded_by: (row['superseded_by'] as string) ?? null, + })); + } + + const nonSuperseded = allRequirements.filter(r => r.superseded_by == null); + const md = generateRequirementsMd(nonSuperseded); + const filePath = resolveGsdRootFile(basePath, 'REQUIREMENTS'); + try { + await saveFile(filePath, md); + } catch (diskErr) { + logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String((diskErr as Error).message) }); + try { + const rollbackAdapter = db._getAdapter(); + rollbackAdapter?.prepare('DELETE FROM requirements WHERE id = :id').run({ ':id': id }); + } catch (rollbackErr) { + logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String((rollbackErr as Error).message) }); + } + throw diskErr; + } + invalidateStateCache(); + clearPathCache(); + clearParseCache(); + + return { id }; + } catch (err) { + logError('manifest', 'saveRequirementToDb failed', { fn: 'saveRequirementToDb', error: String((err as Error).message) }); + throw err; + } +} + // ─── Save Decision to DB + Regenerate Markdown ──────────────────────────── export interface SaveDecisionFields { @@ -242,6 +379,11 @@ export interface SaveDecisionFields { /** * Save a new decision to DB and regenerate DECISIONS.md. * Auto-assigns the next ID via nextDecisionId(). + * + * The ID computation (SELECT MAX) and insert are wrapped in a single + * transaction to prevent parallel tool calls from computing the same ID + * and silently overwriting each other (#3326, #3339, #3459). + * * Returns the assigned ID. */ export async function saveDecisionToDb( @@ -251,18 +393,33 @@ export async function saveDecisionToDb( try { const db = await import('./gsd-db.js'); - const id = await nextDecisionId(); + // Atomic ID assignment + insert inside a transaction to prevent + // parallel calls from racing on the same MAX(id) value. + const id = db.transaction(() => { + const adapter = db._getAdapter(); + if (!adapter) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); - db.upsertDecision({ - id, - when_context: fields.when_context ?? '', - scope: fields.scope, - decision: fields.decision, - choice: fields.choice, - rationale: fields.rationale, - revisable: fields.revisable ?? 'Yes', - made_by: fields.made_by ?? 'agent', - superseded_by: null, + const row = adapter + .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM decisions') + .get(); + const maxNum = row ? (row['max_num'] as number | null) : null; + const nextId = (maxNum == null || isNaN(maxNum)) + ? 'D001' + : `D${String(maxNum + 1).padStart(3, '0')}`; + + db.upsertDecision({ + id: nextId, + when_context: fields.when_context ?? '', + scope: fields.scope, + decision: fields.decision, + choice: fields.choice, + rationale: fields.rationale, + revisable: fields.revisable ?? 'Yes', + made_by: fields.made_by ?? 'agent', + superseded_by: null, + }); + + return nextId; }); // Fetch all decisions (including superseded for the full register) @@ -313,9 +470,30 @@ export async function saveDecisionToDb( await saveFile(filePath, md); } catch (diskErr) { logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) }); - adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id }); + try { + adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id }); + } catch (rollbackErr) { + logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String((rollbackErr as Error).message) }); + } throw diskErr; } + // #2661: When a decision defers a slice, update the slice status in the DB + // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are + // in split-brain: the decision says "deferred" but the state still says + // "active", causing auto-mode to keep dispatching the deferred work. + try { + const sliceRef = extractDeferredSliceRef(fields); + if (sliceRef) { + db.updateSliceStatus(sliceRef.milestoneId, sliceRef.sliceId, 'deferred'); + } + } catch (deferErr) { + // Non-fatal — log but don't fail the decision save + logError('manifest', 'failed to update deferred slice status', { + fn: 'saveDecisionToDb', + error: String((deferErr as Error).message), + }); + } + // Invalidate file-read caches so deriveState() sees the updated markdown. // Do NOT clear the artifacts table — we just wrote to it intentionally. invalidateStateCache(); @@ -329,6 +507,39 @@ export async function saveDecisionToDb( } } +/** + * Extract a milestone/slice reference from a deferral decision. + * + * Detects deferrals by checking: + * - scope contains "defer" (e.g., "deferral", "defer") + * - choice or decision contains "defer" + an M###/S## pattern + * + * Returns { milestoneId, sliceId } if found, null otherwise. + */ +export function extractDeferredSliceRef( + fields: Pick, +): { milestoneId: string; sliceId: string } | null { + const isDeferral = + /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.scope) || + /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.choice) || + /\bdefer(?:ral|red|ring|s)?\b/i.test(fields.decision); + + if (!isDeferral) return null; + + // Look for M###/S## pattern in choice first, then decision + const slicePattern = /\b(M\d{3,4})\/(S\d{2,3})\b/; + const choiceMatch = fields.choice.match(slicePattern); + if (choiceMatch) { + return { milestoneId: choiceMatch[1], sliceId: choiceMatch[2] }; + } + const decisionMatch = fields.decision.match(slicePattern); + if (decisionMatch) { + return { milestoneId: decisionMatch[1], sliceId: decisionMatch[2] }; + } + + return null; +} + // ─── Update Requirement in DB + Regenerate Markdown ─────────────────────── /** @@ -343,16 +554,55 @@ export async function updateRequirementInDb( try { const db = await import('./gsd-db.js'); - const existing = db.getRequirementById(id); + let existing = db.getRequirementById(id); + + // If requirement doesn't exist in DB, seed the entire requirements table + // from REQUIREMENTS.md first (#3346). This handles the standard workflow + // where requirements are authored in markdown during discussion but never + // imported into the database — making gsd_requirement_update always fail + // with "not_found" at milestone completion. if (!existing) { - throw new GSDError(GSD_STALE_STATE, `Requirement ${id} not found`); + const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS'); + try { + const content = readFileSync(reqFilePath, 'utf-8'); + const { parseRequirementsSections } = await import('./md-importer.js'); + const parsed = parseRequirementsSections(content); + if (parsed.length > 0) { + logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' }); + for (const req of parsed) { + // Only seed if not already in DB (avoid overwriting concurrent inserts) + if (!db.getRequirementById(req.id)) { + db.upsertRequirement(req); + } + } + // Re-check after seeding + existing = db.getRequirementById(id); + } + } catch { + // REQUIREMENTS.md missing or unparseable — fall through to skeleton + } } - // Merge updates into existing + const base: Requirement = existing ?? { + id, + class: '', + status: 'active', + description: '', + why: '', + source: '', + primary_owner: '', + supporting_slices: '', + validation: '', + notes: '', + full_content: '', + superseded_by: null, + }; + + // Merge updates into existing (or skeleton) const merged: Requirement = { - ...existing, + ...base, ...updates, - id: existing.id, // ID cannot be changed + id: base.id, // ID cannot be changed }; db.upsertRequirement(merged); @@ -388,7 +638,9 @@ export async function updateRequirementInDb( await saveFile(filePath, md); } catch (diskErr) { logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) }); - db.upsertRequirement(existing); + if (existing) { + db.upsertRequirement(existing); + } throw diskErr; } // Invalidate file-read caches so deriveState() sees the updated markdown. diff --git a/src/resources/extensions/gsd/detection.ts b/src/resources/extensions/gsd/detection.ts index 0bf69ddc9..3cfa9bdb8 100644 --- a/src/resources/extensions/gsd/detection.ts +++ b/src/resources/extensions/gsd/detection.ts @@ -242,6 +242,12 @@ const TEST_MARKERS = [ /** Directories skipped during bounded recursive project scans. */ const RECURSIVE_SCAN_IGNORED_DIRS = new Set([ ".git", + ".gsd", + ".planning", + ".plans", + ".claude", + ".cursor", + ".vscode", "node_modules", ".venv", "venv", @@ -1114,7 +1120,7 @@ function resolveVersionCatalogAccessors( return accessors; } -function scanProjectFiles(basePath: string): string[] { +export function scanProjectFiles(basePath: string): string[] { const files: string[] = []; const queue: Array<{ path: string; depth: number }> = [{ path: basePath, depth: 0 }]; diff --git a/src/resources/extensions/gsd/dispatch-guard.ts b/src/resources/extensions/gsd/dispatch-guard.ts index 59df30db1..568f872d0 100644 --- a/src/resources/extensions/gsd/dispatch-guard.ts +++ b/src/resources/extensions/gsd/dispatch-guard.ts @@ -5,6 +5,7 @@ import { findMilestoneIds } from "./guided-flow.js"; import { parseUnitId } from "./unit-id.js"; import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js"; import { parseRoadmap } from "./parsers-legacy.js"; +import { isClosedStatus } from "./status-guards.js"; import { readFileSync } from "node:fs"; const SLICE_DISPATCH_TYPES = new Set([ @@ -57,7 +58,7 @@ export function getPriorSliceCompletionBlocker( if (rows.length > 0) { slices = rows.map((r) => ({ id: r.id, - done: r.status === "complete", + done: isClosedStatus(r.status), depends: r.depends ?? [], })); } @@ -106,10 +107,27 @@ export function getPriorSliceCompletionBlocker( // it may be a cross-milestone reference handled elsewhere. } } else { + // Positional fallback is only a heuristic for legacy slices with no + // declared dependencies. Skip any earlier slice that depends on the + // target, directly or transitively, or we can deadlock a valid zero-dep + // slice behind its own downstream dependents (#3720). + const reverseDependents = new Set(); + let changed = true; + while (changed) { + changed = false; + for (const slice of slices) { + if (reverseDependents.has(slice.id)) continue; + if (slice.depends.some((depId) => depId === targetSid || reverseDependents.has(depId))) { + reverseDependents.add(slice.id); + changed = true; + } + } + } + const targetIndex = slices.findIndex((slice) => slice.id === targetSid); const incomplete = slices .slice(0, targetIndex) - .find((slice) => !slice.done); + .find((slice) => !slice.done && !reverseDependents.has(slice.id)); if (incomplete) { return `Cannot dispatch ${unitType} ${unitId}: earlier slice ${targetMid}/${incomplete.id} is not complete.`; } diff --git a/src/resources/extensions/gsd/docs/preferences-reference.md b/src/resources/extensions/gsd/docs/preferences-reference.md index 8f110ce37..cc8c4b3b0 100644 --- a/src/resources/extensions/gsd/docs/preferences-reference.md +++ b/src/resources/extensions/gsd/docs/preferences-reference.md @@ -189,6 +189,13 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `budget_pressure`: boolean — downgrade model tier when budget is under pressure. Default: `true`. - `cross_provider`: boolean — allow routing across different providers. Default: `true`. - `hooks`: boolean — enable routing hooks. Default: `true`. + - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`. + +- `context_management`: configures context hygiene for auto-mode sessions. Keys: + - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`. + - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`. + - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.70`. + - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`. - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`. @@ -204,6 +211,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea - `budget_ceiling`: number — optional per-parallel-run budget ceiling. - `merge_strategy`: `"per-slice"` or `"per-milestone"` — when to merge worktree results back. Default: `"per-milestone"`. - `auto_merge`: `"auto"`, `"confirm"`, or `"manual"` — merge behavior after completion. `"auto"` merges immediately; `"confirm"` asks first; `"manual"` leaves branches for you. Default: `"confirm"`. + - `worker_model`: string — optional model override for parallel milestone workers. When set, workers use this model (e.g. `"claude-haiku-4-5"`) instead of inheriting the coordinator's model. Useful for cost savings on execution-heavy milestones. - `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes. diff --git a/src/resources/extensions/gsd/doctor-engine-checks.ts b/src/resources/extensions/gsd/doctor-engine-checks.ts index 8b74dcac4..e7fc57540 100644 --- a/src/resources/extensions/gsd/doctor-engine-checks.ts +++ b/src/resources/extensions/gsd/doctor-engine-checks.ts @@ -13,6 +13,20 @@ export async function checkEngineHealth( issues: DoctorIssue[], fixesApplied: string[], ): Promise { + const dbPath = join(basePath, ".gsd", "gsd.db"); + + if (!isDbAvailable() && existsSync(dbPath)) { + issues.push({ + severity: "warning", + code: "db_unavailable", + scope: "project", + unitId: "project", + message: "Database unavailable — using filesystem state derivation (degraded mode). State queries may be slower and less reliable.", + file: ".gsd/gsd.db", + fixable: false, + }); + } + // ── DB constraint violation detection (full doctor only, not pre-dispatch per D-10) ── try { if (isDbAvailable()) { diff --git a/src/resources/extensions/gsd/doctor-format.ts b/src/resources/extensions/gsd/doctor-format.ts index 841f7ee13..a22d64e97 100644 --- a/src/resources/extensions/gsd/doctor-format.ts +++ b/src/resources/extensions/gsd/doctor-format.ts @@ -2,6 +2,7 @@ import type { DoctorIssue, DoctorIssueCode, DoctorReport, DoctorSummary } from " function matchesScope(unitId: string, scope?: string): boolean { if (!scope) return true; + if (unitId === "project" || unitId === "environment") return true; return unitId === scope || unitId.startsWith(`${scope}/`) || unitId.startsWith(`${scope}`); } diff --git a/src/resources/extensions/gsd/doctor-git-checks.ts b/src/resources/extensions/gsd/doctor-git-checks.ts index 0b8820108..2ceffe97e 100644 --- a/src/resources/extensions/gsd/doctor-git-checks.ts +++ b/src/resources/extensions/gsd/doctor-git-checks.ts @@ -10,10 +10,32 @@ import { deriveState, isMilestoneComplete } from "./state.js"; import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js"; import { abortAndReset } from "./git-self-heal.js"; import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js"; -import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached } from "./native-git-bridge.js"; +import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js"; import { getAllWorktreeHealth } from "./worktree-health.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; +/** + * Returns true if the directory contains only doctor artifacts + * (e.g. `.gsd/doctor-history.jsonl`). These dirs are created by + * appendDoctorHistory() writing to worktree-scoped paths during the audit + * and should not be flagged as orphaned worktrees (#3105). + */ +function isDoctorArtifactOnly(dirPath: string): boolean { + try { + const entries = readdirSync(dirPath); + // Empty dir — not a doctor artifact, still orphaned + if (entries.length === 0) return false; + // Only a .gsd subdirectory + if (entries.length === 1 && entries[0] === ".gsd") { + const gsdEntries = readdirSync(join(dirPath, ".gsd")); + return gsdEntries.length <= 1 && gsdEntries.every(e => e === "doctor-history.jsonl"); + } + return false; + } catch { + return false; + } +} + export async function checkGitHealth( basePath: string, issues: DoctorIssue[], @@ -314,6 +336,10 @@ export async function checkGitHealth( } catch { continue; } const normalizedFullPath = normalizePath(fullPath); if (!registeredPaths.has(normalizedFullPath)) { + // Skip directories that only contain doctor artifacts (.gsd/doctor-history.jsonl). + // appendDoctorHistory() can recreate these dirs during the audit itself, + // causing a circular false positive (#3105 Bug 1). + if (isDoctorArtifactOnly(fullPath)) continue; issues.push({ severity: "warning", code: "worktree_directory_orphaned", @@ -337,6 +363,54 @@ export async function checkGitHealth( // Non-fatal — orphaned worktree directory check failed } + // ── Stale uncommitted changes ──────────────────────────────────────────── + // If the working tree has uncommitted changes and the last commit was + // longer ago than the configured threshold, flag it and optionally + // auto-commit a safety snapshot so work isn't lost. + try { + const prefs = loadEffectiveGSDPreferences()?.preferences ?? {}; + const thresholdMinutes = prefs.stale_commit_threshold_minutes ?? 30; + + if (thresholdMinutes > 0) { + const dirty = nativeHasChanges(basePath); + if (dirty) { + const branch = nativeGetCurrentBranch(basePath); + const lastEpoch = nativeLastCommitEpoch(basePath, branch || "HEAD"); + const nowEpoch = Math.floor(Date.now() / 1000); + const minutesSinceCommit = lastEpoch > 0 ? (nowEpoch - lastEpoch) / 60 : Infinity; + + if (minutesSinceCommit >= thresholdMinutes) { + const mins = Math.floor(minutesSinceCommit); + issues.push({ + severity: "warning", + code: "stale_uncommitted_changes", + scope: "project", + unitId: "project", + message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting tracked files.`, + fixable: true, + }); + + if (shouldFix("stale_uncommitted_changes")) { + try { + nativeAddTracked(basePath); + const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`; + const result = nativeCommit(basePath, commitMsg); + if (result) { + fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`); + } else { + fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files"); + } + } catch { + fixesApplied.push("failed to create gsd snapshot commit"); + } + } + } + } + } + } catch { + // Non-fatal — stale commit check failed + } + // ── Worktree lifecycle checks ────────────────────────────────────────── // Check GSD-managed worktrees for: merged branches, stale work, dirty // state, and unpushed commits. Only worktrees under .gsd/worktrees/. diff --git a/src/resources/extensions/gsd/doctor-proactive.ts b/src/resources/extensions/gsd/doctor-proactive.ts index 0eb3b016f..eb7c11a7f 100644 --- a/src/resources/extensions/gsd/doctor-proactive.ts +++ b/src/resources/extensions/gsd/doctor-proactive.ts @@ -22,7 +22,7 @@ import { abortAndReset } from "./git-self-heal.js"; import { rebuildState } from "./doctor.js"; import { deriveState } from "./state.js"; import { resolveMilestoneIntegrationBranch } from "./git-service.js"; -import { nativeIsRepo } from "./native-git-bridge.js"; +import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; import { runEnvironmentChecks } from "./doctor-environment.js"; @@ -295,6 +295,40 @@ export async function preDispatchHealthGate(basePath: string): Promise 0 && nativeHasChanges(basePath)) { + const branch = nativeGetCurrentBranch(basePath); + const lastEpoch = nativeLastCommitEpoch(basePath, branch || "HEAD"); + const nowEpoch = Math.floor(Date.now() / 1000); + const minutesSinceCommit = lastEpoch > 0 ? (nowEpoch - lastEpoch) / 60 : Infinity; + + if (minutesSinceCommit >= thresholdMinutes) { + const mins = Math.floor(minutesSinceCommit); + try { + nativeAddTracked(basePath); + const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`; + const result = nativeCommit(basePath, commitMsg); + if (result) { + fixesApplied.push(`pre-dispatch: created gsd snapshot after ${mins}m of uncommitted changes`); + } + } catch { + // Non-blocking — snapshot failed but dispatch can continue + fixesApplied.push("pre-dispatch: gsd snapshot failed"); + } + } + } + } + } catch { + // Non-fatal + } + // ── Disk space check ── // Catches low-disk conditions before dispatch rather than letting the unit // fail mid-execution with ENOSPC (which wastes a full LLM turn). diff --git a/src/resources/extensions/gsd/doctor-providers.ts b/src/resources/extensions/gsd/doctor-providers.ts index 99c8c4ede..e0f35341b 100644 --- a/src/resources/extensions/gsd/doctor-providers.ts +++ b/src/resources/extensions/gsd/doctor-providers.ts @@ -181,7 +181,8 @@ function resolveKey(providerId: string): KeyLookup { */ const PROVIDER_ROUTES: Record = { anthropic: ["github-copilot"], - openai: ["github-copilot"], + openai: ["github-copilot", "openai-codex"], + google: ["google-gemini-cli"], }; function checkLlmProviders(): ProviderCheckResult[] { diff --git a/src/resources/extensions/gsd/doctor-runtime-checks.ts b/src/resources/extensions/gsd/doctor-runtime-checks.ts index 1137981a7..d2af2bd9a 100644 --- a/src/resources/extensions/gsd/doctor-runtime-checks.ts +++ b/src/resources/extensions/gsd/doctor-runtime-checks.ts @@ -119,10 +119,11 @@ export async function checkRuntimeHealth( for (const key of keys) { // Key format: "unitType/unitId" e.g. "execute-task/M001/S01/T01" - const slashIdx = key.indexOf("/"); - if (slashIdx === -1) continue; - const unitType = key.slice(0, slashIdx); - const unitId = key.slice(slashIdx + 1); + // Hook units have compound types: "hook//unitId" + const { splitCompletedKey } = await import("./forensics.js"); + const parsed = splitCompletedKey(key); + if (!parsed) continue; + const { unitType, unitId } = parsed; // Only validate artifact-producing unit types const { verifyExpectedArtifact } = await import("./auto-recovery.js"); diff --git a/src/resources/extensions/gsd/doctor-types.ts b/src/resources/extensions/gsd/doctor-types.ts index 864e8f8fa..309848048 100644 --- a/src/resources/extensions/gsd/doctor-types.ts +++ b/src/resources/extensions/gsd/doctor-types.ts @@ -61,6 +61,8 @@ export type DoctorIssueCode = | "worktree_stale" | "worktree_dirty" | "worktree_unpushed" + // Stale commit safety check + | "stale_uncommitted_changes" // Snapshot ref bloat | "snapshot_ref_bloat" // Runtime data integrity @@ -76,6 +78,7 @@ export type DoctorIssueCode = | "db_orphaned_slice" | "db_done_task_no_summary" | "db_duplicate_id" + | "db_unavailable" | "projection_drift"; /** diff --git a/src/resources/extensions/gsd/doctor.ts b/src/resources/extensions/gsd/doctor.ts index 83fc8a754..bf3a59307 100644 --- a/src/resources/extensions/gsd/doctor.ts +++ b/src/resources/extensions/gsd/doctor.ts @@ -8,6 +8,7 @@ import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSl import { deriveState, isMilestoneComplete } from "./state.js"; import { invalidateAllCaches } from "./cache.js"; import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js"; +import { isClosedStatus } from "./status-guards.js"; import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js"; import { GLOBAL_STATE_CODES } from "./doctor-types.js"; @@ -87,7 +88,8 @@ function validatePreferenceShape(preferences: GSDPreferences): string[] { return issues; } -function buildStateMarkdown(state: Awaited>): string { +/** Build STATE.md content from derived state. Exported for guided-flow pre-dispatch rebuild (#3475). */ +export function buildStateMarkdown(state: Awaited>): string { const lines: string[] = []; lines.push("# GSD State", ""); @@ -473,15 +475,16 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; if (!roadmapContent) continue; // Normalize slices: prefer DB, fall back to parser - type NormSlice = RoadmapSliceEntry & { pending?: boolean }; + type NormSlice = RoadmapSliceEntry & { pending?: boolean; skipped?: boolean }; let slices: NormSlice[]; if (isDbAvailable()) { const dbSlices = getMilestoneSlices(milestoneId); slices = dbSlices.map(s => ({ id: s.id, title: s.title, - done: s.status === "complete", + done: isClosedStatus(s.status), pending: s.status === "pending", + skipped: s.status === "skipped", risk: (s.risk || "medium") as RoadmapSliceEntry["risk"], depends: s.depends, demo: s.demo, @@ -577,8 +580,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; const slicePath = resolveSlicePath(basePath, milestoneId, slice.id); if (!slicePath) { // Pending slices haven't been planned yet — directories are created - // lazily by ensurePreconditions() at dispatch time. Skip them. - if (slice.pending) continue; + // lazily by ensurePreconditions() at dispatch time. Skipped slices are + // intentionally allowed to remain summary-less and directory-less. + if (slice.pending || slice.skipped) continue; const expectedPath = relSlicePath(basePath, milestoneId, slice.id); issues.push({ severity: slice.done ? "warning" : "error", @@ -602,7 +606,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id); if (!tasksDir) { // Pending slices haven't been planned yet — tasks/ is created on demand. - if (slice.pending) continue; + // Skipped slices may legitimately never create tasks/. + if (slice.pending || slice.skipped) continue; issues.push({ severity: slice.done ? "warning" : "error", code: "missing_tasks_dir", @@ -729,8 +734,10 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; } // Blocker-without-replan detection + // Skip when all tasks are done — the blocker was implicitly resolved + // within the task and the slice is not stuck (#3105 Bug 2). const replanPath = resolveSliceFile(basePath, milestoneId, slice.id, "REPLAN"); - if (!replanPath) { + if (!replanPath && !allTasksDone) { for (const task of plan.tasks) { if (!task.done) continue; const summaryPath = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"); diff --git a/src/resources/extensions/gsd/error-classifier.ts b/src/resources/extensions/gsd/error-classifier.ts index c63927b98..604167451 100644 --- a/src/resources/extensions/gsd/error-classifier.ts +++ b/src/resources/extensions/gsd/error-classifier.ts @@ -48,7 +48,9 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fet const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i; // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first). const CONNECTION_RE = /terminated|connection.?refused|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i; -const STREAM_RE = /Unexpected end of JSON|Unexpected token.*JSON|Expected double-quoted property name|SyntaxError.*JSON/i; +// Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+". +// This eliminates the need to enumerate every error message variant individually. +const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i; const RESET_DELAY_RE = /reset in (\d+)s/i; /** @@ -58,9 +60,9 @@ const RESET_DELAY_RE = /reset in (\d+)s/i; * 1. Permanent (auth/billing/quota) — unless also rate-limited * 2. Rate limit (429, rate.?limit, too many requests) * 3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns) - * 4. Server (500/502/503, overloaded, server_error) - * 5. Connection (terminated, ECONNREFUSED, EPIPE, other side closed) - * 6. Stream truncation (malformed JSON from mid-stream cut) + * 4. Stream truncation (malformed JSON from mid-stream cut) + * 5. Server (500/502/503, overloaded, server_error) + * 6. Connection (terminated, ECONNREFUSED, EPIPE, other side closed) * 7. Unknown */ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorClass { @@ -90,21 +92,21 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 }; } - // 4. Server errors — try fallback model + // 4. Stream truncation — downstream symptom of connection drop + if (STREAM_RE.test(errorMsg)) { + return { kind: "stream", retryAfterMs: retryAfterMs ?? 15_000 }; + } + + // 5. Server errors — try fallback model if (SERVER_RE.test(errorMsg)) { return { kind: "server", retryAfterMs: retryAfterMs ?? 30_000 }; } - // 5. Connection errors — try fallback model + // 6. Connection errors — try fallback model if (CONNECTION_RE.test(errorMsg)) { return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 }; } - // 6. Stream truncation — downstream symptom of connection drop - if (STREAM_RE.test(errorMsg)) { - return { kind: "stream", retryAfterMs: retryAfterMs ?? 15_000 }; - } - // 7. Unknown return { kind: "unknown" }; } diff --git a/src/resources/extensions/gsd/extension-manifest.json b/src/resources/extensions/gsd/extension-manifest.json index 2c01ab4ee..ca0063a5f 100644 --- a/src/resources/extensions/gsd/extension-manifest.json +++ b/src/resources/extensions/gsd/extension-manifest.json @@ -12,7 +12,22 @@ "gsd_requirement_update", "gsd_milestone_generate_id" ], "commands": ["gsd", "kill", "worktree", "exit"], - "hooks": ["session_start", "session_switch"], + "hooks": [ + "session_start", + "session_switch", + "bash_transform", + "session_fork", + "before_agent_start", + "agent_end", + "session_before_compact", + "session_shutdown", + "tool_call", + "tool_result", + "tool_execution_start", + "tool_execution_end", + "model_select", + "before_provider_request" + ], "shortcuts": ["Ctrl+Alt+G"] } } diff --git a/src/resources/extensions/gsd/file-lock.ts b/src/resources/extensions/gsd/file-lock.ts new file mode 100644 index 000000000..a40c77854 --- /dev/null +++ b/src/resources/extensions/gsd/file-lock.ts @@ -0,0 +1,59 @@ +import { existsSync } from "node:fs"; + +function _require(name: string) { + try { + return require(name); + } catch { + try { + const gsdPiRequire = require("module").createRequire( + require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js") + ); + return gsdPiRequire(name); + } catch { + return null; + } + } +} + +export function withFileLockSync(filePath: string, fn: () => T): T { + const lockfile = _require("proper-lockfile"); + if (!lockfile) return fn(); + + if (!existsSync(filePath)) return fn(); + + try { + const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 }); + try { + return fn(); + } finally { + release(); + } + } catch (err: any) { + if (err.code === "ELOCKED") { + // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine + return fn(); + } + throw err; + } +} + +export async function withFileLock(filePath: string, fn: () => Promise | T): Promise { + const lockfile = _require("proper-lockfile"); + if (!lockfile) return await fn(); + + if (!existsSync(filePath)) return await fn(); + + try { + const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 }); + try { + return await fn(); + } finally { + await release(); + } + } catch (err: any) { + if (err.code === "ELOCKED") { + return await fn(); + } + throw err; + } +} diff --git a/src/resources/extensions/gsd/files.ts b/src/resources/extensions/gsd/files.ts index 9bd194604..a59a8773a 100644 --- a/src/resources/extensions/gsd/files.ts +++ b/src/resources/extensions/gsd/files.ts @@ -70,6 +70,25 @@ export function clearParseCache(): void { for (const cb of _cacheClearCallbacks) cb(); } +// ─── Platform shortcuts ─────────────────────────────────────────────────── + +const IS_MAC = process.platform === "darwin"; + +/** + * Format a keyboard shortcut for the current OS. + * Input: modifier key combo like "Ctrl+Alt+G" + * Output: "⌃⌥G" on macOS, "Ctrl+Alt+G" on Windows/Linux. + */ +export function formatShortcut(combo: string): string { + if (!IS_MAC) return combo; + return combo + .replace(/Ctrl\+Alt\+/i, "⌃⌥") + .replace(/Ctrl\+/i, "⌃") + .replace(/Alt\+/i, "⌥") + .replace(/Shift\+/i, "⇧") + .replace(/Cmd\+/i, "⌘"); +} + // ─── Helpers ─────────────────────────────────────────────────────────────── /** Extract the text after a heading at a given level, up to the next heading of same or higher level. */ @@ -113,6 +132,25 @@ function escapeRegex(s: string): string { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); } +/** + * Normalize a task-plan file reference that may include inline description text + * after the path, for example: + * "docs/file.md — explanation" + * "docs/file.md - explanation" + */ +export function normalizePlannedFileReference(value: string): string { + const trimmed = value.trim().replace(/`/g, ""); + const match = /^(.*?)(?:\s+(?:—|-)\s+)(.+)$/.exec(trimmed); + if (!match) return trimmed; + + const pathCandidate = match[1].trim(); + if (pathCandidate.includes("/") || pathCandidate.includes("\\") || pathCandidate.includes(".")) { + return pathCandidate; + } + + return trimmed; +} + /** Parse bullet list items from a text block. */ export function parseBullets(text: string): string[] { return text.split('\n') @@ -603,11 +641,11 @@ export function parseTaskPlanIO(content: string): { inputFiles: string[]; output let match: RegExpExecArray | null; backtickPathRegex.lastIndex = 0; while ((match = backtickPathRegex.exec(trimmed)) !== null) { - const candidate = match[1]; + const candidate = normalizePlannedFileReference(match[1]); // Filter out things that look like code tokens rather than file paths // (e.g. `true`, `false`, `npm run test`). A file path has at least one // dot or slash. - if (candidate.includes("/") || candidate.includes(".")) { + if (candidate.includes("/") || candidate.includes("\\") || candidate.includes(".")) { paths.push(candidate); } } diff --git a/src/resources/extensions/gsd/forensics.ts b/src/resources/extensions/gsd/forensics.ts index 78c074202..ba2746f8b 100644 --- a/src/resources/extensions/gsd/forensics.ts +++ b/src/resources/extensions/gsd/forensics.ts @@ -28,6 +28,8 @@ import { deriveState } from "./state.js"; import { isAutoActive } from "./auto.js"; import { loadPrompt } from "./prompt-loader.js"; import { gsdRoot } from "./paths.js"; +import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks } from "./gsd-db.js"; +import { isClosedStatus } from "./status-guards.js"; import { formatDuration } from "../shared/format-utils.js"; import { getAutoWorktreePath } from "./auto-worktree.js"; import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js"; @@ -36,7 +38,7 @@ import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./comm // ─── Types ──────────────────────────────────────────────────────────────────── -interface ForensicAnomaly { +export interface ForensicAnomaly { type: "stuck-loop" | "cost-spike" | "timeout" | "missing-artifact" | "crash" | "doctor-issue" | "error-trace" | "journal-stuck" | "journal-guard-block" | "journal-rapid-iterations" | "journal-worktree-failure"; severity: "info" | "warning" | "error"; unitType?: string; @@ -85,6 +87,15 @@ interface JournalSummary { fileCount: number; } +interface DbCompletionCounts { + milestones: number; + milestonesTotal: number; + slices: number; + slicesTotal: number; + tasks: number; + tasksTotal: number; +} + interface ForensicReport { gsdVersion: string; timestamp: string; @@ -95,6 +106,7 @@ interface ForensicReport { unitTraces: UnitTrace[]; metrics: MetricsLedger | null; completedKeys: string[]; + dbCompletionCounts: DbCompletionCounts | null; crashLock: LockData | null; doctorIssues: DoctorIssue[]; anomalies: ForensicAnomaly[]; @@ -106,13 +118,15 @@ interface ForensicReport { // ─── Duplicate Detection ────────────────────────────────────────────────────── const DEDUP_PROMPT_SECTION = ` -## Duplicate Detection (REQUIRED before issue creation) +## Pre-Investigation: Duplicate Check (REQUIRED) -Before offering to create a GitHub issue, you MUST search for existing issues and PRs that may already address this bug. This step uses the user's AI tokens for analysis. +Before reading GSD source code or performing deep analysis, you MUST search for existing issues and PRs that may already address this bug. This avoids wasting tokens on already-fixed bugs. ### Search Steps -1. **Search closed issues** for similar keywords from your diagnosis: +Use keywords from the user's problem description and the anomaly summaries in the forensic report above. + +1. **Search closed issues** for similar keywords: \`\`\` gh issue list --repo gsd-build/gsd-2 --state closed --search "" --limit 20 \`\`\` @@ -129,20 +143,16 @@ Before offering to create a GitHub issue, you MUST search for existing issues an ### Analysis -For each result, compare it against your root-cause diagnosis: +For each result, compare it against the user's reported symptoms and the forensic anomalies: - Does the issue describe the same code path or file? -- Does the PR modify the same file:line you identified? +- Does the PR modify the area related to the reported symptoms? - Is the symptom description semantically similar even if keywords differ? -### Present Findings +### Decision Gate -If you find potential matches, present them to the user: - -1. **"Already fixed by PR #X — skip issue creation"** — when a merged PR or closed issue clearly addresses the same root cause. Explain why you believe it matches. -2. **"Add my findings to existing issue #Y"** — when an open issue exists for the same bug. Use \`gh issue comment #Y --repo gsd-build/gsd-2\` to add forensic evidence. -3. **"Create new issue anyway"** — when existing results do not cover this specific failure. - -Only proceed to issue creation if no matches were found OR the user explicitly chooses "Create new issue anyway". +- **Merged PR clearly fixes the described symptom** → Report "Already fixed by PR #X" with brief explanation. Skip full investigation. +- **Open issue matches** → Report "Existing issue #Y covers this." Offer to add forensic evidence. Skip full investigation unless user asks for deeper analysis. +- **No matches** → Proceed to full investigation below. `; async function writeForensicsDedupPref(ctx: ExtensionCommandContext, enabled: boolean): Promise { @@ -250,6 +260,9 @@ export async function handleForensics( { customType: "gsd-forensics", content, display: false }, { triggerTurn: true }, ); + + // Persist forensics context so follow-up turns can re-inject it (#2941) + writeForensicsMarker(basePath, savedPath, content); } // ─── Report Builder ─────────────────────────────────────────────────────────── @@ -275,8 +288,9 @@ export async function buildForensicReport(basePath: string): Promise(); +/** + * Detect units that were dispatched multiple times (stuck in a loop). + * + * Counts distinct dispatches by grouping on (type, id, startedAt) first to + * collapse idle-watchdog duplicate snapshots (#1943), then counts unique + * startedAt values per type/id to determine actual dispatch count. + * + * Exported for testability. + */ +export function detectStuckLoops(units: UnitMetrics[], anomalies: ForensicAnomaly[]): void { + // First, collect unique startedAt values per type/id key + const dispatchMap = new Map>(); for (const u of units) { const key = `${u.type}/${u.id}`; - counts.set(key, (counts.get(key) ?? 0) + 1); + let starts = dispatchMap.get(key); + if (!starts) { + starts = new Set(); + dispatchMap.set(key, starts); + } + starts.add(u.startedAt); } - for (const [key, count] of counts) { + for (const [key, starts] of dispatchMap) { + const count = starts.size; if (count > 1) { const [unitType, ...idParts] = key.split("/"); anomalies.push({ @@ -649,15 +718,42 @@ function detectTimeouts(traces: UnitTrace[], anomalies: ForensicAnomaly[]): void } } +/** + * Parse a completed-unit key into its unitType and unitId. + * + * Hook units use a compound slash-delimited type ("hook/"), so a + * naive `key.indexOf("/")` would split "hook/telegram-progress/M007/S01" into + * unitType="hook" (wrong) instead of "hook/telegram-progress". + * + * Returns `null` for malformed keys that cannot be split. + */ +export function splitCompletedKey(key: string): { unitType: string; unitId: string } | null { + if (key.startsWith("hook/")) { + // Hook unit types are two segments: "hook//" + const secondSlash = key.indexOf("/", 5); // skip past "hook/" + if (secondSlash === -1) return null; // malformed — no unitId after hook name + return { + unitType: key.slice(0, secondSlash), + unitId: key.slice(secondSlash + 1), + }; + } + + const slashIdx = key.indexOf("/"); + if (slashIdx === -1) return null; + return { + unitType: key.slice(0, slashIdx), + unitId: key.slice(slashIdx + 1), + }; +} + function detectMissingArtifacts(completedKeys: string[], basePath: string, activeMilestone: string | null, anomalies: ForensicAnomaly[]): void { // Also check the worktree path for artifacts — they may exist there but not at root const wtBasePath = activeMilestone ? getAutoWorktreePath(basePath, activeMilestone) : null; for (const key of completedKeys) { - const slashIdx = key.indexOf("/"); - if (slashIdx === -1) continue; - const unitType = key.slice(0, slashIdx); - const unitId = key.slice(slashIdx + 1); + const parsed = splitCompletedKey(key); + if (!parsed) continue; + const { unitType, unitId } = parsed; const rootHasArtifact = verifyExpectedArtifact(unitType, unitId, basePath); const wtHasArtifact = wtBasePath ? verifyExpectedArtifact(unitType, unitId, wtBasePath) : false; @@ -896,6 +992,42 @@ function saveForensicReport(basePath: string, report: ForensicReport, problemDes return filePath; } +// ─── Forensics Session Marker ──────────────────────────────────────────────── + +export interface ForensicsMarker { + reportPath: string; + promptContent: string; + createdAt: string; +} + +/** + * Write a marker file so that buildBeforeAgentStartResult() can re-inject + * the forensics prompt on follow-up turns. (#2941) + */ +export function writeForensicsMarker(basePath: string, reportPath: string, promptContent: string): void { + const dir = join(gsdRoot(basePath), "runtime"); + mkdirSync(dir, { recursive: true }); + const marker: ForensicsMarker = { + reportPath, + promptContent, + createdAt: new Date().toISOString(), + }; + writeFileSync(join(dir, "active-forensics.json"), JSON.stringify(marker), "utf-8"); +} + +/** + * Read the active forensics marker, or null if none exists. + */ +export function readForensicsMarker(basePath: string): ForensicsMarker | null { + const markerPath = join(gsdRoot(basePath), "runtime", "active-forensics.json"); + if (!existsSync(markerPath)) return null; + try { + return JSON.parse(readFileSync(markerPath, "utf-8")) as ForensicsMarker; + } catch { + return null; + } +} + // ─── Prompt Formatter ───────────────────────────────────────────────────────── function formatReportForPrompt(report: ForensicReport): string { @@ -1008,8 +1140,16 @@ function formatReportForPrompt(report: ForensicReport): string { sections.push(""); } - // Completed keys count - sections.push(`### Completed Keys: ${report.completedKeys.length}`); + // Completion status — prefer DB counts, fall back to legacy completed-units.json + if (report.dbCompletionCounts) { + const c = report.dbCompletionCounts; + sections.push(`### Completion Status (from DB)`); + sections.push(`- ${c.milestones}/${c.milestonesTotal} milestones complete`); + sections.push(`- ${c.slices}/${c.slicesTotal} slices complete`); + sections.push(`- ${c.tasks}/${c.tasksTotal} tasks complete`); + } else { + sections.push(`### Completed Keys: ${report.completedKeys.length}`); + } sections.push(`### GSD Version: ${report.gsdVersion}`); sections.push(`### Active Milestone: ${report.activeMilestone ?? "none"}`); sections.push(`### Active Slice: ${report.activeSlice ?? "none"}`); diff --git a/src/resources/extensions/gsd/git-service.ts b/src/resources/extensions/gsd/git-service.ts index d7c543182..ae73a0e94 100644 --- a/src/resources/extensions/gsd/git-service.ts +++ b/src/resources/extensions/gsd/git-service.ts @@ -9,7 +9,7 @@ */ import { execFileSync, execSync } from "node:child_process"; -import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { gsdRoot } from "./paths.js"; import { GIT_NO_PROMPT_ENV } from "./git-constants.js"; @@ -32,6 +32,8 @@ import { nativeRmCached, nativeUpdateRef, nativeAddPaths, + nativeResetSoft, + nativeCommitSubject, } from "./native-git-bridge.js"; import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js"; import { getErrorMessage } from "./error-utils.js"; @@ -50,9 +52,9 @@ export interface GitPreferences { main_branch?: string; merge_strategy?: "squash" | "merge"; /** Controls auto-mode git isolation strategy. - * - "worktree": (default) creates a milestone worktree for isolated work + * - "worktree": creates a milestone worktree for isolated work * - "branch": works directly in the project root (for submodule-heavy repos) - * - "none": no git isolation — commits land on the user's current branch directly + * - "none": (default) no git isolation — commits land on the user's current branch directly */ isolation?: "worktree" | "branch" | "none"; /** When false, GSD will not modify .gitignore at all — no baseline patterns @@ -77,6 +79,11 @@ export interface GitPreferences { * Default: the main branch (from `main_branch` or auto-detected). */ pr_target_branch?: string; + /** Whether to squash `gsd snapshot:` commits into the next real autoCommit. + * Enabled by default. Set to false to keep snapshot commits in history + * for forensic inspection. + */ + absorb_snapshot_commits?: boolean; } export const VALID_BRANCH_NAME = /^[a-zA-Z0-9_\-\/.]+$/; @@ -488,6 +495,29 @@ export class GitServiceImpl { // If .gsd/ IS in .gitignore (the default for external state projects), // git add -A already skips it and the exclusions are harmless no-ops. const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions]; + + // ── Parallel worker milestone scope (#1991) ── + // When GSD_MILESTONE_LOCK is set, this process is a parallel worker that + // must only commit files belonging to its own milestone. Exclude all other + // milestone directories from staging to prevent cross-milestone pollution + // (e.g., an M033 worker fabricating M032 artifacts in the same commit). + const milestoneLock = process.env.GSD_MILESTONE_LOCK; + if (milestoneLock) { + const msDir = join(gsdRoot(this.basePath), "milestones"); + if (existsSync(msDir)) { + try { + const entries = readdirSync(msDir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory() && entry.name !== milestoneLock) { + allExclusions.push(`.gsd/milestones/${entry.name}/`); + } + } + } catch { + // Best-effort — if we can't read the milestones dir, proceed without scoping + } + } + } + nativeAddAllWithExclusions(this.basePath, allExclusions); } @@ -540,9 +570,95 @@ export class GitServiceImpl { ? buildTaskCommitMessage(taskContext) : `chore: auto-commit after ${unitType}\n\nGSD-Unit: ${unitId}`; nativeCommit(this.basePath, message, { allowEmpty: false }); + + // Absorb any preceding gsd snapshot commits into this real commit. + // Walk backwards from HEAD~1 counting consecutive snapshot subjects, + // then soft-reset to before them and re-commit with the same message. + this.absorbSnapshotCommits(message); + return message; } + /** + * Squash consecutive `gsd snapshot:` commits that sit immediately below + * HEAD into the current HEAD commit. This keeps the git history clean + * after automated snapshot commits are superseded by real work. + * + * Guards: + * - Opt-in via `absorb_snapshot_commits` preference (default: true). + * - Refuses to rewrite commits that have been pushed to the remote + * tracking branch (checks merge-base ancestry). + * - Saves HEAD SHA before reset; restores it if the re-commit fails. + * + * Does nothing if there are no snapshot commits to absorb. + */ + private absorbSnapshotCommits(headMessage: string): void { + try { + // Opt-in guard — users can disable to keep snapshot commits for forensics + if (this.prefs.absorb_snapshot_commits === false) return; + + const GSD_SNAPSHOT_PREFIX = "gsd snapshot:"; + let count = 0; + + // Walk back from HEAD~1 counting consecutive snapshot commits (cap at 10) + for (let i = 1; i <= 10; i++) { + const subject = nativeCommitSubject(this.basePath, `HEAD~${i}`); + if (!subject.startsWith(GSD_SNAPSHOT_PREFIX)) break; + count = i; + } + + if (count === 0) return; + + // Guard: don't rewrite history that has been pushed to the remote. + // Check whether the newest snapshot commit (HEAD~1) is already + // reachable from the remote tracking branch. If it is, the snapshots + // have been pushed and must not be squashed via local history rewrite. + // (Checking resetTarget instead would false-positive when the remote + // is at the pre-snapshot base but the snapshots themselves are local.) + const resetTarget = `HEAD~${count + 1}`; + try { + const branch = nativeGetCurrentBranch(this.basePath); + if (branch) { + const remoteBranch = `origin/${branch}`; + // merge-base --is-ancestor exits 0 if HEAD~1 is ancestor of remote + execFileSync("git", ["merge-base", "--is-ancestor", "HEAD~1", remoteBranch], { + cwd: this.basePath, + stdio: ["ignore", "pipe", "pipe"], + }); + // If we get here, newest snapshot IS reachable from remote — already pushed + return; + } + } catch { + // Not an ancestor or remote doesn't exist — safe to proceed + } + + // Save HEAD SHA so we can restore if the re-commit fails + const savedHead = execFileSync("git", ["rev-parse", "HEAD"], { + cwd: this.basePath, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); + + nativeResetSoft(this.basePath, resetTarget); + + // Re-run smartStage so the same RUNTIME_EXCLUSION_PATHS apply. + // Snapshot commits used nativeAddTracked (git add -u) which stages + // ALL tracked modifications including .gsd/ state files. Without + // re-staging, those .gsd/ changes leak into the absorbed commit. + this.smartStage(); + + try { + nativeCommit(this.basePath, headMessage, { allowEmpty: false }); + } catch { + // Re-commit failed — restore original HEAD to avoid leaving the + // repo in a partially-reset state with no commit + nativeResetSoft(this.basePath, savedHead); + } + } catch { + // Non-fatal — if squash fails, the commits remain unsquashed + } + } + // ─── Branch Queries ──────────────────────────────────────────────────── /** diff --git a/src/resources/extensions/gsd/gitignore.ts b/src/resources/extensions/gsd/gitignore.ts index da4b2ee91..8a80c3da5 100644 --- a/src/resources/extensions/gsd/gitignore.ts +++ b/src/resources/extensions/gsd/gitignore.ts @@ -41,6 +41,8 @@ const GSD_RUNTIME_PATTERNS = [ const BASELINE_PATTERNS = [ // ── GSD state directory (symlink to external storage) ── ".gsd", + ".gsd-id", + ".bg-shell/", // ── OS junk ── ".DS_Store", @@ -84,6 +86,38 @@ const BASELINE_PATTERNS = [ "tmp/", ]; +/** + * Check whether `.gsd` is covered by the project's `.gitignore`. + * + * Uses `git check-ignore` for accurate evaluation — this respects nested + * .gitignore files, global gitignore, and negation patterns. Returns true + * only when git would actually ignore `.gsd/`. + * + * Returns false (not ignored) if: + * - No `.gitignore` exists + * - `.gsd` is not listed in any active ignore rule + * - Not a git repo or git is unavailable + */ +export function isGsdGitignored(basePath: string): boolean { + // Check both `.gsd` and `.gsd/` because `.gsd/` in .gitignore (trailing + // slash = directory-only pattern) only matches the directory form. Using + // both paths covers all gitignore pattern variants. + for (const path of [".gsd", ".gsd/"]) { + try { + // git check-ignore exits 0 when the path IS ignored, 1 when it is NOT. + execFileSync("git", ["check-ignore", "-q", path], { + cwd: basePath, + stdio: "pipe", + env: GIT_NO_PROMPT_ENV, + }); + return true; // exit 0 → .gsd is ignored + } catch { + // exit 1 → this form is NOT ignored, try the other + } + } + return false; // neither form is ignored (or git unavailable) +} + /** * Check whether `.gsd/` contains files tracked by git. * If so, the project intentionally keeps `.gsd/` in version control diff --git a/src/resources/extensions/gsd/gsd-db.ts b/src/resources/extensions/gsd/gsd-db.ts index 1559b8616..e440bdb44 100644 --- a/src/resources/extensions/gsd/gsd-db.ts +++ b/src/resources/extensions/gsd/gsd-db.ts @@ -10,6 +10,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs"; import { dirname } from "node:path"; import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js"; import { GSDError, GSD_STALE_STATE } from "./errors.js"; +import { logError, logWarning } from "./workflow-logger.js"; const _require = createRequire(import.meta.url); @@ -408,6 +409,7 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void { db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)"); db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)"); db.exec("CREATE INDEX IF NOT EXISTS idx_verification_evidence_task ON verification_evidence(milestone_id, slice_id, task_id)"); + db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_verification_evidence_dedup ON verification_evidence(task_id, slice_id, milestone_id, command, verdict)"); // v14 index — slice dependency lookups db.exec("CREATE INDEX IF NOT EXISTS idx_slice_deps_target ON slice_dependencies(milestone_id, depends_on_slice_id)"); @@ -449,6 +451,25 @@ function migrateSchema(db: DbAdapter): void { const currentVersion = row ? (row["v"] as number) : 0; if (currentVersion >= SCHEMA_VERSION) return; + // Backup database before migration so a mid-migration crash doesn't + // leave a partially-migrated DB with no recovery path. + // WAL-safe: checkpoint first to flush WAL into the main DB file, then copy. + if (currentPath && currentPath !== ":memory:" && existsSync(currentPath)) { + try { + const backupPath = `${currentPath}.backup-v${currentVersion}`; + if (!existsSync(backupPath)) { + // Flush WAL to main DB file before copying — without this, the backup + // may be missing committed data that only exists in the -wal file. + try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch { /* checkpoint is best-effort */ } + copyFileSync(currentPath, backupPath); + } + } catch (backupErr) { + // Log but proceed — blocking migration leaves the DB stuck at an old + // schema version permanently on read-only or full filesystems. + logWarning("db", `Pre-migration backup failed: ${backupErr instanceof Error ? backupErr.message : String(backupErr)}`); + } + } + db.exec("BEGIN"); try { if (currentVersion < 2) { @@ -721,6 +742,7 @@ function migrateSchema(db: DbAdapter): void { db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)"); db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)"); db.exec("CREATE INDEX IF NOT EXISTS idx_verification_evidence_task ON verification_evidence(milestone_id, slice_id, task_id)"); + db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_verification_evidence_dedup ON verification_evidence(task_id, slice_id, milestone_id, command, verdict)"); db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({ ":version": 13, ":applied_at": new Date().toISOString(), @@ -756,6 +778,7 @@ let currentDb: DbAdapter | null = null; let currentPath: string | null = null; let currentPid: number = 0; let _exitHandlerRegistered = false; +let _dbOpenAttempted = false; export function getDbProvider(): ProviderName | null { loadProvider(); @@ -766,7 +789,18 @@ export function isDbAvailable(): boolean { return currentDb !== null; } +/** + * Returns true if openDatabase() has been called at least once this session. + * Used to distinguish "DB not yet initialized" from "DB genuinely unavailable" + * so that early callers (e.g. before_agent_start context injection) don't + * trigger a false degraded-mode warning. + */ +export function wasDbOpenAttempted(): boolean { + return _dbOpenAttempted; +} + export function openDatabase(path: string): boolean { + _dbOpenAttempted = true; if (currentDb && currentPath !== path) closeDatabase(); if (currentDb && currentPath === path) return true; @@ -778,8 +812,21 @@ export function openDatabase(path: string): boolean { try { initSchema(adapter, fileBacked); } catch (err) { - try { adapter.close(); } catch { /* swallow */ } - throw err; + // Corrupt freelist: DDL fails with "malformed" but VACUUM can rebuild. + // Attempt VACUUM recovery before giving up (see #2519). + if (fileBacked && err instanceof Error && err.message?.includes("malformed")) { + try { + adapter.exec("VACUUM"); + initSchema(adapter, fileBacked); + process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n"); + } catch (retryErr) { + try { adapter.close(); } catch (e) { logWarning("db", `close after VACUUM failed: ${(e as Error).message}`); } + throw retryErr; + } + } else { + try { adapter.close(); } catch (e) { logWarning("db", `close after VACUUM failed: ${(e as Error).message}`); } + throw err; + } } currentDb = adapter; @@ -788,7 +835,7 @@ export function openDatabase(path: string): boolean { if (!_exitHandlerRegistered) { _exitHandlerRegistered = true; - process.on("exit", () => { try { closeDatabase(); } catch {} }); + process.on("exit", () => { try { closeDatabase(); } catch (e) { logWarning("db", `exit handler close failed: ${(e as Error).message}`); } }); } return true; @@ -798,16 +845,14 @@ export function closeDatabase(): void { if (currentDb) { try { currentDb.exec('PRAGMA wal_checkpoint(TRUNCATE)'); - } catch { /* non-fatal — best effort before close */ } + } catch (e) { logWarning("db", `WAL checkpoint failed: ${(e as Error).message}`); } try { // Incremental vacuum to reclaim space without blocking currentDb.exec('PRAGMA incremental_vacuum(64)'); - } catch { /* non-fatal */ } + } catch (e) { logWarning("db", `incremental vacuum failed: ${(e as Error).message}`); } try { currentDb.close(); - } catch { - // swallow close errors - } + } catch (e) { logWarning("db", `database close failed: ${(e as Error).message}`); } currentDb = null; currentPath = null; currentPid = 0; @@ -819,7 +864,7 @@ export function vacuumDatabase(): void { if (!currentDb) return; try { currentDb.exec('VACUUM'); - } catch { /* non-fatal */ } + } catch (e) { logWarning("db", `VACUUM failed: ${(e as Error).message}`); } } let _txDepth = 0; @@ -985,9 +1030,21 @@ export function _resetProvider(): void { export function upsertDecision(d: Omit): void { if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); + // Use ON CONFLICT DO UPDATE instead of INSERT OR REPLACE to preserve the + // seq column. INSERT OR REPLACE deletes then reinserts, resetting seq and + // corrupting decision ordering in DECISIONS.md after reconcile replay. currentDb.prepare( - `INSERT OR REPLACE INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, made_by, superseded_by) - VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :made_by, :superseded_by)`, + `INSERT INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, made_by, superseded_by) + VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :made_by, :superseded_by) + ON CONFLICT(id) DO UPDATE SET + when_context = excluded.when_context, + scope = excluded.scope, + decision = excluded.decision, + choice = excluded.choice, + rationale = excluded.rationale, + revisable = excluded.revisable, + made_by = excluded.made_by, + superseded_by = excluded.superseded_by`, ).run({ ":id": d.id, ":when_context": d.when_context, @@ -1024,7 +1081,7 @@ export function upsertRequirement(r: Requirement): void { export function clearArtifacts(): void { if (!currentDb) return; - try { currentDb.exec("DELETE FROM artifacts"); } catch { /* cache clear is best effort */ } + try { currentDb.exec("DELETE FROM artifacts"); } catch (e) { logWarning("db", `clearArtifacts failed: ${(e as Error).message}`); } } export function insertArtifact(a: { @@ -1107,7 +1164,9 @@ export function insertMilestone(m: { ).run({ ":id": m.id, ":title": m.title ?? "", - ":status": m.status ?? "active", + // Default to "queued" — never auto-create milestones as "active" (#3380). + // Callers that need "active" must pass it explicitly. + ":status": m.status ?? "queued", ":depends_on": JSON.stringify(m.depends_on ?? []), ":created_at": new Date().toISOString(), ":vision": m.planning?.vision ?? "", @@ -1124,10 +1183,12 @@ export function insertMilestone(m: { }); } -export function upsertMilestonePlanning(milestoneId: string, planning: Partial): void { +export function upsertMilestonePlanning(milestoneId: string, planning: Partial & { title?: string; status?: string }): void { if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); currentDb.prepare( `UPDATE milestones SET + title = COALESCE(NULLIF(:title, ''), title), + status = COALESCE(NULLIF(:status, ''), status), vision = COALESCE(:vision, vision), success_criteria = COALESCE(:success_criteria, success_criteria), key_risks = COALESCE(:key_risks, key_risks), @@ -1142,6 +1203,8 @@ export function upsertMilestonePlanning(milestoneId: string, planning: Partial): void { if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); currentDb.prepare( @@ -1505,7 +1597,7 @@ export function insertVerificationEvidence(e: { }): void { if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open"); currentDb.prepare( - `INSERT INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at) + `INSERT OR IGNORE INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at) VALUES (:task_id, :slice_id, :milestone_id, :command, :exit_code, :verdict, :duration_ms, :created_at)`, ).run({ ":task_id": e.taskId, @@ -1519,6 +1611,26 @@ export function insertVerificationEvidence(e: { }); } +export interface VerificationEvidenceRow { + id: number; + task_id: string; + slice_id: string; + milestone_id: string; + command: string; + exit_code: number; + verdict: string; + duration_ms: number; + created_at: string; +} + +export function getVerificationEvidence(milestoneId: string, sliceId: string, taskId: string): VerificationEvidenceRow[] { + if (!currentDb) return []; + const rows = currentDb.prepare( + "SELECT * FROM verification_evidence WHERE milestone_id = :mid AND slice_id = :sid AND task_id = :tid ORDER BY id", + ).all({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId }); + return rows as unknown as VerificationEvidenceRow[]; +} + export interface MilestoneRow { id: string; title: string; @@ -1625,11 +1737,11 @@ export function getActiveSliceFromDb(milestoneId: string): SliceRow | null { const row = currentDb.prepare( `SELECT s.* FROM slices s WHERE s.milestone_id = :mid - AND s.status NOT IN ('complete', 'done') + AND s.status NOT IN ('complete', 'done', 'skipped') AND NOT EXISTS ( SELECT 1 FROM json_each(s.depends) AS dep WHERE dep.value NOT IN ( - SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done') + SELECT id FROM slices WHERE milestone_id = :mid AND status IN ('complete', 'done', 'skipped') ) ) ORDER BY s.sequence, s.id @@ -1738,7 +1850,7 @@ export function copyWorktreeDb(srcDbPath: string, destDbPath: string): boolean { copyFileSync(srcDbPath, destDbPath); return true; } catch (err) { - process.stderr.write(`gsd-db: failed to copy DB to worktree: ${(err as Error).message}\n`); + logError("db", "failed to copy DB to worktree", { error: (err as Error).message }); return false; } } @@ -1765,18 +1877,18 @@ export function reconcileWorktreeDb( // ATTACHing a WAL-mode DB to itself corrupts the WAL (#2823). try { if (realpathSync(mainDbPath) === realpathSync(worktreeDbPath)) return zero; - } catch { /* path resolution failed — fall through to existing checks */ } + } catch (e) { logWarning("db", `realpathSync failed: ${(e as Error).message}`); } // Sanitize path: reject any characters that could break ATTACH syntax. // ATTACH DATABASE doesn't support parameterized paths in all providers, // so we use strict allowlist validation instead. if (/['";\x00]/.test(worktreeDbPath)) { - process.stderr.write("gsd-db: worktree DB reconciliation failed: path contains unsafe characters\n"); + logError("db", "worktree DB reconciliation failed: path contains unsafe characters"); return zero; } if (!currentDb) { const opened = openDatabase(mainDbPath); if (!opened) { - process.stderr.write("gsd-db: worktree DB reconciliation failed: cannot open main DB\n"); + logError("db", "worktree DB reconciliation failed: cannot open main DB"); return zero; } } @@ -1850,20 +1962,32 @@ export function reconcileWorktreeDb( FROM wt.milestones `).run()); - // Merge slices — preserve worktree progress (status, summaries, planning) + // Merge slices — preserve worktree progress but never downgrade completed status (#2558). + // Uses INSERT OR REPLACE with a subquery that picks the best status — if the main DB + // already has a completed slice, keep that status even if the worktree copy is stale. merged.slices = countChanges(adapter.prepare(` INSERT OR REPLACE INTO slices ( milestone_id, id, title, status, risk, depends, demo, created_at, completed_at, full_summary_md, full_uat_md, goal, success_criteria, proof_level, integration_closure, observability_impact, sequence, replan_triggered_at ) - SELECT milestone_id, id, title, status, risk, depends, demo, created_at, completed_at, - full_summary_md, full_uat_md, goal, success_criteria, proof_level, - integration_closure, observability_impact, sequence, replan_triggered_at - FROM wt.slices + SELECT w.milestone_id, w.id, w.title, + CASE + WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done') + THEN m.status ELSE w.status + END, + w.risk, w.depends, w.demo, w.created_at, + CASE + WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done') + THEN m.completed_at ELSE w.completed_at + END, + w.full_summary_md, w.full_uat_md, w.goal, w.success_criteria, w.proof_level, + w.integration_closure, w.observability_impact, w.sequence, w.replan_triggered_at + FROM wt.slices w + LEFT JOIN slices m ON m.milestone_id = w.milestone_id AND m.id = w.id `).run()); - // Merge tasks — preserve execution results, status, summaries + // Merge tasks — preserve execution results, never downgrade completed status (#2558) merged.tasks = countChanges(adapter.prepare(` INSERT OR REPLACE INTO tasks ( milestone_id, slice_id, id, title, status, one_liner, narrative, @@ -1872,12 +1996,23 @@ export function reconcileWorktreeDb( description, estimate, files, verify, inputs, expected_output, observability_impact, full_plan_md, sequence ) - SELECT milestone_id, slice_id, id, title, status, one_liner, narrative, - verification_result, duration, completed_at, blocker_discovered, - deviations, known_issues, key_files, key_decisions, full_summary_md, - description, estimate, files, verify, inputs, expected_output, - observability_impact, full_plan_md, sequence - FROM wt.tasks + SELECT w.milestone_id, w.slice_id, w.id, w.title, + CASE + WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done') + THEN m.status ELSE w.status + END, + w.one_liner, w.narrative, + w.verification_result, w.duration, + CASE + WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done') + THEN m.completed_at ELSE w.completed_at + END, + w.blocker_discovered, + w.deviations, w.known_issues, w.key_files, w.key_decisions, w.full_summary_md, + w.description, w.estimate, w.files, w.verify, w.inputs, w.expected_output, + w.observability_impact, w.full_plan_md, w.sequence + FROM wt.tasks w + LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id `).run()); // Merge memories — keep worktree-learned insights @@ -1902,15 +2037,15 @@ export function reconcileWorktreeDb( adapter.exec("COMMIT"); } catch (txErr) { - try { adapter.exec("ROLLBACK"); } catch { /* best effort */ } + try { adapter.exec("ROLLBACK"); } catch (e) { logWarning("db", `rollback failed: ${(e as Error).message}`); } throw txErr; } return { ...merged, conflicts }; } finally { - try { adapter.exec("DETACH DATABASE wt"); } catch { /* best effort */ } + try { adapter.exec("DETACH DATABASE wt"); } catch (e) { logWarning("db", `detach worktree DB failed: ${(e as Error).message}`); } } } catch (err) { - process.stderr.write(`gsd-db: worktree DB reconciliation failed: ${(err as Error).message}\n`); + logError("db", "worktree DB reconciliation failed", { error: (err as Error).message }); return { ...zero, conflicts }; } } diff --git a/src/resources/extensions/gsd/guided-flow.ts b/src/resources/extensions/gsd/guided-flow.ts index c6fdb2ea9..53f76915f 100644 --- a/src/resources/extensions/gsd/guided-flow.ts +++ b/src/resources/extensions/gsd/guided-flow.ts @@ -8,14 +8,20 @@ import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@gsd/pi-coding-agent"; import { showNextAction } from "../shared/tui.js"; -import { loadFile } from "./files.js"; +import { loadFile, saveFile } from "./files.js"; import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js"; +import { parseRoadmapSlices } from "./roadmap-slices.js"; import { loadPrompt, inlineTemplate } from "./prompt-loader.js"; import { buildSkillActivationBlock } from "./auto-prompts.js"; import { deriveState } from "./state.js"; import { invalidateAllCaches } from "./cache.js"; import { startAuto } from "./auto.js"; -import { readCrashLock, clearLock, formatCrashInfo } from "./crash-recovery.js"; +import { clearLock } from "./crash-recovery.js"; +import { + assessInterruptedSession, + formatInterruptedSessionRunningMessage, + formatInterruptedSessionSummary, +} from "./interrupted-session.js"; import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js"; import { resolveExpectedArtifactPath } from "./auto.js"; import { @@ -37,7 +43,18 @@ import { showConfirm } from "../shared/tui.js"; import { debugLog } from "./debug-logger.js"; import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMilestoneIds, clearReservedMilestoneIds } from "./milestone-ids.js"; import { parkMilestone, discardMilestone } from "./milestone-actions.js"; -import { resolveModelWithFallbacksForUnit } from "./preferences-models.js"; +import { selectAndApplyModel } from "./auto-model-selection.js"; +import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js"; +import { + getWorkflowTransportSupportError, + getRequiredWorkflowToolsForGuidedUnit, + supportsStructuredQuestions, +} from "./workflow-mcp.js"; +import { + runPreparation, + formatCodebaseBrief, + formatPriorContextBrief, +} from "./preparation.js"; // ─── Re-exports (preserve public API for existing importers) ──────────────── export { @@ -51,6 +68,7 @@ export { buildExistingMilestonesContext, } from "./guided-flow-queue.js"; import { getErrorMessage } from "./error-utils.js"; +import { logWarning } from "./workflow-logger.js"; // ─── ID Generation with Reservation ───────────────────────────────────────── @@ -75,25 +93,73 @@ function buildDocsCommitInstruction(_message: string): string { // ─── Auto-start after discuss ───────────────────────────────────────────────── -/** Stashed context + flag for auto-starting after discuss phase completes */ -let pendingAutoStart: { +/** Pending auto-start context, keyed by basePath for session isolation (#2985). */ +interface PendingAutoStartEntry { ctx: ExtensionCommandContext; pi: ExtensionAPI; basePath: string; milestoneId: string; // the milestone being discussed step?: boolean; // preserve step mode through discuss → auto transition -} | null = null; + createdAt: number; // timestamp for staleness detection (#3274) +} -/** Returns the milestoneId being discussed, or null if no discussion is active */ -export function getDiscussionMilestoneId(): string | null { - return pendingAutoStart?.milestoneId ?? null; +const pendingAutoStartMap = new Map(); + +/** + * Backward-compat bridge: returns a mutable reference to the entry matching + * basePath, or the sole entry when only one session exists. + * Internal use only — external code should use the Map directly. + */ +function _getPendingAutoStart(basePath?: string): PendingAutoStartEntry | null { + if (basePath) return pendingAutoStartMap.get(basePath) ?? null; + if (pendingAutoStartMap.size === 1) return pendingAutoStartMap.values().next().value!; + return null; +} + +/** + * Store pending auto-start state for a project. + * Exported for testing (#2985). + */ +export function setPendingAutoStart(basePath: string, entry: { basePath: string; milestoneId: string; ctx?: ExtensionCommandContext; pi?: ExtensionAPI; step?: boolean; createdAt?: number }): void { + pendingAutoStartMap.set(basePath, { createdAt: Date.now(), ...entry } as PendingAutoStartEntry); +} + +/** + * Clear pending auto-start state. + * If basePath is given, clears only that project. Otherwise clears all. + * Exported for testing (#2985). + */ +export function clearPendingAutoStart(basePath?: string): void { + if (basePath) { + pendingAutoStartMap.delete(basePath); + } else { + pendingAutoStartMap.clear(); + } +} + +/** + * Returns the milestoneId being discussed for the given project. + * When basePath is omitted and only one session is active, returns that + * session's milestoneId for backward compatibility. Returns null when + * multiple sessions exist and basePath is not specified (#2985 Bug 4). + */ +export function getDiscussionMilestoneId(basePath?: string): string | null { + if (basePath) { + return pendingAutoStartMap.get(basePath)?.milestoneId ?? null; + } + // Backward compat: return the sole entry's milestoneId, or null if ambiguous + if (pendingAutoStartMap.size === 1) { + return pendingAutoStartMap.values().next().value!.milestoneId; + } + return null; } /** Called from agent_end to check if auto-mode should start after discuss */ export function checkAutoStartAfterDiscuss(): boolean { - if (!pendingAutoStart) return false; + const entry = _getPendingAutoStart(); + if (!entry) return false; - const { ctx, pi, basePath, milestoneId, step } = pendingAutoStart; + const { ctx, pi, basePath, milestoneId, step } = entry; // Gate 1: Primary milestone must have CONTEXT.md or ROADMAP.md // The "discuss" path creates CONTEXT.md; the "plan" path creates ROADMAP.md. @@ -113,12 +179,13 @@ export function checkAutoStartAfterDiscuss(): boolean { // Parse PROJECT.md for milestone sequence, warn if any are missing context. // Don't block — milestones can be intentionally queued without context. const projectFile = resolveGsdRootFile(basePath, "PROJECT"); + let projectIds: string[] = []; if (projectFile) { try { const projectContent = readFileSync(projectFile, "utf-8"); - const milestoneIds = parseMilestoneSequenceFromProject(projectContent); - if (milestoneIds.length > 1) { - const missing = milestoneIds.filter(id => { + projectIds = parseMilestoneSequenceFromProject(projectContent); + if (projectIds.length > 1) { + const missing = projectIds.filter(id => { const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT"); const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT"); const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id)); @@ -132,13 +199,13 @@ export function checkAutoStartAfterDiscuss(): boolean { ); } } - } catch { /* non-fatal — PROJECT.md parsing failure shouldn't block auto-start */ } + } catch (e) { logWarning("guided", `PROJECT.md parsing failed: ${(e as Error).message}`); } } // Gate 4: Discussion manifest process verification (multi-milestone only) // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision. - // If the manifest exists but gates_completed < total, the LLM hasn't finished - // presenting all readiness gates to the user — block auto-start. + // When it exists, validate it before auto-starting. Project history alone is + // not a reliable signal for the current discussion mode. const manifestPath = join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"); if (existsSync(manifestPath)) { try { @@ -152,9 +219,7 @@ export function checkAutoStartAfterDiscuss(): boolean { } // Cross-check manifest milestones against PROJECT.md if available - if (projectFile) { - const projectContent = readFileSync(projectFile, "utf-8"); - const projectIds = parseMilestoneSequenceFromProject(projectContent); + if (projectIds.length > 0) { const manifestIds = Object.keys(manifest.milestones ?? {}); const untracked = projectIds.filter(id => !manifestIds.includes(id)); if (untracked.length > 0) { @@ -164,7 +229,7 @@ export function checkAutoStartAfterDiscuss(): boolean { ); } } - } catch { /* malformed manifest — warn but don't block */ } + } catch (e) { logWarning("guided", `discussion manifest verification failed: ${(e as Error).message}`); } } // Draft promotion cleanup: if a CONTEXT-DRAFT.md exists alongside the new @@ -172,16 +237,16 @@ export function checkAutoStartAfterDiscuss(): boolean { try { const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT"); if (draftFile) unlinkSync(draftFile); - } catch { /* non-fatal — stale draft doesn't break anything, CONTEXT.md wins */ } + } catch (e) { logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`); } // Cleanup: remove discussion manifest after auto-start (only needed during discussion) - try { unlinkSync(manifestPath); } catch { /* may not exist for single-milestone */ } + try { unlinkSync(manifestPath); } catch (e) { logWarning("guided", `manifest unlink failed: ${(e as Error).message}`); } - pendingAutoStart = null; + pendingAutoStartMap.delete(basePath); ctx.ui.notify(`Milestone ${milestoneId} ready.`, "info"); startAuto(ctx, pi, basePath, false, { step }).catch((err) => { ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error"); - if (process.env.GSD_DEBUG) console.error('[gsd] auto start error:', err); + logWarning("guided", `auto start error: ${getErrorMessage(err)}`); debugLog("auto-start-failed", { error: getErrorMessage(err) }); }); return true; @@ -223,25 +288,65 @@ async function dispatchWorkflow( ctx?: ExtensionContext, unitType?: string, ): Promise { - // Apply model preference for this unit type (if configured) + // Route through the dynamic routing pipeline (complexity classification, + // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958). if (ctx && unitType) { - const modelConfig = resolveModelWithFallbacksForUnit(unitType); - if (modelConfig) { - const availableModels = ctx.modelRegistry.getAvailable(); - const modelsToTry = [modelConfig.primary, ...modelConfig.fallbacks]; - - for (const modelId of modelsToTry) { - // Resolve model from available models (same logic as auto-model-selection) - const model = resolveAvailableModel(modelId, availableModels, ctx.model?.provider); - if (!model) continue; - - const ok = await pi.setModel(model, { persist: false }); - if (ok) { - debugLog("guided-flow-model-applied", { unitType, model: `${model.provider}/${model.id}` }); - break; - } - } + const prefs = loadEffectiveGSDPreferences()?.preferences; + const result = await selectAndApplyModel( + ctx, pi, unitType, /* unitId */ "", /* basePath */ process.cwd(), + prefs, /* verbose */ false, /* autoModeStartModel */ null, + /* retryContext */ undefined, /* isAutoMode */ false, + ); + if (result.appliedModel) { + debugLog("guided-flow-model-applied", { + unitType, + model: `${result.appliedModel.provider}/${result.appliedModel.id}`, + routing: result.routing, + }); } + + const compatibilityError = getWorkflowTransportSupportError( + result.appliedModel?.provider ?? ctx.model?.provider, + getRequiredWorkflowToolsForGuidedUnit(unitType), + { + projectRoot: process.cwd(), + surface: "guided flow", + unitType, + authMode: result.appliedModel?.provider + ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider) + : ctx.model?.provider + ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider) + : undefined, + baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl, + }, + ); + if (compatibilityError) { + ctx.ui.notify(compatibilityError, "error"); + return; + } + } + + // Scope tools for discuss flows (#2949). + // Providers with grammar-based constrained decoding (xAI/Grok) return + // "Grammar is too complex" when the combined tool schema is too large. + // Discuss flows only need a small subset of GSD tools — strip the heavy + // planning/execution/completion tools to keep the grammar within limits. + let savedTools: string[] | null = null; + if (unitType?.startsWith("discuss-")) { + const currentTools = pi.getActiveTools(); + savedTools = currentTools; + // Keep all non-GSD tools (builtins, other extensions) and only the + // GSD tools on the discuss allowlist. + const scopedTools = currentTools.filter( + (t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t), + ); + pi.setActiveTools(scopedTools); + debugLog("discuss-tool-scoping", { + unitType, + before: currentTools.length, + after: scopedTools.length, + removed: currentTools.length - scopedTools.length, + }); } const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md"); @@ -255,6 +360,27 @@ async function dispatchWorkflow( }, { triggerTurn: true }, ); + + // Restore full tool set after the message is queued. The LLM turn has + // already captured the scoped set — restoring prevents the narrowed + // tools from leaking into subsequent dispatches (#3628). + if (savedTools) { + pi.setActiveTools(savedTools); + } +} + +function getStructuredQuestionsAvailability( + pi: ExtensionAPI, + ctx: ExtensionContext | undefined, +): "true" | "false" { + if (!ctx) return "false"; + + const provider = ctx.model?.provider; + const authMode = provider ? ctx.modelRegistry.getProviderAuthMode(provider) : undefined; + return supportsStructuredQuestions(pi.getActiveTools(), { + authMode, + baseUrl: ctx.model?.baseUrl, + }) ? "true" : "false"; } /** @@ -300,8 +426,9 @@ function resolveAvailableModel( * Build the discuss-and-plan prompt for a new milestone. * Used by all three "new milestone" paths (first ever, no active, all complete). */ -function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string): string { +function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string, pi: ExtensionAPI, ctx: ExtensionCommandContext, preparationContext?: string): string { const milestoneRel = `.gsd/milestones/${nextId}`; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); const inlinedTemplates = [ inlineTemplate("project", "Project"), inlineTemplate("requirements", "Requirements"), @@ -312,6 +439,8 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string) return loadPrompt("discuss", { milestoneId: nextId, preamble, + preparationContext: preparationContext ?? "", + structuredQuestionsAvailable, contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`, roadmapPath: `${milestoneRel}/${nextId}-ROADMAP.md`, inlinedTemplates, @@ -344,6 +473,59 @@ function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePa }); } +/** + * Run preparation phase if enabled, then build the discuss prompt. + * Preparation analyzes the codebase and prior context, injecting the results + * as supplementary context into the standard discuss template. The discuss + * template drives the conversation (asks "What's the vision?" first), while + * the preparation briefs give the agent grounding in the existing codebase. + * + * @param ctx - Extension command context with UI for progress notifications + * @param nextId - The milestone ID being discussed + * @param preamble - Preamble text for the discuss prompt + * @param basePath - Root directory of the project + * @returns The discuss prompt string + */ +async function prepareAndBuildDiscussPrompt( + ctx: ExtensionCommandContext, + pi: ExtensionAPI, + nextId: string, + preamble: string, + basePath: string, +): Promise { + const prefs = loadEffectiveGSDPreferences()?.preferences ?? {}; + + // Run preparation if enabled (default: true) — results are injected as + // supplementary context into the standard discuss prompt, NOT as a + // replacement template. The discuss prompt always leads with "What's the + // vision?" so the user defines the scope, not the codebase analysis. + let preparationContext = ""; + if (prefs.discuss_preparation !== false) { + try { + const prepResult = await runPreparation(basePath, ctx.ui, { + discuss_preparation: prefs.discuss_preparation, + discuss_web_research: prefs.discuss_web_research, + discuss_depth: prefs.discuss_depth, + }); + + if (prepResult.enabled) { + const codebaseBrief = prepResult.codebaseBrief || formatCodebaseBrief(prepResult.codebase); + const priorContextBrief = prepResult.priorContextBrief || formatPriorContextBrief(prepResult.priorContext); + const parts: string[] = []; + if (codebaseBrief) parts.push(`### Codebase Brief\n\n${codebaseBrief}`); + if (priorContextBrief) parts.push(`### Prior Context Brief\n\n${priorContextBrief}`); + if (parts.length > 0) { + preparationContext = `\n\n## Preparation Context\n\nThe system analyzed the codebase before this discussion. Use these findings as background context — they describe what already exists, NOT what the user wants to build. Always ask the user what they want to build first.\n\n${parts.join("\n\n")}`; + } + } + } catch (err) { + logWarning("guided", `preparation failed, proceeding without context: ${(err as Error).message}`); + } + } + + return buildDiscussPrompt(nextId, preamble, basePath, pi, ctx, preparationContext); +} + /** * Bootstrap a .gsd/ project from scratch for headless use. * Ensures git repo, .gsd/ structure, gitignore, and preferences all exist. @@ -393,7 +575,7 @@ export async function showHeadlessMilestoneCreation( const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath); // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss) - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId }; + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() }); // Dispatch — headless milestone creation is a planning activity await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone"); @@ -413,7 +595,7 @@ async function buildDiscussSlicePrompt( sid: string, sTitle: string, base: string, - options?: { rediscuss?: boolean }, + options?: { rediscuss?: boolean; structuredQuestionsAvailable?: string }, ): Promise { const inlined: string[] = []; @@ -493,6 +675,7 @@ async function buildDiscussSlicePrompt( contextPath: sliceContextPath, projectRoot: base, inlinedTemplates, + structuredQuestionsAvailable: options?.structuredQuestionsAvailable ?? "false", commitInstruction: buildDocsCommitInstruction(`docs(${mid}/${sid}): slice context from discuss`), }); } @@ -518,6 +701,16 @@ export async function showDiscuss( const state = await deriveState(basePath); + // Rebuild STATE.md from derived state before any dispatch (#3475). + // Without this, guided prompts read a stale STATE.md cache and the + // agent bootstraps from the wrong milestone. + try { + const { buildStateMarkdown } = await import("./doctor.js"); + await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state)); + } catch (err) { + logWarning("guided", `STATE.md rebuild failed: ${(err as Error).message}`); + } + // No active milestone (or corrupted milestone with undefined id) — // check for pending milestones to discuss instead if (!state.activeMilestone?.id) { @@ -565,30 +758,32 @@ export async function showDiscuss( if (choice === "discuss_draft") { const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); const basePrompt = loadPrompt("guided-discuss-milestone", { milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`), + fastPathInstruction: "", }); const seed = draftContent ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}` : basePrompt; - pendingAutoStart = { ctx, pi, basePath, milestoneId: mid, step: false }; + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() }); await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone"); } else if (choice === "discuss_fresh") { const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; - pendingAutoStart = { ctx, pi, basePath, milestoneId: mid, step: false }; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() }); await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", { milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`), + fastPathInstruction: "", }), "gsd-discuss", ctx, "discuss-milestone"); } else if (choice === "skip_milestone") { const milestoneIds = findMilestoneIds(basePath); const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids; const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds); - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: false }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone"); + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone"); } return; } @@ -617,9 +812,21 @@ export async function showDiscuss( } else { normSlices = []; } + // DB is open but returned zero slices despite a roadmap existing — + // the DB may be empty due to WAL loss or truncation (see #2815, #2892). + // Fall back to roadmap parsing to prevent false "all complete" exit. + if (normSlices.length === 0 && roadmapContent) { + normSlices = parseRoadmapSlices(roadmapContent).map(s => ({ id: s.id, done: s.done, title: s.title })); + } const pendingSlices = normSlices.filter(s => !s.done); if (pendingSlices.length === 0) { + // All slices complete — but queued milestones may still need discussion (#3150) + const pendingMilestones = state.registry.filter(m => m.status === "pending"); + if (pendingMilestones.length > 0) { + await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones); + return; + } ctx.ui.notify("All slices are complete — nothing to discuss.", "info"); return; } @@ -636,9 +843,14 @@ export async function showDiscuss( discussedMap.set(s.id, !!contextFile); } - // If all pending slices are discussed, notify and exit instead of looping + // If all pending slices are discussed, check for queued milestones before exiting (#3150) const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id)); if (allDiscussed) { + const pendingMilestones = state.registry.filter(m => m.status === "pending"); + if (pendingMilestones.length > 0) { + await showDiscussQueuedMilestone(ctx, pi, basePath, pendingMilestones); + return; + } const lockData = readSessionLockData(basePath); const remoteAutoRunning = lockData && lockData.pid !== process.pid && isSessionLockProcessAlive(lockData); const nextStep = remoteAutoRunning @@ -717,7 +929,8 @@ export async function showDiscuss( if (confirm !== "rediscuss") continue; } - const prompt = await buildDiscussSlicePrompt(mid, chosen.id, chosen.title, basePath, { rediscuss: isRediscuss }); + const sqAvail = getStructuredQuestionsAvailability(pi, ctx); + const prompt = await buildDiscussSlicePrompt(mid, chosen.id, chosen.title, basePath, { rediscuss: isRediscuss, structuredQuestionsAvailable: sqAvail }); await dispatchWorkflow(pi, prompt, "gsd-discuss", ctx, "discuss-slice"); // Wait for the discuss session to finish, then loop back to the picker @@ -767,7 +980,36 @@ async function showDiscussQueuedMilestone( const chosen = pendingMilestones.find(m => m.id === choice); if (!chosen) return; - await dispatchDiscussForMilestone(ctx, pi, basePath, chosen.id, chosen.title); + const hasDraft = !!resolveMilestoneFile(basePath, chosen.id, "CONTEXT-DRAFT"); + let fastPath = hasDraft; + + if (!hasDraft) { + const mode = await showNextAction(ctx, { + title: `Discuss ${chosen.id}`, + summary: [ + "Choose how to start the discussion.", + "Fast path skips generic scouting — use it when you already know the scope.", + ], + actions: [ + { + id: "full", + label: "Full discussion", + description: "Scout the codebase, ask open-ended questions, explore deeply", + recommended: true, + }, + { + id: "fast", + label: "I have the scope — fast path", + description: "Treat your first message as authoritative seed context; skip scouting", + }, + ], + notYetMessage: "Run /gsd discuss when ready.", + }); + if (mode === "not_yet") return; + fastPath = mode === "fast"; + } + + await dispatchDiscussForMilestone(ctx, pi, basePath, chosen.id, chosen.title, { fastPath }); } /** @@ -781,17 +1023,30 @@ async function dispatchDiscussForMilestone( basePath: string, mid: string, milestoneTitle: string, + opts: { fastPath?: boolean } = {}, ): Promise { const draftFile = resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"); const draftContent = draftFile ? await loadFile(draftFile) : null; + const hasSeed = !!(draftContent || opts.fastPath); + const fastPathInstruction = hasSeed + ? [ + "> **Fast path active — scope provided.**", + "> Do NOT perform a generic codebase scouting pass.", + "> Do at most 2 targeted reads to check for obvious conflicts with existing work.", + "> Treat the seed context or the operator's first message as authoritative.", + "> Move directly to the depth summary and write step.", + "> Ask only questions where the answer would materially change scope.", + ].join("\n") + : ""; const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); const basePrompt = loadPrompt("guided-discuss-milestone", { milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`), + fastPathInstruction, }); const prompt = draftContent ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}` @@ -834,8 +1089,8 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea ctx.ui.notify(`Self-heal: cleared ${cleared} stale runtime record(s) from a previous session.`, "info"); } return { cleared }; - } catch { - // Non-fatal — self-heal should never block the wizard + } catch (e) { + logWarning("guided", `self-heal stale runtime records failed: ${(e as Error).message}`); return { cleared: 0 }; } } @@ -932,8 +1187,8 @@ async function handleMilestoneActions( const milestoneIds = findMilestoneIds(basePath); const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids; const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds); - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -974,7 +1229,15 @@ export async function showSmartEntry( } // ── Detection preamble — run before any bootstrap ──────────────────── - if (!existsSync(gsdRoot(basePath))) { + // Check bootstrap completeness, not just .gsd/ directory existence. + // A zombie .gsd/ state (symlink exists but missing PREFERENCES.md and + // milestones/) must trigger the init wizard, not skip it (#2942). + const gsdPath = gsdRoot(basePath); + const hasBootstrapArtifacts = existsSync(gsdPath) + && (existsSync(join(gsdPath, "PREFERENCES.md")) + || existsSync(join(gsdPath, "milestones"))); + + if (!hasBootstrapArtifacts) { const detection = detectProjectState(basePath); // v1 .planning/ detected — offer migration before anything else @@ -989,7 +1252,7 @@ export async function showSmartEntry( // "fresh" — fall through to init wizard } - // No .gsd/ — run the project init wizard + // No .gsd/ or zombie .gsd/ — run the project init wizard const result = await showProjectInit(ctx, pi, basePath, detection); if (!result.completed) return; // User cancelled @@ -1013,46 +1276,77 @@ export async function showSmartEntry( // ── Self-heal stale runtime records from crashed auto-mode sessions ── selfHealRuntimeRecords(basePath, ctx); - // Check for crash from previous auto-mode session. - // Skip if the lock was written by the current process — acquireSessionLock() - // writes to the same file, so we'd always false-positive (#1398). - const crashLock = readCrashLock(basePath); - if (crashLock && crashLock.pid !== process.pid) { + const interrupted = await assessInterruptedSession(basePath); + if (interrupted.classification === "running") { + ctx.ui.notify(formatInterruptedSessionRunningMessage(interrupted), "error"); + return; + } + + if (interrupted.classification === "stale") { clearLock(basePath); - - // Bootstrap crash with zero completed units = no work was lost. - // Auto-discard instead of prompting the user — this commonly happens - // when the user exits during init wizard or discuss phase before any - // real auto-mode work begins. - const isBootstrapCrash = crashLock.unitType === "starting" - && crashLock.unitId === "bootstrap"; - - if (!isBootstrapCrash) { - const resume = await showNextAction(ctx, { - title: "GSD — Interrupted Session Detected", - summary: [formatCrashInfo(crashLock)], - actions: [ - { id: "resume", label: "Resume with /gsd auto", description: "Pick up where it left off", recommended: true }, - { id: "continue", label: "Continue manually", description: "Open the wizard as normal" }, - ], - }); - if (resume === "resume") { - await startAuto(ctx, pi, basePath, false); - return; + if (interrupted.pausedSession) { + try { + unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json")); + } catch (e) { + logWarning("guided", `stale pause file cleanup failed: ${(e as Error).message}`, { file: "guided-flow.ts" }); } } + } else if (interrupted.classification === "recoverable") { + if (interrupted.lock) clearLock(basePath); + const resumeLabel = interrupted.pausedSession?.stepMode + ? "Resume with /gsd next" + : "Resume with /gsd auto"; + const resume = await showNextAction(ctx, { + title: "GSD — Interrupted Session Detected", + summary: formatInterruptedSessionSummary(interrupted), + actions: [ + { id: "resume", label: resumeLabel, description: "Pick up where it left off", recommended: true }, + { id: "continue", label: "Continue manually", description: "Open the wizard as normal" }, + ], + }); + if (resume === "resume") { + await startAuto(ctx, pi, basePath, false, { + interrupted, + step: interrupted.pausedSession?.stepMode ?? false, + }); + return; + } } + // Always derive from the project root — the assessment may have derived + // state from a worktree path that was cleaned up in the stale branch above. const state = await deriveState(basePath); + // Rebuild STATE.md from derived state before any dispatch (#3475). + try { + const { buildStateMarkdown } = await import("./doctor.js"); + await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state)); + } catch (err) { + logWarning("guided", `STATE.md rebuild failed: ${(err as Error).message}`); + } + if (!state.activeMilestone?.id) { // Guard: if a discuss session is already in flight, don't re-inject the prompt. // Both /gsd and /gsd auto reach this branch when no milestone exists yet. - // Without this guard, every subsequent /gsd call overwrites pendingAutoStart + // Without this guard, every subsequent /gsd call overwrites the pending auto-start // and fires another dispatchWorkflow, resetting the conversation mid-interview. - if (pendingAutoStart) { - ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info"); - return; + if (pendingAutoStartMap.has(basePath)) { + // #3274: If /clear interrupted the discussion, the pending entry is stale. + // Detect staleness: no manifest, no CONTEXT.md, AND entry is older than + // 30s (avoids race between .set() and LLM writing first artifact). + const entry = pendingAutoStartMap.get(basePath)!; + const ageMs = Date.now() - (entry.createdAt || 0); + const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json")); + const milestoneHasContext = existsSync( + join(gsdRoot(basePath), "milestones", entry.milestoneId, `${entry.milestoneId}-CONTEXT.md`), + ); + if (!manifestExists && !milestoneHasContext && ageMs > 30_000) { + // Stale entry from an interrupted discussion — clear and continue + pendingAutoStartMap.delete(basePath); + } else { + ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info"); + return; + } } const milestoneIds = findMilestoneIds(basePath); @@ -1073,7 +1367,7 @@ export async function showSmartEntry( ); return; } - } catch { /* directory exists but unreadable — fall through to normal flow */ } + } catch (e) { logWarning("guided", `directory read failed: ${(e as Error).message}`); } } } @@ -1083,8 +1377,8 @@ export async function showSmartEntry( if (isFirst) { // First ever — skip wizard, just ask directly - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -1104,8 +1398,8 @@ export async function showSmartEntry( }); if (choice === "new_milestone") { - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -1143,8 +1437,8 @@ export async function showSmartEntry( const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids; const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds); - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -1186,30 +1480,32 @@ export async function showSmartEntry( if (choice === "discuss_draft") { const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); const basePrompt = loadPrompt("guided-discuss-milestone", { milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`), + fastPathInstruction: "", }); const seed = draftContent ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}` : basePrompt; - pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode }; + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() }); await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone"); } else if (choice === "discuss_fresh") { const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; - pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode }; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() }); await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", { milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`), + fastPathInstruction: "", }), "gsd-discuss", ctx, "discuss-milestone"); } else if (choice === "skip_milestone") { const milestoneIds = findMilestoneIds(basePath); const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids; const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds); - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -1222,7 +1518,19 @@ export async function showSmartEntry( const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP"); const hasRoadmap = !!(roadmapFile && await loadFile(roadmapFile)); - if (!hasRoadmap) { + // A roadmap file with zero parseable slices (placeholder text) should be + // treated the same as no roadmap — offer "Create roadmap" instead of "Go auto" + // which would immediately get stuck in blocked state (#3441). + let roadmapHasSlices = false; + if (hasRoadmap) { + const roadmapContent = await loadFile(roadmapFile!); + if (roadmapContent) { + const parsed = parseRoadmapSlices(roadmapContent); + roadmapHasSlices = parsed.length > 0; + } + } + + if (!hasRoadmap || !roadmapHasSlices) { // No roadmap → discuss or plan const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT"); const hasContext = !!(contextFile && await loadFile(contextFile)); @@ -1261,7 +1569,7 @@ export async function showSmartEntry( }); if (choice === "plan") { - pendingAutoStart = { ctx, pi, basePath, milestoneId, step: stepMode }; + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() }); const planMilestoneTemplates = [ inlineTemplate("roadmap", "Roadmap"), inlineTemplate("plan", "Slice Plan"), @@ -1283,17 +1591,18 @@ export async function showSmartEntry( }), "gsd-run", ctx, "plan-milestone"); } else if (choice === "discuss") { const discussMilestoneTemplates = inlineTemplate("context", "Context"); - const structuredQuestionsAvailable = pi.getActiveTools().includes("ask_user_questions") ? "true" : "false"; + const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx); await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", { milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable, commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`), + fastPathInstruction: "", }), "gsd-run", ctx, "discuss-milestone"); } else if (choice === "skip_milestone") { const milestoneIds = findMilestoneIds(basePath); const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids; const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds); - pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId, step: stepMode }; - await dispatchWorkflow(pi, buildDiscussPrompt(nextId, + pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() }); + await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath ), "gsd-run", ctx, "discuss-milestone"); @@ -1422,7 +1731,8 @@ export async function showSmartEntry( }), }), "gsd-run", ctx, "plan-slice"); } else if (choice === "discuss") { - await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext }), "gsd-run", ctx, "discuss-slice"); + const sqAvail = getStructuredQuestionsAvailability(pi, ctx); + await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext, structuredQuestionsAvailable: sqAvail }), "gsd-run", ctx, "discuss-slice"); } else if (choice === "research") { const researchTemplates = inlineTemplate("research", "Research"); await dispatchWorkflow(pi, loadPrompt("guided-research-slice", { diff --git a/src/resources/extensions/gsd/health-widget-core.ts b/src/resources/extensions/gsd/health-widget-core.ts index cc50f2099..783baf1da 100644 --- a/src/resources/extensions/gsd/health-widget-core.ts +++ b/src/resources/extensions/gsd/health-widget-core.ts @@ -18,6 +18,10 @@ export interface HealthWidgetData { providerIssue: string | null; environmentErrorCount: number; environmentWarningCount: number; + /** Unix epoch (seconds) of the last commit, or null if unavailable. */ + lastCommitEpoch: number | null; + /** Subject line of the last commit, or null if unavailable. */ + lastCommitMessage: string | null; lastRefreshed: number; } @@ -32,6 +36,29 @@ function formatCost(n: number): string { return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`; } +/** + * Format a Unix epoch (seconds) as a human-readable relative time string. + * Returns "just now" for <1m, "Xm ago" for <1h, "Xh ago" for <24h, "Xd ago" otherwise. + */ +export function formatRelativeTime(epochSeconds: number): string { + const diffSeconds = Math.floor(Date.now() / 1000) - epochSeconds; + if (diffSeconds < 60) return "just now"; + const minutes = Math.floor(diffSeconds / 60); + if (minutes < 60) return `${minutes}m ago`; + const hours = Math.floor(minutes / 60); + if (hours < 24) return `${hours}h ago`; + const days = Math.floor(hours / 24); + return `${days}d ago`; +} + +/** + * Truncate a commit message to fit the widget, appending "…" if needed. + */ +function truncateMessage(msg: string, maxLen: number): string { + if (msg.length <= maxLen) return msg; + return msg.slice(0, maxLen - 1) + "…"; +} + /** * Build compact health lines for the widget. * Returns a string array suitable for setWidget(). @@ -73,5 +100,12 @@ export function buildHealthLines(data: HealthWidgetData): string[] { parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`); } + // Always-on last commit display — shows relative time + truncated message + if (data.lastCommitEpoch !== null && data.lastCommitEpoch > 0) { + const relTime = formatRelativeTime(data.lastCommitEpoch); + const msg = data.lastCommitMessage ? ` — ${truncateMessage(data.lastCommitMessage, 50)}` : ""; + parts.push(`Last commit: ${relTime}${msg}`); + } + return [` ${parts.join(" │ ")}`]; } diff --git a/src/resources/extensions/gsd/health-widget.ts b/src/resources/extensions/gsd/health-widget.ts index fa63e6677..f3f2d262a 100644 --- a/src/resources/extensions/gsd/health-widget.ts +++ b/src/resources/extensions/gsd/health-widget.ts @@ -13,6 +13,7 @@ import type { GSDState } from "./types.js"; import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js"; import { runEnvironmentChecks } from "./doctor-environment.js"; import { loadEffectiveGSDPreferences } from "./preferences.js"; +import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js"; import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js"; import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js"; import { projectRoot } from "./commands/context.js"; @@ -31,6 +32,8 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData { let providerIssue: string | null = null; let environmentErrorCount = 0; let environmentWarningCount = 0; + let lastCommitEpoch: number | null = null; + let lastCommitMessage: string | null = null; const projectState = detectHealthWidgetProjectState(basePath); @@ -58,6 +61,18 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData { } } catch { /* non-fatal */ } + // ── Last commit info ── + try { + if (nativeIsRepo(basePath)) { + const branch = nativeGetCurrentBranch(basePath); + const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD"); + if (epoch > 0) { + lastCommitEpoch = epoch; + lastCommitMessage = nativeCommitSubject(basePath, branch || "HEAD") || null; + } + } + } catch { /* non-fatal */ } + return { projectState, budgetCeiling, @@ -65,6 +80,8 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData { providerIssue, environmentErrorCount, environmentWarningCount, + lastCommitEpoch, + lastCommitMessage, lastRefreshed: Date.now(), }; } diff --git a/src/resources/extensions/gsd/index.ts b/src/resources/extensions/gsd/index.ts index 13e6dc97c..d61786f6f 100644 --- a/src/resources/extensions/gsd/index.ts +++ b/src/resources/extensions/gsd/index.ts @@ -1,10 +1,18 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent"; export { + isDepthConfirmationAnswer, isDepthVerified, + isGateQuestionId, isQueuePhaseActive, setQueuePhaseActive, shouldBlockContextWrite, + shouldBlockPendingGate, + shouldBlockPendingGateBash, + shouldBlockQueueExecution, + setPendingGate, + clearPendingGate, + getPendingGate, } from "./bootstrap/write-gate.js"; export default async function registerExtension(pi: ExtensionAPI) { diff --git a/src/resources/extensions/gsd/init-wizard.ts b/src/resources/extensions/gsd/init-wizard.ts index f1a077dd8..b7251471e 100644 --- a/src/resources/extensions/gsd/init-wizard.ts +++ b/src/resources/extensions/gsd/init-wizard.ts @@ -16,6 +16,7 @@ import { gsdRoot } from "./paths.js"; import { assertSafeDirectory } from "./validate-directory.js"; import type { ProjectDetection, ProjectSignals } from "./detection.js"; import { runSkillInstallStep } from "./skill-catalog.js"; +import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js"; // ─── Types ────────────────────────────────────────────────────────────────────── @@ -234,10 +235,50 @@ export async function showProjectInit( // ── Step 9: Bootstrap .gsd/ ──────────────────────────────────────────────── bootstrapGsdDirectory(basePath, prefs, signals); + // Initialize SQLite database so GSD starts in full-capability mode (#3880). + // Without this, isDbAvailable() returns false and GSD enters degraded + // markdown-only mode until a tool handler happens to call ensureDbOpen(). + try { + const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js"); + await ensureDbOpen(basePath); + } catch { + // Non-fatal — DB creation failure should not block project init + } + // Ensure .gitignore ensureGitignore(basePath); untrackRuntimeFiles(basePath); + // Auto-generate codebase map for instant agent orientation + try { + const result = generateCodebaseMap(basePath); + if (result.fileCount > 0) { + writeCodebaseMap(basePath, result.content); + ctx.ui.notify(`Codebase map generated: ${result.fileCount} files`, "info"); + } + } catch { + // Non-fatal — codebase map generation failure should never block project init + } + + // Write initial STATE.md so it exists before the first /gsd invocation. + // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(), + // which would otherwise generate STATE.md at guided-flow.ts:1358. + try { + const { deriveState } = await import("./state.js"); + const { buildStateMarkdown } = await import("./doctor.js"); + const { saveFile } = await import("./files.js"); + const { resolveGsdRootFile } = await import("./paths.js"); + const state = await deriveState(basePath); + await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state)); + } catch { + // Non-fatal — STATE.md will be regenerated on next /gsd invocation + } + + { + const { prepareWorkflowMcpForProject } = await import("./workflow-mcp-auto-prep.js"); + prepareWorkflowMcpForProject(ctx, basePath); + } + ctx.ui.notify("GSD initialized. Starting your first milestone...", "info"); return { completed: true, bootstrapped: true }; @@ -421,6 +462,7 @@ function bootstrapGsdDirectory( const gsd = gsdRoot(basePath); mkdirSync(join(gsd, "milestones"), { recursive: true }); + mkdirSync(join(gsd, "runtime"), { recursive: true }); // Write PREFERENCES.md from wizard answers const preferencesContent = buildPreferencesFile(prefs); diff --git a/src/resources/extensions/gsd/interrupted-session.ts b/src/resources/extensions/gsd/interrupted-session.ts new file mode 100644 index 000000000..8c6274a05 --- /dev/null +++ b/src/resources/extensions/gsd/interrupted-session.ts @@ -0,0 +1,224 @@ +import { existsSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +import { verifyExpectedArtifact } from "./auto-recovery.js"; +import { + formatCrashInfo, + isLockProcessAlive, + readCrashLock, + type LockData, +} from "./crash-recovery.js"; +import { gsdRoot } from "./paths.js"; +import { + synthesizeCrashRecovery, + type RecoveryBriefing, +} from "./session-forensics.js"; +import { deriveState } from "./state.js"; +import type { GSDState } from "./types.js"; + +export type InterruptedSessionClassification = + | "none" + | "running" + | "recoverable" + | "stale"; + +export interface PausedSessionMetadata { + milestoneId?: string; + worktreePath?: string | null; + originalBasePath?: string; + stepMode?: boolean; + pausedAt?: string; + sessionFile?: string | null; + unitType?: string; + unitId?: string; + activeEngineId?: string; + activeRunDir?: string | null; + autoStartTime?: number; +} + +export interface InterruptedSessionAssessment { + classification: InterruptedSessionClassification; + lock: LockData | null; + pausedSession: PausedSessionMetadata | null; + state: GSDState | null; + recovery: RecoveryBriefing | null; + recoveryPrompt: string | null; + recoveryToolCallCount: number; + artifactSatisfied: boolean; + hasResumableDiskState: boolean; + isBootstrapCrash: boolean; +} + +export function readPausedSessionMetadata( + basePath: string, +): PausedSessionMetadata | null { + const pausedPath = join(gsdRoot(basePath), "runtime", "paused-session.json"); + if (!existsSync(pausedPath)) return null; + + try { + return JSON.parse(readFileSync(pausedPath, "utf-8")) as PausedSessionMetadata; + } catch { + return null; + } +} + +export function isBootstrapCrashLock(lock: LockData | null): boolean { + return !!( + lock && + lock.unitType === "starting" && + lock.unitId === "bootstrap" + ); +} + +export function hasResumableDerivedState(state: GSDState | null): boolean { + return !!(state?.activeMilestone && state.phase !== "complete"); +} + +export async function assessInterruptedSession( + basePath: string, +): Promise { + const pausedSession = readPausedSessionMetadata(basePath); + const worktreeExists = pausedSession?.worktreePath + ? existsSync(pausedSession.worktreePath) + : false; + const assessmentBasePath = worktreeExists ? pausedSession!.worktreePath! : basePath; + const rawLock = readCrashLock(basePath); + const lock = rawLock && rawLock.pid !== process.pid ? rawLock : null; + + if (!lock && !pausedSession) { + return { + classification: "none", + lock: null, + pausedSession: null, + state: null, + recovery: null, + recoveryPrompt: null, + recoveryToolCallCount: 0, + artifactSatisfied: false, + hasResumableDiskState: false, + isBootstrapCrash: false, + }; + } + + if (lock && isLockProcessAlive(lock)) { + return { + classification: "running", + lock, + pausedSession, + state: null, + recovery: null, + recoveryPrompt: null, + recoveryToolCallCount: 0, + artifactSatisfied: false, + hasResumableDiskState: false, + isBootstrapCrash: false, + }; + } + + const isBootstrapCrash = isBootstrapCrashLock(lock); + const state = await deriveState(assessmentBasePath); + const hasResumableDiskState = hasResumableDerivedState(state); + const artifactSatisfied = !!( + lock && + !isBootstrapCrash && + verifyExpectedArtifact(lock.unitType, lock.unitId, assessmentBasePath) + ); + + let recovery: RecoveryBriefing | null = null; + if (lock && !isBootstrapCrash && !artifactSatisfied) { + recovery = synthesizeCrashRecovery( + assessmentBasePath, + lock.unitType, + lock.unitId, + lock.sessionFile, + join(gsdRoot(assessmentBasePath), "activity"), + ); + } + + const recoveryToolCallCount = recovery?.trace.toolCallCount ?? 0; + const recoveryPrompt = recoveryToolCallCount > 0 ? recovery!.prompt : null; + + if (isBootstrapCrash) { + return { + classification: pausedSession ? "recoverable" : "stale", + lock, + pausedSession, + state, + recovery, + recoveryPrompt, + recoveryToolCallCount, + artifactSatisfied, + hasResumableDiskState, + isBootstrapCrash: true, + }; + } + + if (!hasResumableDiskState && pausedSession && !lock && recoveryToolCallCount === 0) { + return { + classification: "stale", + lock, + pausedSession, + state, + recovery, + recoveryPrompt, + recoveryToolCallCount, + artifactSatisfied, + hasResumableDiskState, + isBootstrapCrash: false, + }; + } + + if (lock && artifactSatisfied && !hasResumableDiskState && recoveryToolCallCount === 0) { + return { + classification: "stale", + lock, + pausedSession, + state, + recovery, + recoveryPrompt, + recoveryToolCallCount, + artifactSatisfied, + hasResumableDiskState, + isBootstrapCrash: false, + }; + } + + const hasStrongRecoverySignal = + hasResumableDiskState || recoveryToolCallCount > 0; + + return { + classification: hasStrongRecoverySignal ? "recoverable" : "stale", + lock, + pausedSession, + state, + recovery, + recoveryPrompt, + recoveryToolCallCount, + artifactSatisfied, + hasResumableDiskState, + isBootstrapCrash: false, + }; +} + +export function formatInterruptedSessionSummary( + assessment: InterruptedSessionAssessment, +): string[] { + if (assessment.lock) return [formatCrashInfo(assessment.lock)]; + + if (assessment.pausedSession?.milestoneId) { + return [ + `Paused auto-mode session detected for ${assessment.pausedSession.milestoneId}.`, + ]; + } + + return ["Paused auto-mode session detected."]; +} + +export function formatInterruptedSessionRunningMessage( + assessment: InterruptedSessionAssessment, +): string { + const pid = assessment.lock?.pid; + return pid + ? `Another auto-mode session (PID ${pid}) appears to be running.\nStop it with \`kill ${pid}\` before starting a new session.` + : "Another auto-mode session appears to be running."; +} diff --git a/src/resources/extensions/gsd/json-persistence.ts b/src/resources/extensions/gsd/json-persistence.ts index 8c6c2776c..6aeef5720 100644 --- a/src/resources/extensions/gsd/json-persistence.ts +++ b/src/resources/extensions/gsd/json-persistence.ts @@ -1,5 +1,6 @@ -import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs"; +import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from "node:fs"; import { dirname } from "node:path"; +import { randomBytes } from "node:crypto"; /** * Load a JSON file with validation, returning a default on failure. @@ -51,9 +52,11 @@ export function loadJsonFileOrNull( export function saveJsonFile(filePath: string, data: T): void { try { mkdirSync(dirname(filePath), { recursive: true }); - const tmp = filePath + ".tmp"; + // Use randomized tmp suffix to prevent concurrent-write data loss + const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`; writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", "utf-8"); renameSync(tmp, filePath); + // No cleanup needed — renameSync atomically removes tmp on success } catch { // Non-fatal — don't let persistence failures break operation } @@ -66,7 +69,7 @@ export function saveJsonFile(filePath: string, data: T): void { export function writeJsonFileAtomic(filePath: string, data: T): void { try { mkdirSync(dirname(filePath), { recursive: true }); - const tmp = filePath + ".tmp"; + const tmp = `${filePath}.tmp.${randomBytes(4).toString("hex")}`; writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8"); renameSync(tmp, filePath); } catch { diff --git a/src/resources/extensions/gsd/markdown-renderer.ts b/src/resources/extensions/gsd/markdown-renderer.ts index 5e9eda89b..6f3ab0f45 100644 --- a/src/resources/extensions/gsd/markdown-renderer.ts +++ b/src/resources/extensions/gsd/markdown-renderer.ts @@ -9,6 +9,7 @@ // parseRoadmap(), parsePlan(), parseSummary() in files.ts. import { readFileSync, existsSync, mkdirSync } from "node:fs"; +import { logWarning } from "./workflow-logger.js"; import { isClosedStatus } from "./status-guards.js"; import { join, relative } from "node:path"; import { createRequire } from "node:module"; @@ -93,9 +94,7 @@ function loadArtifactContent( try { content = readFileSync(absPath, "utf-8"); } catch { - process.stderr.write( - `markdown-renderer: cannot read file from disk: ${absPath}\n`, - ); + logWarning("renderer", `cannot read file from disk: ${absPath}`); return null; } @@ -111,9 +110,7 @@ function loadArtifactContent( }); } catch { // Non-fatal: we have the content, DB storage is best-effort - process.stderr.write( - `markdown-renderer: warning — failed to store disk fallback in DB: ${artifactPath}\n`, - ); + logWarning("renderer", `failed to store disk fallback in DB: ${artifactPath}`); } return content; @@ -146,9 +143,7 @@ async function writeAndStore( }); } catch { // Non-fatal: file is on disk, DB is best-effort - process.stderr.write( - `markdown-renderer: warning — failed to update artifact in DB: ${artifactPath}\n`, - ); + logWarning("renderer", `failed to update artifact in DB: ${artifactPath}`); } invalidateCaches(); @@ -806,7 +801,8 @@ export function detectStaleRenders(basePath: string): StaleEntry[] { try { const m = _require("./parsers-legacy.ts"); parseRoadmap = m.parseRoadmap; parsePlan = m.parsePlan; - } catch { + } catch (e) { + logWarning("renderer", `parsers-legacy.ts require failed, falling back to .js: ${(e as Error).message}`); const m = _require("./parsers-legacy.js"); parseRoadmap = m.parseRoadmap; parsePlan = m.parsePlan; } @@ -841,8 +837,8 @@ export function detectStaleRenders(basePath: string): StaleEntry[] { }); } } - } catch { - // Can't parse roadmap — skip silently + } catch (e) { + logWarning("renderer", `roadmap parse failed: ${(e as Error).message}`); } } @@ -874,8 +870,8 @@ export function detectStaleRenders(basePath: string): StaleEntry[] { }); } } - } catch { - // Can't parse plan — skip silently + } catch (e) { + logWarning("renderer", `plan parse failed: ${(e as Error).message}`); } } @@ -1025,9 +1021,7 @@ export async function repairStaleRenders(basePath: string): Promise { } } } catch (err) { - process.stderr.write( - `markdown-renderer: repair failed for ${entry.path}: ${(err as Error).message}\n`, - ); + logWarning("renderer", `repair failed for ${entry.path}: ${(err as Error).message}`); } } diff --git a/src/resources/extensions/gsd/mcp-project-config.ts b/src/resources/extensions/gsd/mcp-project-config.ts new file mode 100644 index 000000000..351426909 --- /dev/null +++ b/src/resources/extensions/gsd/mcp-project-config.ts @@ -0,0 +1,128 @@ +import { existsSync, readFileSync, writeFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +import { assertSafeDirectory } from "./validate-directory.js"; +import { detectWorkflowMcpLaunchConfig } from "./workflow-mcp.js"; + +export const GSD_WORKFLOW_MCP_SERVER_NAME = "gsd-workflow"; + +export interface ProjectMcpServerConfig { + command?: string; + args?: string[]; + cwd?: string; + env?: Record; + url?: string; +} + +export interface EnsureProjectWorkflowMcpConfigResult { + configPath: string; + serverName: string; + status: "created" | "updated" | "unchanged"; +} + +interface McpConfigFile { + mcpServers?: Record; + servers?: Record; + [key: string]: unknown; +} + +export function resolveBundledGsdCliPath(env: NodeJS.ProcessEnv = process.env): string | null { + const explicit = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim(); + if (explicit) return explicit; + + const candidates = [ + resolve(fileURLToPath(new URL("../../../../scripts/dev-cli.js", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../dist/loader.js", import.meta.url))), + resolve(fileURLToPath(new URL("../../../loader.js", import.meta.url))), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + return null; +} + +export function buildProjectWorkflowMcpServerConfig( + projectRoot: string, + env: NodeJS.ProcessEnv = process.env, +): ProjectMcpServerConfig { + const resolvedProjectRoot = resolve(projectRoot); + const gsdCliPath = resolveBundledGsdCliPath(env); + const launch = detectWorkflowMcpLaunchConfig(resolvedProjectRoot, { + ...env, + ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}), + }); + + if (!launch) { + throw new Error( + "Unable to resolve the GSD workflow MCP server. Build this checkout or install gsd-mcp-server on PATH.", + ); + } + + return { + command: launch.command, + ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}), + ...(launch.cwd ? { cwd: launch.cwd } : {}), + ...(launch.env ? { env: launch.env } : {}), + }; +} + +function readExistingConfig(configPath: string): McpConfigFile { + if (!existsSync(configPath)) return {}; + + const raw = readFileSync(configPath, "utf-8"); + try { + const parsed = JSON.parse(raw) as McpConfigFile; + return parsed && typeof parsed === "object" ? parsed : {}; + } catch (err) { + throw new Error( + `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`, + ); + } +} + +export function ensureProjectWorkflowMcpConfig( + projectRoot: string, + env: NodeJS.ProcessEnv = process.env, +): EnsureProjectWorkflowMcpConfigResult { + const resolvedProjectRoot = resolve(projectRoot); + assertSafeDirectory(resolvedProjectRoot); + + const configPath = resolve(resolvedProjectRoot, ".mcp.json"); + const existing = readExistingConfig(configPath); + const desiredServer = buildProjectWorkflowMcpServerConfig(resolvedProjectRoot, env); + const previousServers = existing.mcpServers ?? {}; + const nextServers = { + ...previousServers, + [GSD_WORKFLOW_MCP_SERVER_NAME]: desiredServer, + }; + + const alreadyPresent = existsSync(configPath); + const unchanged = + JSON.stringify(previousServers[GSD_WORKFLOW_MCP_SERVER_NAME] ?? null) + === JSON.stringify(desiredServer) + && existing.mcpServers !== undefined; + + if (unchanged) { + return { + configPath, + serverName: GSD_WORKFLOW_MCP_SERVER_NAME, + status: "unchanged", + }; + } + + const nextConfig: McpConfigFile = { + ...existing, + mcpServers: nextServers, + }; + + writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8"); + + return { + configPath, + serverName: GSD_WORKFLOW_MCP_SERVER_NAME, + status: alreadyPresent ? "updated" : "created", + }; +} diff --git a/src/resources/extensions/gsd/md-importer.ts b/src/resources/extensions/gsd/md-importer.ts index f0ba20231..aaa6aa612 100644 --- a/src/resources/extensions/gsd/md-importer.ts +++ b/src/resources/extensions/gsd/md-importer.ts @@ -31,6 +31,7 @@ import { import { findMilestoneIds } from './guided-flow.js'; import { parseRoadmap, parsePlan } from './parsers-legacy.js'; import { parseContextDependsOn } from './files.js'; +import { logWarning } from './workflow-logger.js'; // ─── DECISIONS.md Parser ─────────────────────────────────────────────────── @@ -529,11 +530,6 @@ export function migrateHierarchyToDb(basePath: string): { // Ghost milestone: no CONTEXT, ROADMAP, or SUMMARY → skip if (!hasRoadmap && !hasContext && !hasSummary) continue; - // Determine milestone status - let milestoneStatus = 'active'; - if (hasSummary) milestoneStatus = 'complete'; - else if (hasParked) milestoneStatus = 'parked'; - // Determine milestone title from roadmap H1 or CONTEXT heading let milestoneTitle = ''; let roadmapContent: string | null = null; @@ -543,6 +539,16 @@ export function migrateHierarchyToDb(basePath: string): { roadmap = parseRoadmap(roadmapContent); milestoneTitle = roadmap.title; } + + // Determine milestone status + let milestoneStatus = 'active'; + if (hasSummary) milestoneStatus = 'complete'; + else if (hasParked) milestoneStatus = 'parked'; + // Import milestones with all-done roadmap slices as complete (#3390, #3379) + // even when SUMMARY.md is missing — the roadmap checkboxes are authoritative. + else if (roadmap && roadmap.slices.length > 0 && roadmap.slices.every(s => s.done)) { + milestoneStatus = 'complete'; + } if (!milestoneTitle && hasContext) { const contextContent = readFileSync(contextPath!, 'utf-8'); const h1Match = contextContent.match(/^#\s+(.+)/m); @@ -585,7 +591,8 @@ export function migrateHierarchyToDb(basePath: string): { // Parse roadmap for slices if (!roadmap) continue; - for (const sliceEntry of roadmap.slices) { + for (let si = 0; si < roadmap.slices.length; si++) { + const sliceEntry = roadmap.slices[si]!; // Per K002: use 'complete' not 'done' const sliceStatus = sliceEntry.done ? 'complete' : 'pending'; @@ -605,6 +612,7 @@ export function migrateHierarchyToDb(basePath: string): { risk: sliceEntry.risk, depends: sliceEntry.depends, demo: sliceEntry.demo, + sequence: si + 1, // Preserve roadmap parse order (#3356) planning: { goal: plan?.goal ?? '', }, @@ -712,25 +720,25 @@ export function migrateFromMarkdown(gsdDir: string): { try { decisions = importDecisions(gsdDir); } catch (err) { - process.stderr.write(`gsd-migrate: skipping decisions import: ${(err as Error).message}\n`); + logWarning("migration", `skipping decisions import: ${(err as Error).message}`); } try { requirements = importRequirements(gsdDir); } catch (err) { - process.stderr.write(`gsd-migrate: skipping requirements import: ${(err as Error).message}\n`); + logWarning("migration", `skipping requirements import: ${(err as Error).message}`); } try { artifacts = importHierarchyArtifacts(gsdDir); } catch (err) { - process.stderr.write(`gsd-migrate: skipping artifacts import: ${(err as Error).message}\n`); + logWarning("migration", `skipping artifacts import: ${(err as Error).message}`); } try { hierarchy = migrateHierarchyToDb(gsdDir); } catch (err) { - process.stderr.write(`gsd-migrate: skipping hierarchy migration: ${(err as Error).message}\n`); + logWarning("migration", `skipping hierarchy migration: ${(err as Error).message}`); } }); diff --git a/src/resources/extensions/gsd/memory-extractor.ts b/src/resources/extensions/gsd/memory-extractor.ts index c63a385a5..acca3c7a0 100644 --- a/src/resources/extensions/gsd/memory-extractor.ts +++ b/src/resources/extensions/gsd/memory-extractor.ts @@ -87,14 +87,22 @@ export function buildMemoryLLMCall(ctx: ExtensionContext): LLMCallFn | null { const selectedModel = model as Model; + // Resolve API key via modelRegistry so OAuth tokens (auth.json) are used. + // Without this, streamSimpleAnthropic only checks env vars via getEnvApiKey, + // which returns undefined for OAuth users (Claude Max / Claude Pro). + // See: https://github.com/gsd-build/gsd-2/issues/2959 + const resolvedKeyPromise = ctx.modelRegistry.getApiKey(selectedModel).catch(() => undefined); + return async (system: string, user: string): Promise => { const { completeSimple } = await import('@gsd/pi-ai'); + const resolvedApiKey = await resolvedKeyPromise; const result: AssistantMessage = await completeSimple(selectedModel, { systemPrompt: system, messages: [{ role: 'user', content: [{ type: 'text', text: user }], timestamp: Date.now() }], }, { maxTokens: 2048, temperature: 0, + ...(resolvedApiKey ? { apiKey: resolvedApiKey } : {}), }); // Extract text from response diff --git a/src/resources/extensions/gsd/metrics.ts b/src/resources/extensions/gsd/metrics.ts index 1467499e4..a29d4f39d 100644 --- a/src/resources/extensions/gsd/metrics.ts +++ b/src/resources/extensions/gsd/metrics.ts @@ -567,7 +567,34 @@ export function loadLedgerFromDisk(base: string): MetricsLedger | null { } function loadLedger(base: string): MetricsLedger { - return loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger); + const raw = loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger); + const before = raw.units.length; + raw.units = deduplicateUnits(raw.units); + if (raw.units.length < before) { + // Persist the cleaned ledger so duplicates don't re-accumulate + saveLedger(base, raw); + } + return raw; +} + +/** + * Collapse duplicate entries with the same (type, id, startedAt) triple. + * Keeps the entry with the highest finishedAt (the most complete snapshot). + * + * This is a defensive measure against idle-watchdog race conditions that can + * produce duplicate entries on disk despite the in-memory idempotency guard + * in snapshotUnitMetrics(). See #1943. + */ +function deduplicateUnits(units: UnitMetrics[]): UnitMetrics[] { + const map = new Map(); + for (const u of units) { + const key = `${u.type}\0${u.id}\0${u.startedAt}`; + const existing = map.get(key); + if (!existing || u.finishedAt > existing.finishedAt) { + map.set(key, u); + } + } + return Array.from(map.values()); } function saveLedger(base: string, data: MetricsLedger): void { diff --git a/src/resources/extensions/gsd/migrate-external.ts b/src/resources/extensions/gsd/migrate-external.ts index 4fd53e7d1..1f9786799 100644 --- a/src/resources/extensions/gsd/migrate-external.ts +++ b/src/resources/extensions/gsd/migrate-external.ts @@ -9,7 +9,7 @@ import { execFileSync } from "node:child_process"; import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs"; import { join } from "node:path"; -import { externalGsdRoot } from "./repo-identity.js"; +import { externalGsdRoot, isInsideWorktree } from "./repo-identity.js"; import { getErrorMessage } from "./error-utils.js"; import { hasGitTrackedGsdFiles } from "./gitignore.js"; import { GIT_NO_PROMPT_ENV } from "./git-constants.js"; @@ -34,6 +34,14 @@ export interface MigrationResult { * 3. On failure: rename `.gsd.migrating` back to `.gsd` (rollback) */ export function migrateToExternalState(basePath: string): MigrationResult { + // Worktrees get their .gsd via syncGsdStateToWorktree(), not migration. + // Migration inside a worktree would compute the same external hash as the + // main repo (externalGsdRoot hashes remoteUrl + gitRoot), creating a broken + // junction and orphaning .gsd.migrating (#2970). + if (isInsideWorktree(basePath)) { + return { migrated: false }; + } + const localGsd = join(basePath, ".gsd"); // Skip if doesn't exist diff --git a/src/resources/extensions/gsd/milestone-actions.ts b/src/resources/extensions/gsd/milestone-actions.ts index 7615a1eb9..49102dc25 100644 --- a/src/resources/extensions/gsd/milestone-actions.ts +++ b/src/resources/extensions/gsd/milestone-actions.ts @@ -21,6 +21,7 @@ import { import { invalidateAllCaches } from "./cache.js"; import { loadQueueOrder, saveQueueOrder } from "./queue-order.js"; import { isDbAvailable, updateMilestoneStatus } from "./gsd-db.js"; +import { logWarning } from "./workflow-logger.js"; // ─── Park ────────────────────────────────────────────────────────────────── @@ -58,7 +59,7 @@ export function parkMilestone(basePath: string, milestoneId: string, reason: str try { updateMilestoneStatus(milestoneId, "parked"); } catch (err) { - process.stderr.write(`gsd: parkMilestone DB sync failed for ${milestoneId}: ${(err as Error).message}\n`); + logWarning("engine", `parkMilestone DB sync failed for ${milestoneId}: ${(err as Error).message}`); } } invalidateAllCaches(); @@ -84,7 +85,7 @@ export function unparkMilestone(basePath: string, milestoneId: string): boolean try { updateMilestoneStatus(milestoneId, "active"); } catch (err) { - process.stderr.write(`gsd: unparkMilestone DB sync failed for ${milestoneId}: ${(err as Error).message}\n`); + logWarning("engine", `unparkMilestone DB sync failed for ${milestoneId}: ${(err as Error).message}`); } } invalidateAllCaches(); diff --git a/src/resources/extensions/gsd/milestone-ids.ts b/src/resources/extensions/gsd/milestone-ids.ts index aa44c8f87..3d6d9592d 100644 --- a/src/resources/extensions/gsd/milestone-ids.ts +++ b/src/resources/extensions/gsd/milestone-ids.ts @@ -6,6 +6,7 @@ */ import { randomInt } from "node:crypto"; +import { logWarning } from "./workflow-logger.js"; import { readdirSync, existsSync } from "node:fs"; import { milestonesDir } from "./paths.js"; import { loadQueueOrder, sortByQueueOrder } from "./queue-order.js"; @@ -128,7 +129,7 @@ export function findMilestoneIds(basePath: string): string[] { } catch (err) { // Log why milestone scanning failed — silent [] here causes infinite loops (#456) if (existsSync(dir)) { - console.error(`[gsd] findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${getErrorMessage(err)}`); + logWarning("engine", `findMilestoneIds: .gsd/milestones/ exists but readdirSync failed — ${getErrorMessage(err)}`); } return []; } diff --git a/src/resources/extensions/gsd/milestone-validation-gates.ts b/src/resources/extensions/gsd/milestone-validation-gates.ts new file mode 100644 index 000000000..4dcd522b6 --- /dev/null +++ b/src/resources/extensions/gsd/milestone-validation-gates.ts @@ -0,0 +1,56 @@ +/** + * Milestone validation quality gate persistence. + * + * #2945 Bug 4: validate-milestone was writing VALIDATION.md to disk and + * inserting an assessment row, but never persisted structured quality_gates + * records in the DB. This module inserts milestone-level validation gates + * that correspond to the validation checks performed. + * + * Gate IDs for milestone validation: + * MV01 — Success criteria checklist + * MV02 — Slice delivery audit + * MV03 — Cross-slice integration + * MV04 — Requirement coverage + * + * These use the existing quality_gates table with scope "milestone". + */ + +import { _getAdapter } from "./gsd-db.js"; + +/** Milestone validation gate IDs. */ +const MILESTONE_GATE_IDS = ["MV01", "MV02", "MV03", "MV04"] as const; + +/** + * Insert milestone-level quality_gates records for a validation run. + * + * Each gate is inserted with status "complete" and a verdict derived + * from the overall milestone validation verdict. Individual gate-level + * verdicts are not available (the handler receives a single verdict), + * so all gates share the overall verdict. + */ +export function insertMilestoneValidationGates( + milestoneId: string, + sliceId: string, + verdict: string, + evaluatedAt: string, +): void { + const db = _getAdapter(); + if (!db) return; + + const gateVerdict = verdict === "pass" ? "pass" : "flag"; + + for (const gateId of MILESTONE_GATE_IDS) { + db.prepare( + `INSERT OR REPLACE INTO quality_gates + (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at) + VALUES (:mid, :sid, :gid, 'milestone', '', 'complete', :verdict, :rationale, '', :evaluated_at)`, + ).run({ + ":mid": milestoneId, + ":sid": sliceId, + ":gid": gateId, + ":verdict": gateVerdict, + ":rationale": `Milestone validation verdict: ${verdict}`, + ":evaluated_at": evaluatedAt, + }); + } +} diff --git a/src/resources/extensions/gsd/model-cost-table.ts b/src/resources/extensions/gsd/model-cost-table.ts index 82be7930d..4c4ebc81c 100644 --- a/src/resources/extensions/gsd/model-cost-table.ts +++ b/src/resources/extensions/gsd/model-cost-table.ts @@ -33,10 +33,29 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [ // OpenAI { id: "gpt-4o", inputPer1k: 0.0025, outputPer1k: 0.01, updatedAt: "2025-03-15" }, { id: "gpt-4o-mini", inputPer1k: 0.00015, outputPer1k: 0.0006, updatedAt: "2025-03-15" }, + { id: "gpt-4.1", inputPer1k: 0.002, outputPer1k: 0.008, updatedAt: "2026-03-29" }, + { id: "gpt-4.1-mini", inputPer1k: 0.0004, outputPer1k: 0.0016, updatedAt: "2026-03-29" }, + { id: "gpt-4.1-nano", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2026-03-29" }, + { id: "gpt-5", inputPer1k: 0.01, outputPer1k: 0.04, updatedAt: "2026-03-29" }, + { id: "gpt-5-mini", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" }, + { id: "gpt-5-nano", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2026-03-29" }, + { id: "gpt-5-pro", inputPer1k: 0.015, outputPer1k: 0.06, updatedAt: "2026-03-29" }, { id: "o1", inputPer1k: 0.015, outputPer1k: 0.06, updatedAt: "2025-03-15" }, { id: "o3", inputPer1k: 0.015, outputPer1k: 0.06, updatedAt: "2025-03-15" }, + { id: "o4-mini", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + { id: "o4-mini-deep-research", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, { id: "gpt-4-turbo", inputPer1k: 0.01, outputPer1k: 0.03, updatedAt: "2025-03-15" }, + // OpenAI Codex + { id: "gpt-5.1", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + { id: "gpt-5.1-codex-max", inputPer1k: 0.003, outputPer1k: 0.012, updatedAt: "2026-03-29" }, + { id: "gpt-5.1-codex-mini", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" }, + { id: "gpt-5.2", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + { id: "gpt-5.2-codex", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + { id: "gpt-5.3-codex", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + { id: "gpt-5.3-codex-spark", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" }, + { id: "gpt-5.4", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" }, + // Google { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" }, { id: "gemini-flash-2.0", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" }, diff --git a/src/resources/extensions/gsd/model-router.ts b/src/resources/extensions/gsd/model-router.ts index fe8bdf0a5..cc915877a 100644 --- a/src/resources/extensions/gsd/model-router.ts +++ b/src/resources/extensions/gsd/model-router.ts @@ -2,14 +2,18 @@ // Maps complexity tiers to models, enforcing downgrade-only semantics. // The user's configured model is always the ceiling. -import type { ComplexityTier, ClassificationResult } from "./complexity-classifier.js"; +import type { ComplexityTier, ClassificationResult, TaskMetadata } from "./complexity-classifier.js"; import { tierOrdinal } from "./complexity-classifier.js"; import type { ResolvedModelConfig } from "./preferences.js"; +import { getProviderCapabilities, type ProviderCapabilities } from "@gsd/pi-ai"; +import { getToolCompatibility, getAllToolCompatibility } from "@gsd/pi-coding-agent"; +import type { ToolCompatibility } from "@gsd/pi-coding-agent"; // ─── Types ─────────────────────────────────────────────────────────────────── export interface DynamicRoutingConfig { enabled?: boolean; + capability_routing?: boolean; // default: false — enable capability profile scoring tier_models?: { light?: string; standard?: string; @@ -32,18 +36,45 @@ export interface RoutingDecision { wasDowngraded: boolean; /** Human-readable reason for this decision */ reason: string; + /** How the model was selected */ + selectionMethod: "tier-only" | "capability-scored"; + /** Capability scores per eligible model (capability-scored path only) */ + capabilityScores?: Record; + /** Tools filtered out due to provider incompatibility (ADR-005) */ + filteredTools?: string[]; + /** Task requirement vector used for scoring */ + taskRequirements?: Partial>; +} + +// ─── Capability Profiles ───────────────────────────────────────────────────── + +/** Seven-dimension capability profile for a model. All values in 0–100 range. */ +export interface ModelCapabilities { + coding: number; + debugging: number; + research: number; + reasoning: number; + speed: number; + longContext: number; + instruction: number; } // ─── Known Model Tiers ─────────────────────────────────────────────────────── // Maps known model IDs to their capability tier. Used when tier_models is not // explicitly configured to pick the best available model for each tier. -const MODEL_CAPABILITY_TIER: Record = { +export const MODEL_CAPABILITY_TIER: Record = { // Light-tier models (cheapest) "claude-haiku-4-5": "light", "claude-3-5-haiku-latest": "light", "claude-3-haiku-20240307": "light", "gpt-4o-mini": "light", + "gpt-4.1-mini": "light", + "gpt-4.1-nano": "light", + "gpt-5-mini": "light", + "gpt-5-nano": "light", + "gpt-5.1-codex-mini": "light", + "gpt-5.3-codex-spark": "light", "gemini-2.0-flash": "light", "gemini-flash-2.0": "light", @@ -52,6 +83,8 @@ const MODEL_CAPABILITY_TIER: Record = { "claude-sonnet-4-5-20250514": "standard", "claude-3-5-sonnet-latest": "standard", "gpt-4o": "standard", + "gpt-4.1": "standard", + "gpt-5.1-codex-max": "standard", "gemini-2.5-pro": "standard", "deepseek-chat": "standard", @@ -59,8 +92,17 @@ const MODEL_CAPABILITY_TIER: Record = { "claude-opus-4-6": "heavy", "claude-3-opus-latest": "heavy", "gpt-4-turbo": "heavy", + "gpt-5": "heavy", + "gpt-5-pro": "heavy", + "gpt-5.1": "heavy", + "gpt-5.2": "heavy", + "gpt-5.2-codex": "heavy", + "gpt-5.3-codex": "heavy", + "gpt-5.4": "heavy", "o1": "heavy", "o3": "heavy", + "o4-mini": "heavy", + "o4-mini-deep-research": "heavy", }; // ─── Cost Table (per 1K input tokens, approximate USD) ─────────────────────── @@ -75,29 +117,263 @@ const MODEL_COST_PER_1K_INPUT: Record = { "claude-opus-4-6": 0.015, "gpt-4o-mini": 0.00015, "gpt-4o": 0.0025, + "gpt-4.1": 0.002, + "gpt-4.1-mini": 0.0004, + "gpt-4.1-nano": 0.0001, + "gpt-5": 0.01, + "gpt-5-mini": 0.0003, + "gpt-5-nano": 0.0001, + "gpt-5-pro": 0.015, + "gpt-5.1": 0.005, + "gpt-5.1-codex-max": 0.003, + "gpt-5.1-codex-mini": 0.0003, + "gpt-5.2": 0.005, + "gpt-5.2-codex": 0.005, + "gpt-5.3-codex": 0.005, + "gpt-5.3-codex-spark": 0.0003, + "gpt-5.4": 0.005, + "o4-mini": 0.005, + "o4-mini-deep-research": 0.005, "gemini-2.0-flash": 0.0001, "gemini-2.5-pro": 0.00125, "deepseek-chat": 0.00014, }; +// ─── Capability Profiles Data Table ────────────────────────────────────────── +// Per-model capability profiles (0–100 scale). Used for capability-aware +// model selection within an eligible tier set. + +export const MODEL_CAPABILITY_PROFILES: Record = { + // ── Anthropic ────────────────────────────────────────────────────────────── + "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 }, + "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 }, + "claude-sonnet-4-5-20250514": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 }, + "claude-3-5-sonnet-latest": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 }, + "claude-haiku-4-5": { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 }, + "claude-3-5-haiku-latest": { coding: 60, debugging: 50, research: 45, reasoning: 50, speed: 95, longContext: 50, instruction: 75 }, + "claude-3-haiku-20240307": { coding: 50, debugging: 40, research: 35, reasoning: 40, speed: 95, longContext: 40, instruction: 65 }, + "claude-3-opus-latest": { coding: 90, debugging: 85, research: 82, reasoning: 90, speed: 35, longContext: 75, instruction: 88 }, + + // ── OpenAI GPT ───────────────────────────────────────────────────────────── + "gpt-4o": { coding: 80, debugging: 75, research: 70, reasoning: 75, speed: 65, longContext: 70, instruction: 80 }, + "gpt-4o-mini": { coding: 55, debugging: 45, research: 40, reasoning: 45, speed: 90, longContext: 45, instruction: 70 }, + "gpt-4-turbo": { coding: 78, debugging: 72, research: 68, reasoning: 72, speed: 50, longContext: 65, instruction: 78 }, + "gpt-4.1": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 72, instruction: 82 }, + "gpt-4.1-mini": { coding: 58, debugging: 48, research: 42, reasoning: 48, speed: 88, longContext: 48, instruction: 72 }, + "gpt-4.1-nano": { coding: 40, debugging: 30, research: 25, reasoning: 30, speed: 95, longContext: 30, instruction: 60 }, + "gpt-5": { coding: 92, debugging: 88, research: 85, reasoning: 92, speed: 40, longContext: 85, instruction: 90 }, + "gpt-5-mini": { coding: 62, debugging: 52, research: 48, reasoning: 52, speed: 88, longContext: 52, instruction: 74 }, + "gpt-5-nano": { coding: 42, debugging: 32, research: 28, reasoning: 32, speed: 95, longContext: 32, instruction: 62 }, + "gpt-5-pro": { coding: 94, debugging: 90, research: 88, reasoning: 94, speed: 35, longContext: 88, instruction: 92 }, + "gpt-5.1": { coding: 93, debugging: 89, research: 86, reasoning: 93, speed: 42, longContext: 86, instruction: 91 }, + "gpt-5.1-codex-max": { coding: 90, debugging: 85, research: 70, reasoning: 85, speed: 55, longContext: 75, instruction: 85 }, + "gpt-5.1-codex-mini": { coding: 65, debugging: 55, research: 40, reasoning: 50, speed: 88, longContext: 48, instruction: 72 }, + "gpt-5.2": { coding: 93, debugging: 90, research: 87, reasoning: 93, speed: 42, longContext: 87, instruction: 91 }, + "gpt-5.2-codex": { coding: 93, debugging: 90, research: 72, reasoning: 88, speed: 50, longContext: 78, instruction: 88 }, + "gpt-5.3-codex": { coding: 94, debugging: 91, research: 74, reasoning: 89, speed: 50, longContext: 80, instruction: 89 }, + "gpt-5.3-codex-spark": { coding: 68, debugging: 58, research: 42, reasoning: 52, speed: 90, longContext: 50, instruction: 74 }, + "gpt-5.4": { coding: 95, debugging: 92, research: 88, reasoning: 94, speed: 42, longContext: 88, instruction: 92 }, + + // ── OpenAI o-series (reasoning-first) ────────────────────────────────────── + "o1": { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 }, + "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 }, + "o4-mini": { coding: 75, debugging: 80, research: 72, reasoning: 88, speed: 60, longContext: 65, instruction: 80 }, + "o4-mini-deep-research": { coding: 75, debugging: 80, research: 85, reasoning: 88, speed: 30, longContext: 80, instruction: 80 }, + + // ── Google ───────────────────────────────────────────────────────────────── + "gemini-2.5-pro": { coding: 75, debugging: 70, research: 85, reasoning: 75, speed: 55, longContext: 90, instruction: 75 }, + "gemini-2.0-flash": { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 }, + "gemini-flash-2.0": { coding: 50, debugging: 40, research: 50, reasoning: 40, speed: 95, longContext: 60, instruction: 65 }, + + // ── DeepSeek ─────────────────────────────────────────────────────────────── + "deepseek-chat": { coding: 75, debugging: 65, research: 55, reasoning: 70, speed: 70, longContext: 55, instruction: 65 }, +}; + +// ─── Base Task Requirements Data Table ─────────────────────────────────────── +// Per-unit-type base requirement vectors. Weights indicate how important each +// capability dimension is for this unit type. + +export const BASE_REQUIREMENTS: Record>> = { + "execute-task": { coding: 0.9, instruction: 0.7, speed: 0.3 }, + "research-milestone": { research: 0.9, longContext: 0.7, reasoning: 0.5 }, + "research-slice": { research: 0.9, longContext: 0.7, reasoning: 0.5 }, + "plan-milestone": { reasoning: 0.9, coding: 0.5 }, + "plan-slice": { reasoning: 0.9, coding: 0.5 }, + "replan-slice": { reasoning: 0.9, debugging: 0.6, coding: 0.5 }, + "reassess-roadmap": { reasoning: 0.9, research: 0.5 }, + "complete-slice": { instruction: 0.8, speed: 0.7 }, + "run-uat": { instruction: 0.7, speed: 0.8 }, + "discuss-milestone": { reasoning: 0.6, instruction: 0.7 }, + "complete-milestone": { instruction: 0.8, reasoning: 0.5 }, +}; + // ─── Public API ────────────────────────────────────────────────────────────── +/** + * Score a model's suitability for a task given a requirement vector. + * Returns a weighted average of capability dimensions (0–100). + * Returns 50 if requirements are empty (neutral score). + */ +export function scoreModel( + model: ModelCapabilities, + requirements: Partial>, +): number { + let weightedSum = 0; + let weightSum = 0; + for (const [dim, weight] of Object.entries(requirements)) { + const capability = model[dim as keyof ModelCapabilities] ?? 50; + weightedSum += weight * capability; + weightSum += weight; + } + return weightSum > 0 ? weightedSum / weightSum : 50; +} + +/** + * Compute dynamic task requirements from unit type and optional task metadata. + * Returns a requirement vector refined by task-specific signals. + */ +export function computeTaskRequirements( + unitType: string, + metadata?: TaskMetadata, +): Partial> { + const base = BASE_REQUIREMENTS[unitType] ?? { reasoning: 0.5 }; + if (unitType === "execute-task" && metadata) { + if (metadata.tags?.some(t => /^(docs?|readme|comment|config|typo|rename)$/i.test(t))) { + return { ...base, instruction: 0.9, coding: 0.3, speed: 0.7 }; + } + if (metadata.complexityKeywords?.some(k => k === "concurrency" || k === "compatibility")) { + return { ...base, debugging: 0.9, reasoning: 0.8 }; + } + if (metadata.complexityKeywords?.some(k => k === "migration" || k === "architecture")) { + return { ...base, reasoning: 0.9, coding: 0.8 }; + } + if ((metadata.fileCount ?? 0) >= 6 || (metadata.estimatedLines ?? 0) >= 500) { + return { ...base, coding: 0.9, reasoning: 0.7 }; + } + } + return base; +} + +/** + * Score all eligible models against a requirement vector and return them + * sorted by score descending. Within 2 points: prefer cheaper; equal cost: + * lexicographic tie-break by model ID. + */ +export function scoreEligibleModels( + eligibleModelIds: string[], + requirements: Partial>, + capabilityOverrides?: Record>, +): Array<{ modelId: string; score: number }> { + const scored = eligibleModelIds.map(modelId => { + const builtin = MODEL_CAPABILITY_PROFILES[modelId]; + const override = capabilityOverrides?.[modelId]; + const profile: ModelCapabilities = builtin + ? override ? { ...builtin, ...override } : builtin + : { coding: 50, debugging: 50, research: 50, reasoning: 50, speed: 50, longContext: 50, instruction: 50 }; + return { modelId, score: scoreModel(profile, requirements) }; + }); + scored.sort((a, b) => { + const scoreDiff = b.score - a.score; + if (Math.abs(scoreDiff) > 2) return scoreDiff; + const costA = MODEL_COST_PER_1K_INPUT[a.modelId] ?? Infinity; + const costB = MODEL_COST_PER_1K_INPUT[b.modelId] ?? Infinity; + if (costA !== costB) return costA - costB; + return a.modelId.localeCompare(b.modelId); + }); + return scored; +} + +/** + * Return all models eligible for a given tier, sorted cheapest first. + * If routingConfig.tier_models[tier] is set and available, returns only that + * model. Otherwise filters availableModelIds by tier from MODEL_CAPABILITY_TIER. + */ +export function getEligibleModels( + tier: ComplexityTier, + availableModelIds: string[], + routingConfig: DynamicRoutingConfig, +): string[] { + // 1. Check explicit tier_models config + const explicitModel = routingConfig.tier_models?.[tier]; + if (explicitModel) { + // Exact match + if (availableModelIds.includes(explicitModel)) return [explicitModel]; + // Provider-prefix-stripped match + const match = availableModelIds.find(id => { + const bareAvail = id.includes("/") ? id.split("/").pop()! : id; + const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel; + return bareAvail === bareExplicit; + }); + if (match) return [match]; + } + + // 2. Auto-detect: filter by tier, sort cheapest first + return availableModelIds + .filter(id => getModelTier(id) === tier) + .sort((a, b) => { + const costA = getModelCost(a); + const costB = getModelCost(b); + return costA - costB; + }); +} + +/** + * Build a fallback chain for a selected model: [selectedModel, ...configuredFallbacks, configuredPrimary] + * Deduplicates entries while preserving order. + */ +function buildFallbackChain(selectedModelId: string, phaseConfig: ResolvedModelConfig): string[] { + return [ + ...phaseConfig.fallbacks.filter(f => f !== selectedModelId), + phaseConfig.primary, + ].filter(f => f !== selectedModelId); +} + +/** + * Load capability overrides from user preferences' modelOverrides section. + * Returns a map of model ID → partial capability overrides to deep-merge with built-in profiles. + * + * Per D-17: partial capability overrides via models.json modelOverrides, deep-merged with defaults. + */ +export function loadCapabilityOverrides( + prefs: { modelOverrides?: Record }> }, +): Record> { + const result: Record> = {}; + if (!prefs.modelOverrides) return result; + for (const [modelId, overrideEntry] of Object.entries(prefs.modelOverrides)) { + if (overrideEntry.capabilities) { + result[modelId] = overrideEntry.capabilities; + } + } + return result; +} + /** * Resolve the model to use for a given complexity tier. * * Downgrade-only: the returned model is always equal to or cheaper than * the user's configured primary model. Never upgrades beyond configuration. * - * @param classification The complexity classification result - * @param phaseConfig The user's configured model for this phase (ceiling) - * @param routingConfig Dynamic routing configuration - * @param availableModelIds List of available model IDs (from registry) + * STEP 1: Filter to eligible models for the requested tier. + * STEP 2: Capability scoring — ranks eligible models by task-capability match + * when capability_routing is enabled and multiple eligible models exist. + * STEP 3: Fallback chain assembly. + * + * @param classification The complexity classification result + * @param phaseConfig The user's configured model for this phase (ceiling) + * @param routingConfig Dynamic routing configuration + * @param availableModelIds List of available model IDs (from registry) + * @param unitType The unit type for capability requirement computation (optional) + * @param taskMetadata Task metadata for refined requirement vectors (optional) + * @param capabilityOverrides User-provided capability overrides (deep-merged with built-in profiles, optional) */ export function resolveModelForComplexity( classification: ClassificationResult, phaseConfig: ResolvedModelConfig | undefined, routingConfig: DynamicRoutingConfig, availableModelIds: string[], + unitType?: string, + taskMetadata?: TaskMetadata, + capabilityOverrides?: Record>, ): RoutingDecision { // If no phase config or routing disabled, pass through if (!phaseConfig || !routingConfig.enabled) { @@ -107,6 +383,7 @@ export function resolveModelForComplexity( tier: classification.tier, wasDowngraded: false, reason: "dynamic routing disabled or no phase config", + selectionMethod: "tier-only", }; } @@ -126,6 +403,7 @@ export function resolveModelForComplexity( tier: requestedTier, wasDowngraded: false, reason: `configured model "${configuredPrimary}" is not in the known tier map — honoring explicit config`, + selectionMethod: "tier-only", }; } @@ -137,18 +415,14 @@ export function resolveModelForComplexity( tier: requestedTier, wasDowngraded: false, reason: `tier ${requestedTier} >= configured ${configuredTier}`, + selectionMethod: "tier-only", }; } - // Find the best model for the requested tier - const targetModelId = findModelForTier( - requestedTier, - routingConfig, - availableModelIds, - routingConfig.cross_provider !== false, - ); + // STEP 1: Get all eligible models for the requested tier + const eligible = getEligibleModels(requestedTier, availableModelIds, routingConfig); - if (!targetModelId) { + if (eligible.length === 0) { // No suitable model found — use configured primary return { modelId: configuredPrimary, @@ -156,14 +430,37 @@ export function resolveModelForComplexity( tier: requestedTier, wasDowngraded: false, reason: `no ${requestedTier}-tier model available`, + selectionMethod: "tier-only", }; } + // STEP 2: Capability scoring (when enabled and multiple eligible models exist) + if (routingConfig.capability_routing !== false && eligible.length > 1 && unitType) { + const requirements = computeTaskRequirements(unitType, taskMetadata); + const scored = scoreEligibleModels(eligible, requirements, capabilityOverrides); + const winner = scored[0]; + if (winner) { + const capScores: Record = {}; + for (const s of scored) capScores[s.modelId] = s.score; + const fallbacks = buildFallbackChain(winner.modelId, phaseConfig); + return { + modelId: winner.modelId, + fallbacks, + tier: requestedTier, + wasDowngraded: true, + reason: `capability-scored: ${winner.modelId} (${winner.score.toFixed(1)}) for ${unitType}`, + capabilityScores: capScores, + taskRequirements: requirements, + selectionMethod: "capability-scored", + }; + } + } + + // STEP 3: Fallback — use first eligible model (cheapest in tier, or single eligible) + const targetModelId = eligible[0]; + // Build fallback chain: [downgraded_model, ...configured_fallbacks, configured_primary] - const fallbacks = [ - ...phaseConfig.fallbacks.filter(f => f !== targetModelId), - configuredPrimary, - ].filter(f => f !== targetModelId); + const fallbacks = buildFallbackChain(targetModelId, phaseConfig); return { modelId: targetModelId, @@ -171,6 +468,7 @@ export function resolveModelForComplexity( tier: requestedTier, wasDowngraded: true, reason: classification.reason, + selectionMethod: "tier-only", }; } @@ -191,7 +489,8 @@ export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null */ export function defaultRoutingConfig(): DynamicRoutingConfig { return { - enabled: false, + enabled: true, + capability_routing: true, escalate_on_failure: true, budget_pressure: true, cross_provider: true, @@ -213,8 +512,8 @@ function getModelTier(modelId: string): ComplexityTier { if (bareId.includes(knownId) || knownId.includes(bareId)) return tier; } - // Unknown models are assumed heavy (safest assumption) - return "heavy"; + // Unknown models are assumed standard (per D-15: avoids silently ignoring user config) + return "standard"; } /** Check if a model ID has a known capability tier mapping. (#2192) */ @@ -227,43 +526,6 @@ function isKnownModel(modelId: string): boolean { return false; } -function findModelForTier( - tier: ComplexityTier, - config: DynamicRoutingConfig, - availableModelIds: string[], - crossProvider: boolean, -): string | null { - // 1. Check explicit tier_models config - const explicitModel = config.tier_models?.[tier]; - if (explicitModel && availableModelIds.includes(explicitModel)) { - return explicitModel; - } - // Also check with provider prefix stripped - if (explicitModel) { - const match = availableModelIds.find(id => { - const bareAvail = id.includes("/") ? id.split("/").pop()! : id; - const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel; - return bareAvail === bareExplicit; - }); - if (match) return match; - } - - // 2. Auto-detect: find the cheapest available model in the requested tier - const candidates = availableModelIds - .filter(id => { - const modelTier = getModelTier(id); - return modelTier === tier; - }) - .sort((a, b) => { - if (!crossProvider) return 0; - const costA = getModelCost(a); - const costB = getModelCost(b); - return costA - costB; - }); - - return candidates[0] ?? null; -} - function getModelCost(modelId: string): number { const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId; @@ -279,3 +541,71 @@ function getModelCost(modelId: string): number { // Unknown cost — assume expensive to avoid routing to unknown cheap models return 999; } + +// ─── Tool Compatibility Filter (ADR-005 Phase 3) ─────────────────────────── + +/** + * Check if a tool is compatible with a provider's capabilities. + * Returns true if the tool can be used with the provider. + */ +export function isToolCompatibleWithProvider( + toolName: string, + providerCaps: ProviderCapabilities, +): boolean { + const compat = getToolCompatibility(toolName); + if (!compat) return true; // no metadata = always compatible + + // Hard filter: provider doesn't support image tool results + if (compat.producesImages && !providerCaps.imageToolResults) return false; + + // Hard filter: tool uses schema features provider doesn't support + if (compat.schemaFeatures?.some(f => providerCaps.unsupportedSchemaFeatures.includes(f))) { + return false; + } + + return true; +} + +/** + * Filter a list of tool names to only those compatible with a provider. + * Used by the routing pipeline to adjust tool sets when switching providers. + */ +export function filterToolsForProvider( + toolNames: string[], + providerApi: string, +): { compatible: string[]; filtered: string[] } { + const providerCaps = getProviderCapabilities(providerApi); + + // Provider doesn't support tool calling at all + if (!providerCaps.toolCalling) { + return { compatible: [], filtered: toolNames }; + } + + const compatible: string[] = []; + const filtered: string[] = []; + + for (const name of toolNames) { + if (isToolCompatibleWithProvider(name, providerCaps)) { + compatible.push(name); + } else { + filtered.push(name); + } + } + + return { compatible, filtered }; +} + +/** + * Adjust the active tool set for a selected model's provider capabilities. + * Returns tool names that should be active — removes incompatible tools. + * + * This is a hard filter only — it removes tools that would fail at the + * provider level. It does NOT remove tools based on soft heuristics. + */ +export function adjustToolSet( + activeToolNames: string[], + selectedModelApi: string, +): { toolNames: string[]; removedTools: string[] } { + const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi); + return { toolNames: compatible, removedTools: filtered }; +} diff --git a/src/resources/extensions/gsd/native-git-bridge.ts b/src/resources/extensions/gsd/native-git-bridge.ts index edfe81188..ad126332a 100644 --- a/src/resources/extensions/gsd/native-git-bridge.ts +++ b/src/resources/extensions/gsd/native-git-bridge.ts @@ -680,6 +680,16 @@ export function nativeAddAll(basePath: string): void { gitFileExec(basePath, ["add", "-A"]); } +/** + * Stage only already-tracked files (git add -u). + * Does NOT add new untracked files — only updates modifications and deletions + * for files git already knows about. Safe for automated snapshots where + * pulling in unknown untracked files (secrets, binaries) would be dangerous. + */ +export function nativeAddTracked(basePath: string): void { + gitFileExec(basePath, ["add", "-u"]); +} + /** * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...). * Excluded paths are never hashed by git, preventing hangs on large @@ -714,10 +724,12 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl return; } // When .gsd is a symlink, git rejects `:!.gsd/...` pathspecs with - // "beyond a symbolic link". Fall back to plain `git add -A` which - // respects .gitignore (where .gsd/ is listed by default). + // "beyond a symbolic link". Fall back to `git add -u` which only + // stages changes to already-tracked files — O(tracked) not O(filesystem). + // Using `git add -A` here would traverse the entire working tree, + // hanging indefinitely on repos with large untracked data dirs. (#1977) if (stderr.includes("beyond a symbolic link")) { - nativeAddAll(basePath); + gitFileExec(basePath, ["add", "-u"]); return; } throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`); @@ -931,6 +943,37 @@ export function nativeResetHard(basePath: string): void { execSync("git reset --hard HEAD", { cwd: basePath, stdio: "pipe" }); } +/** + * Soft reset to a target ref (git reset --soft ). + * Moves HEAD to `target` while keeping all changes staged in the index. + * Used to squash snapshot commits back into a single real commit. + */ +export function nativeResetSoft(basePath: string, target: string): void { + execFileSync("git", ["reset", "--soft", target], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + env: GIT_NO_PROMPT_ENV, + }); +} + +/** + * Get the subject line of a commit (git log -1 --format=%s ). + * Returns empty string if the ref doesn't exist. + */ +export function nativeCommitSubject(basePath: string, ref: string): string { + try { + return execFileSync("git", ["log", "-1", "--format=%s", ref], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + env: GIT_NO_PROMPT_ENV, + }).trim(); + } catch { + return ""; + } +} + /** * Delete a branch. * Native: libgit2 branch delete. diff --git a/src/resources/extensions/gsd/notification-overlay.ts b/src/resources/extensions/gsd/notification-overlay.ts new file mode 100644 index 000000000..1b5e3bec5 --- /dev/null +++ b/src/resources/extensions/gsd/notification-overlay.ts @@ -0,0 +1,295 @@ +// GSD Extension — Notification History Overlay +// Scrollable panel showing all persisted notifications with severity filtering. +// Toggled with Ctrl+Alt+N (⌃⌥N on macOS) or opened from /gsd notifications. + +import type { Theme } from "@gsd/pi-coding-agent"; +import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui"; + +import { + readNotifications, + markAllRead, + clearNotifications, + getUnreadCount, + type NotificationEntry, + type NotifySeverity, +} from "./notification-store.js"; +import { padRight, centerLine, joinColumns, formatDuration } from "../shared/mod.js"; + +type FilterMode = "all" | "error" | "warning" | "info"; +const FILTER_CYCLE: FilterMode[] = ["all", "error", "warning", "info"]; + +function severityIcon(severity: NotifySeverity): string { + switch (severity) { + case "error": return "✗"; + case "warning": return "⚠"; + case "success": return "✓"; + case "info": + default: return "●"; + } +} + +/** Word-wrap plain text to fit within maxWidth columns. */ +function wrapText(text: string, maxWidth: number): string[] { + if (text.length <= maxWidth) return [text]; + const words = text.split(/\s+/); + const lines: string[] = []; + let current = ""; + for (const word of words) { + if (current.length === 0) { + current = word; + } else if (current.length + 1 + word.length <= maxWidth) { + current += " " + word; + } else { + lines.push(current); + current = word; + } + } + if (current.length > 0) lines.push(current); + // If a single word exceeds maxWidth, truncate it + return lines.map((l) => l.length > maxWidth ? l.slice(0, maxWidth - 1) + "…" : l); +} + +function formatTimestamp(ts: string): string { + try { + const d = new Date(ts); + const now = Date.now(); + const diffMs = now - d.getTime(); + if (diffMs < 60_000) return "just now"; + if (diffMs < 3600_000) return `${Math.floor(diffMs / 60_000)}m ago`; + if (diffMs < 86400_000) return `${Math.floor(diffMs / 3600_000)}h ago`; + return `${Math.floor(diffMs / 86400_000)}d ago`; + } catch { + return ts.slice(11, 19); // fallback: HH:MM:SS + } +} + +export class GSDNotificationOverlay { + private tui: { requestRender: () => void }; + private theme: Theme; + private onClose: () => void; + private cachedWidth?: number; + private cachedLines?: string[]; + private scrollOffset = 0; + private filterIndex = 0; + private entries: NotificationEntry[] = []; + private refreshTimer: ReturnType; + private disposed = false; + private resizeHandler: (() => void) | null = null; + + constructor( + tui: { requestRender: () => void }, + theme: Theme, + onClose: () => void, + ) { + this.tui = tui; + this.theme = theme; + this.onClose = onClose; + + // Mark all as read on open + markAllRead(); + this.entries = readNotifications(); + + // Resize handler + this.resizeHandler = () => { + if (this.disposed) return; + this.invalidate(); + this.tui.requestRender(); + }; + process.stdout.on("resize", this.resizeHandler); + + // Refresh every 3s for new notifications + this.refreshTimer = setInterval(() => { + if (this.disposed) return; + const fresh = readNotifications(); + if (fresh.length !== this.entries.length) { + this.entries = fresh; + markAllRead(); + this.invalidate(); + this.tui.requestRender(); + } + }, 3000); + } + + private get filter(): FilterMode { + return FILTER_CYCLE[this.filterIndex]!; + } + + private get filteredEntries(): NotificationEntry[] { + if (this.filter === "all") return this.entries; + return this.entries.filter((e) => e.severity === this.filter); + } + + handleInput(data: string): void { + if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c")) || matchesKey(data, Key.ctrlAlt("n"))) { + this.dispose(); + this.onClose(); + return; + } + + // Scroll + if (matchesKey(data, Key.down) || matchesKey(data, "j")) { + this.scrollOffset++; + this.invalidate(); + this.tui.requestRender(); + return; + } + if (matchesKey(data, Key.up) || matchesKey(data, "k")) { + this.scrollOffset = Math.max(0, this.scrollOffset - 1); + this.invalidate(); + this.tui.requestRender(); + return; + } + if (data === "g") { + this.scrollOffset = 0; + this.invalidate(); + this.tui.requestRender(); + return; + } + if (data === "G") { + this.scrollOffset = 999; + this.invalidate(); + this.tui.requestRender(); + return; + } + + // Filter cycle + if (data === "f") { + this.filterIndex = (this.filterIndex + 1) % FILTER_CYCLE.length; + this.scrollOffset = 0; + this.invalidate(); + this.tui.requestRender(); + return; + } + + // Clear all + if (data === "c") { + clearNotifications(); + this.entries = []; + this.scrollOffset = 0; + this.invalidate(); + this.tui.requestRender(); + return; + } + } + + render(width: number): string[] { + if (this.cachedLines && this.cachedWidth === width) { + return this.cachedLines; + } + + const content = this.buildContentLines(width); + const maxVisibleRows = Math.max(5, process.stdout.rows ? process.stdout.rows - 8 : 24) - 2; + const visibleContentRows = Math.min(content.length, maxVisibleRows); + const maxScroll = Math.max(0, content.length - visibleContentRows); + this.scrollOffset = Math.min(this.scrollOffset, maxScroll); + const visibleContent = content.slice(this.scrollOffset, this.scrollOffset + visibleContentRows); + + const lines = this.wrapInBox(visibleContent, width); + + this.cachedWidth = width; + this.cachedLines = lines; + return lines; + } + + invalidate(): void { + this.cachedLines = undefined; + this.cachedWidth = undefined; + } + + dispose(): void { + this.disposed = true; + clearInterval(this.refreshTimer); + if (this.resizeHandler) { + process.stdout.removeListener("resize", this.resizeHandler); + this.resizeHandler = null; + } + } + + private wrapInBox(inner: string[], width: number): string[] { + const th = this.theme; + const border = (s: string) => th.fg("borderAccent", s); + const innerWidth = width - 4; + const lines: string[] = []; + + lines.push(border("╭" + "─".repeat(width - 2) + "╮")); + for (const line of inner) { + const truncated = truncateToWidth(line, innerWidth); + const padWidth = Math.max(0, innerWidth - visibleWidth(truncated)); + lines.push(border("│") + " " + truncated + " ".repeat(padWidth) + " " + border("│")); + } + lines.push(border("╰" + "─".repeat(width - 2) + "╯")); + return lines; + } + + private buildContentLines(width: number): string[] { + const th = this.theme; + const shellWidth = width - 4; + const contentWidth = Math.min(shellWidth, 128); + const sidePad = Math.max(0, Math.floor((shellWidth - contentWidth) / 2)); + const leftMargin = " ".repeat(sidePad); + const lines: string[] = []; + + const row = (content = ""): string => { + const truncated = truncateToWidth(content, contentWidth); + return leftMargin + padRight(truncated, contentWidth); + }; + const blank = () => row(""); + const hr = () => row(th.fg("dim", "─".repeat(contentWidth))); + + // Header + const title = th.fg("accent", th.bold("Notifications")); + const filterLabel = this.filter === "all" + ? th.fg("dim", "all") + : th.fg(this.filter === "error" ? "error" : this.filter === "warning" ? "warning" : "dim", this.filter); + const count = `${this.filteredEntries.length} entries`; + lines.push(row(joinColumns( + `${title} ${th.fg("dim", "filter:")} ${filterLabel}`, + th.fg("dim", count), + contentWidth, + ))); + lines.push(hr()); + + // Controls + lines.push(row(th.fg("dim", "↑/↓ scroll f filter c clear Esc close"))); + lines.push(blank()); + + // Entries + const filtered = this.filteredEntries; + if (filtered.length === 0) { + lines.push(blank()); + lines.push(row(th.fg("dim", this.entries.length === 0 + ? "No notifications yet." + : `No ${this.filter} notifications.`))); + lines.push(blank()); + return lines; + } + + for (const entry of filtered) { + const icon = severityIcon(entry.severity); + const coloredIcon = entry.severity === "error" ? th.fg("error", icon) + : entry.severity === "warning" ? th.fg("warning", icon) + : entry.severity === "success" ? th.fg("success", icon) + : th.fg("dim", icon); + const time = th.fg("dim", formatTimestamp(entry.ts)); + const source = entry.source === "workflow-logger" ? th.fg("dim", " [engine]") : ""; + + // Measure actual prefix width for wrapping + const prefix = `${coloredIcon} ${time}${source} `; + const prefixWidth = visibleWidth(prefix); + const msgMaxWidth = Math.max(10, contentWidth - prefixWidth); + + // Wrap long messages onto continuation lines indented to align with message start + const msgLines = wrapText(entry.message, msgMaxWidth); + const indent = " ".repeat(prefixWidth); + for (let i = 0; i < msgLines.length; i++) { + if (i === 0) { + lines.push(row(`${prefix}${msgLines[i]}`)); + } else { + lines.push(row(`${indent}${msgLines[i]}`)); + } + } + } + + return lines; + } +} diff --git a/src/resources/extensions/gsd/notification-store.ts b/src/resources/extensions/gsd/notification-store.ts new file mode 100644 index 000000000..50484597f --- /dev/null +++ b/src/resources/extensions/gsd/notification-store.ts @@ -0,0 +1,311 @@ +// GSD Extension — Persistent Notification Store +// Captures all ctx.ui.notify() calls and workflow-logger warnings to +// .gsd/notifications.jsonl so they survive context resets and session restarts. +// Rotates at MAX_ENTRIES to prevent unbounded growth. + +import { appendFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { randomUUID } from "node:crypto"; + +// ─── Types ────────────────────────────────────────────────────────────── + +export type NotifySeverity = "info" | "success" | "warning" | "error"; +export type NotificationSource = "notify" | "workflow-logger"; + +export interface NotificationEntry { + id: string; + ts: string; + severity: NotifySeverity; + message: string; + source: NotificationSource; + read: boolean; +} + +// ─── Constants ────────────────────────────────────────────────────────── + +const MAX_ENTRIES = 500; +const FILENAME = "notifications.jsonl"; +const LOCKFILE = "notifications.lock"; +const DEDUP_WINDOW_MS = 30_000; +const DEDUP_PRUNE_THRESHOLD = 200; + +// ─── Module State ─────────────────────────────────────────────────────── + +let _basePath: string | null = null; +let _lineCount = 0; // Hint for rotation — not authoritative for public API +let _suppressCount = 0; +let _recentMessageTimestamps = new Map(); + +// ─── Public API ───────────────────────────────────────────────────────── + +/** + * Initialize the notification store. Call once at session start with the + * project root. Seeds in-memory counters from the existing file on disk. + */ +export function initNotificationStore(basePath: string): void { + if (_basePath !== basePath) { + _recentMessageTimestamps.clear(); + } + _basePath = basePath; + // Seed line count hint for rotation — public counters read from disk + _lineCount = _readEntriesFromDisk(basePath).length; +} + +/** + * Append a notification entry to the store. Synchronous — safe to call + * from the notify() shim which is declared void (not async). + */ +export function appendNotification( + message: string, + severity: NotifySeverity, + source: NotificationSource = "notify", +): void { + if (!_basePath) return; + if (_suppressCount > 0) return; + const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message; + const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`; + const now = Date.now(); + const lastSeen = _recentMessageTimestamps.get(dedupKey); + if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS) return; + _recentMessageTimestamps.set(dedupKey, now); + if (_recentMessageTimestamps.size > DEDUP_PRUNE_THRESHOLD) { + for (const [key, ts] of _recentMessageTimestamps) { + if (now - ts > DEDUP_WINDOW_MS) _recentMessageTimestamps.delete(key); + } + } + + const entry: NotificationEntry = { + id: randomUUID(), + ts: new Date().toISOString(), + severity, + message: persistedMessage, + source, + read: false, + }; + + try { + const dir = join(_basePath, ".gsd"); + mkdirSync(dir, { recursive: true }); + appendFileSync(join(dir, FILENAME), JSON.stringify(entry) + "\n", "utf-8"); + _lineCount++; + + // Rotate if hint suggests we're over limit + if (_lineCount > MAX_ENTRIES) { + _rotate(); + } + } catch { + // Non-fatal — never let persistence break the caller + } +} + +/** + * Read all notification entries from disk. Returns newest-first. + */ +export function readNotifications(basePath?: string): NotificationEntry[] { + const bp = basePath ?? _basePath; + if (!bp) return []; + return _readEntriesFromDisk(bp).reverse(); +} + +/** + * Mark all notifications as read. Atomic rewrite via temp-file + rename. + * Resyncs in-memory counters from disk after mutation. + */ +export function markAllRead(basePath?: string): void { + const bp = basePath ?? _basePath; + if (!bp) return; + + const entries = _readEntriesFromDisk(bp); + if (entries.length === 0) return; + + const hasUnread = entries.some((e) => !e.read); + if (!hasUnread) return; + + try { + _withLock(bp, () => { + // Re-read inside lock to get freshest state + const fresh = _readEntriesFromDisk(bp); + if (fresh.length === 0 || !fresh.some((e) => !e.read)) return; + const lines = fresh.map((e) => JSON.stringify({ ...e, read: true })); + _atomicWrite(bp, lines.join("\n") + "\n"); + }); + } catch { + // Non-fatal + } +} + +/** + * Clear all notifications. Atomic write of empty content under lock. + */ +export function clearNotifications(basePath?: string): void { + const bp = basePath ?? _basePath; + if (!bp) return; + + try { + _withLock(bp, () => { + _atomicWrite(bp, ""); + }); + } catch { + // Non-fatal + } +} + +/** + * Get the current unread count. Reads from disk to stay accurate across + * processes (web subprocess can clear/modify the file independently). + */ +export function getUnreadCount(): number { + if (!_basePath) return 0; + try { + const entries = _readEntriesFromDisk(_basePath); + return entries.filter((e) => !e.read).length; + } catch { + return 0; + } +} + +/** + * Get the total notification count. Reads from disk for cross-process accuracy. + */ +export function getLineCount(): number { + if (!_basePath) return 0; + try { + return _readEntriesFromDisk(_basePath).length; + } catch { + return 0; + } +} + +/** + * Temporarily suppress persistence. Use around ctx.ui.notify calls that + * should NOT be persisted (e.g., confirmation toasts after clear). + * Calls are ref-counted — nest safely. + */ +export function suppressPersistence(): void { + _suppressCount++; +} + +export function unsuppressPersistence(): void { + _suppressCount = Math.max(0, _suppressCount - 1); +} + +// ─── Test Helpers ─────────────────────────────────────────────────────── + +/** + * Reset module state. Only for use in tests. + */ +export function _resetNotificationStore(): void { + _basePath = null; + _lineCount = 0; + _suppressCount = 0; + _recentMessageTimestamps = new Map(); +} + +// ─── Internal ─────────────────────────────────────────────────────────── + +function _readEntriesFromDisk(basePath: string): NotificationEntry[] { + const filePath = join(basePath, ".gsd", FILENAME); + if (!existsSync(filePath)) return []; + try { + const content = readFileSync(filePath, "utf-8"); + return content + .split("\n") + .filter((l) => l.length > 0) + .map((l) => { + try { + return JSON.parse(l) as NotificationEntry; + } catch { + return null; + } + }) + .filter((e): e is NotificationEntry => e !== null); + } catch { + return []; + } +} + +function _rotate(): void { + if (!_basePath) return; + try { + _withLock(_basePath, () => { + // Re-read inside lock to get freshest state + const entries = _readEntriesFromDisk(_basePath!); + if (entries.length <= MAX_ENTRIES) return; + const trimmed = entries.slice(entries.length - MAX_ENTRIES); + const lines = trimmed.map((e) => JSON.stringify(e)); + _atomicWrite(_basePath!, lines.join("\n") + "\n"); + }); + } catch { + // Non-fatal + } +} + +/** + * Atomic file rewrite via temp-file + rename. Prevents partial reads + * by other processes (web API subprocess, parallel workers). + * Must be called inside _withLock for cross-process safety. + */ +function _atomicWrite(basePath: string, content: string): void { + const dir = join(basePath, ".gsd"); + mkdirSync(dir, { recursive: true }); + const target = join(dir, FILENAME); + const tmp = target + ".tmp." + process.pid; + writeFileSync(tmp, content, "utf-8"); + renameSync(tmp, target); +} + +/** + * Acquire an exclusive lockfile for rewrite operations. + * Uses O_CREAT|O_EXCL for atomic creation — if the file exists, another + * process holds the lock. Retries briefly, then proceeds anyway (best-effort) + * to avoid deadlocking the UI on a stale lock. + */ +function _withLock(basePath: string, fn: () => T): T { + const lockPath = join(basePath, ".gsd", LOCKFILE); + let fd: number | null = null; + const maxAttempts = 5; + const retryMs = 20; + + for (let i = 0; i < maxAttempts; i++) { + try { + mkdirSync(join(basePath, ".gsd"), { recursive: true }); + fd = openSync(lockPath, "wx"); + break; + } catch (err: any) { + if (err?.code === "EEXIST") { + // Check if lock is stale (older than 5s) + try { + const stat = readFileSync(lockPath, "utf-8"); + const lockTime = parseInt(stat, 10); + if (Date.now() - lockTime > 5000) { + try { unlinkSync(lockPath); } catch { /* race ok */ } + continue; + } + } catch { /* can't read lock, retry */ } + + // Wait and retry + const start = Date.now(); + while (Date.now() - start < retryMs) { /* spin */ } + continue; + } + // Other error — proceed without lock + break; + } + } + + // Only run the mutation if we actually own the lock + const ownsLock = fd !== null; + try { + if (ownsLock && fd !== null) { + // Write our PID timestamp into the lock for stale detection + writeFileSync(lockPath, String(Date.now()), "utf-8"); + closeSync(fd); + } + return fn(); + } finally { + // Only delete the lock if we created it — never remove another process's lock + if (ownsLock) { + try { unlinkSync(lockPath); } catch { /* best-effort cleanup */ } + } + } +} diff --git a/src/resources/extensions/gsd/notification-widget.ts b/src/resources/extensions/gsd/notification-widget.ts new file mode 100644 index 000000000..648e2af65 --- /dev/null +++ b/src/resources/extensions/gsd/notification-widget.ts @@ -0,0 +1,69 @@ +// GSD Extension — Notification Widget +// Always-on ambient widget rendered belowEditor showing unread count and +// the most recent notification message. Refreshes every 5 seconds. +// Widget key: "gsd-notifications", placement: "belowEditor" + +import type { ExtensionContext } from "@gsd/pi-coding-agent"; + +import { getUnreadCount, readNotifications } from "./notification-store.js"; +import { formatShortcut } from "./files.js"; + +// ─── Pure rendering ──���────────────────────────���───────────────────────── + +export function buildNotificationWidgetLines(): string[] { + const unread = getUnreadCount(); + if (unread === 0) return []; + + const entries = readNotifications(); + const latest = entries[0]; // newest-first + if (!latest) return []; + + const icon = latest.severity === "error" ? "✗" : latest.severity === "warning" ? "⚠" : "●"; + const badge = `${unread} unread`; + const msgMax = 80; + const truncated = latest.message.length > msgMax + ? latest.message.slice(0, msgMax - 1) + "…" + : latest.message; + + return [` ${icon} [${badge}] ${truncated} (${formatShortcut("Ctrl+Alt+N")} or /gsd notifications)`]; +} + +// ─── Widget init ──────────────────────────────────────────────────────── + +const REFRESH_INTERVAL_MS = 5_000; + +/** + * Initialize the always-on notification widget (belowEditor). + * Call once from session_start after the notification store is initialized. + */ +export function initNotificationWidget(ctx: ExtensionContext): void { + if (!ctx.hasUI) return; + + // String-array fallback for RPC mode + ctx.ui.setWidget("gsd-notifications", buildNotificationWidgetLines(), { placement: "belowEditor" }); + + // Factory-based widget for TUI mode + ctx.ui.setWidget("gsd-notifications", (_tui, _theme) => { + let cachedLines: string[] | undefined; + + const refresh = () => { + cachedLines = undefined; + _tui.requestRender(); + }; + + const refreshTimer = setInterval(refresh, REFRESH_INTERVAL_MS); + + return { + render(_width: number): string[] { + if (!cachedLines) cachedLines = buildNotificationWidgetLines(); + return cachedLines; + }, + invalidate(): void { + cachedLines = undefined; + }, + dispose(): void { + clearInterval(refreshTimer); + }, + }; + }, { placement: "belowEditor" }); +} diff --git a/src/resources/extensions/gsd/notifications.ts b/src/resources/extensions/gsd/notifications.ts index 4a45eae94..0efd0d4c3 100644 --- a/src/resources/extensions/gsd/notifications.ts +++ b/src/resources/extensions/gsd/notifications.ts @@ -23,7 +23,13 @@ export function sendDesktopNotification( message: string, level: NotifyLevel = "info", kind: NotificationKind = "complete", + projectName?: string, ): void { + // When a projectName is provided and the title is the default "GSD", + // replace it with a project-qualified title for multi-project clarity. + if (projectName && title === "GSD") { + title = formatNotificationTitle(projectName); + } const loaded = loadEffectiveGSDPreferences()?.preferences; if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return; @@ -64,6 +70,16 @@ export function shouldSendDesktopNotification( } } +/** + * Format a notification title that includes the project name for context. + * Returns "GSD — projectName" when a project name is available, otherwise "GSD". + */ +export function formatNotificationTitle(projectName?: string): string { + const trimmed = projectName?.trim(); + if (trimmed) return `GSD — ${trimmed}`; + return "GSD"; +} + export function buildDesktopNotificationCommand( platform: NodeJS.Platform, title: string, diff --git a/src/resources/extensions/gsd/parallel-eligibility.ts b/src/resources/extensions/gsd/parallel-eligibility.ts index 20e4a2327..ea30521b9 100644 --- a/src/resources/extensions/gsd/parallel-eligibility.ts +++ b/src/resources/extensions/gsd/parallel-eligibility.ts @@ -112,7 +112,20 @@ export async function analyzeParallelEligibility( for (const mid of milestoneIds) { const entry = registryMap.get(mid); const title = entry?.title ?? mid; - const status = entry?.status ?? "pending"; + + // Rule 0: milestones with no registry entry (ghost directories, unknown + // state) are ineligible — we cannot determine their status or deps (#2501) + if (!entry) { + ineligible.push({ + milestoneId: mid, + title, + eligible: false, + reason: "Milestone has no planning data — cannot determine eligibility.", + }); + continue; + } + + const status = entry.status; // Rule 1: skip complete and parked milestones if (status === "complete" || status === "parked") { @@ -126,7 +139,7 @@ export async function analyzeParallelEligibility( } // Rule 2: check dependency satisfaction - const deps = entry?.dependsOn ?? []; + const deps = entry.dependsOn ?? []; const unsatisfied = deps.filter(dep => { const depEntry = registryMap.get(dep); return !depEntry || depEntry.status !== "complete"; diff --git a/src/resources/extensions/gsd/parallel-merge.ts b/src/resources/extensions/gsd/parallel-merge.ts index 74b526fdd..09a179869 100644 --- a/src/resources/extensions/gsd/parallel-merge.ts +++ b/src/resources/extensions/gsd/parallel-merge.ts @@ -5,6 +5,9 @@ * with safety checks for parallel execution context. */ +import { existsSync, readdirSync } from "node:fs"; +import { join } from "node:path"; +import { spawnSync } from "node:child_process"; import { loadFile } from "./files.js"; import { resolveMilestoneFile } from "./paths.js"; import { mergeMilestoneToMain } from "./auto-worktree.js"; @@ -12,6 +15,7 @@ import { MergeConflictError } from "./git-service.js"; import { removeSessionStatus } from "./session-status-io.js"; import type { WorkerInfo } from "./parallel-orchestrator.js"; import { getErrorMessage } from "./error-utils.js"; +import { logWarning } from "./workflow-logger.js"; // ─── Types ───────────────────────────────────────────────────────────────── @@ -28,22 +32,103 @@ export type MergeOrder = "sequential" | "by-completion"; // ─── Merge Queue ─────────────────────────────────────────────────────────── +/** + * Check whether a milestone is complete by querying its worktree SQLite DB. + * Uses a subprocess to avoid disrupting the global DB singleton. + * Returns true when milestones.status = 'complete' in the worktree's gsd.db. + */ +export function isMilestoneCompleteInWorktreeDb(basePath: string, mid: string): boolean { + const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db"); + if (!existsSync(dbPath)) return false; + + try { + const result = spawnSync( + "sqlite3", + [dbPath, `SELECT status FROM milestones WHERE id='${mid}' LIMIT 1`], + { timeout: 3000, encoding: "utf-8" }, + ); + return (result.stdout || "").trim() === "complete"; + } catch (e) { + logWarning("parallel", `spawnSync milestone completion check failed for ${mid}: ${(e as Error).message}`); + return false; + } +} + +/** + * Discover milestone IDs with status='complete' in their worktree DB, + * scanning .gsd/worktrees//.gsd/gsd.db for each worktree directory. + */ +function discoverDbCompletedMilestones(basePath: string): Set { + const completed = new Set(); + const worktreeDir = join(basePath, ".gsd", "worktrees"); + try { + for (const entry of readdirSync(worktreeDir)) { + if (entry.startsWith("M") && isMilestoneCompleteInWorktreeDb(basePath, entry)) { + completed.add(entry); + } + } + } catch (e) { + logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`); + } + return completed; +} + /** * Determine safe merge order for completed milestones. * Sequential: merge in milestone ID order (M001 before M002). * By-completion: merge in the order milestones finished. + * + * When basePath is provided, also checks worktree SQLite DBs as the + * source of truth — workers with stale orchestrator state (e.g. "error") + * are included if their worktree DB shows status='complete'. + * See: https://github.com/gsd-build/gsd-2/issues/2812 */ export function determineMergeOrder( workers: WorkerInfo[], order: MergeOrder = "sequential", + basePath?: string, ): string[] { - const completed = workers.filter(w => w.state === "stopped"); + // Start with workers the orchestrator already knows are stopped + const stoppedIds = new Set( + workers.filter(w => w.state === "stopped").map(w => w.milestoneId), + ); + + // When basePath is available, also check worktree DBs for milestones + // whose orchestrator state is stale but are actually complete (#2812) + const dbCompleted = basePath ? discoverDbCompletedMilestones(basePath) : new Set(); + + // Union: milestone is mergeable if stopped OR DB-complete + const mergeableIds = new Set([...stoppedIds, ...dbCompleted]); + + // Build the list from tracked workers + any DB-discovered milestones + // not tracked by the orchestrator at all + const workerMap = new Map(workers.map(w => [w.milestoneId, w])); + const allMergeable: WorkerInfo[] = []; + for (const mid of mergeableIds) { + const w = workerMap.get(mid); + if (w) { + allMergeable.push(w); + } else { + // Milestone discovered from worktree DB but not in workers list + allMergeable.push({ + milestoneId: mid, + title: mid, + pid: 0, + process: null, + worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "", + startedAt: 0, + state: "stopped", + cost: 0, + }); + } + } + if (order === "by-completion") { - return completed + return allMergeable .sort((a, b) => a.startedAt - b.startedAt) // earliest first .map(w => w.milestoneId); } - return completed + return allMergeable .sort((a, b) => a.milestoneId.localeCompare(b.milestoneId)) .map(w => w.milestoneId); } @@ -114,7 +199,7 @@ export async function mergeAllCompleted( workers: WorkerInfo[], order: MergeOrder = "sequential", ): Promise { - const mergeOrder = determineMergeOrder(workers, order); + const mergeOrder = determineMergeOrder(workers, order, basePath); const results: MergeResult[] = []; for (const mid of mergeOrder) { diff --git a/src/resources/extensions/gsd/parallel-monitor-overlay.ts b/src/resources/extensions/gsd/parallel-monitor-overlay.ts index 4b671f973..d56623621 100644 --- a/src/resources/extensions/gsd/parallel-monitor-overlay.ts +++ b/src/resources/extensions/gsd/parallel-monitor-overlay.ts @@ -2,7 +2,7 @@ * GSD Parallel Monitor Overlay * * Full-screen TUI overlay showing real-time parallel worker progress. - * Opened via `/gsd parallel watch` or Ctrl+Alt+P. + * Opened via `/gsd parallel watch` or Ctrl+Alt+P (⌃⌥P on macOS). * Reads the same data sources as `scripts/parallel-monitor.mjs` but * renders as a native pi-tui overlay with theme integration. */ @@ -490,6 +490,8 @@ export class ParallelMonitorOverlay { // Apply scroll — use terminal rows as height estimate const termHeight = process.stdout.rows || 40; + const maxScroll = Math.max(0, lines.length - termHeight); + this.scrollOffset = Math.min(Math.max(this.scrollOffset, 0), maxScroll); const visible = lines.slice(this.scrollOffset, this.scrollOffset + termHeight); this.cachedLines = visible; return visible; diff --git a/src/resources/extensions/gsd/parallel-orchestrator.ts b/src/resources/extensions/gsd/parallel-orchestrator.ts index 95b87d738..689de6ce2 100644 --- a/src/resources/extensions/gsd/parallel-orchestrator.ts +++ b/src/resources/extensions/gsd/parallel-orchestrator.ts @@ -41,6 +41,7 @@ import { type ParallelCandidates, } from "./parallel-eligibility.js"; import { getErrorMessage } from "./error-utils.js"; +import { logWarning } from "./workflow-logger.js"; // ─── Types ───────────────────────────────────────────────────────────────── @@ -126,7 +127,7 @@ export function persistState(basePath: string): void { const tmp = dest + TMP_SUFFIX; writeFileSync(tmp, JSON.stringify(persisted, null, 2), "utf-8"); renameSync(tmp, dest); - } catch { /* non-fatal */ } + } catch (e) { logWarning("parallel", `persist parallel state failed: ${(e as Error).message}`); } } /** @@ -136,7 +137,7 @@ function removeStateFile(basePath: string): void { try { const p = stateFilePath(basePath); if (existsSync(p)) unlinkSync(p); - } catch { /* non-fatal */ } + } catch (e) { logWarning("parallel", `clear parallel state file failed: ${(e as Error).message}`); } } function isPidAlive(pid: number): boolean { @@ -144,7 +145,8 @@ function isPidAlive(pid: number): boolean { try { process.kill(pid, 0); return true; - } catch { + } catch (e) { + logWarning("parallel", `pid alive check failed for pid ${pid}: ${(e as Error).message}`); return false; } } @@ -176,7 +178,8 @@ export function restoreState(basePath: string): PersistedState | null { } return persisted; - } catch { + } catch (e) { + logWarning("parallel", `readParallelState JSON parse failed: ${(e as Error).message}`); return null; } } @@ -190,8 +193,8 @@ function appendWorkerLog(basePath: string, milestoneId: string, chunk: string): const dir = join(gsdRoot(basePath), "parallel"); if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); appendFileSync(workerLogPath(basePath, milestoneId), chunk, "utf-8"); - } catch { - // Non-fatal — diagnostics should never break orchestration. + } catch (e) { + logWarning("parallel", `appendFileSync worker log failed for ${milestoneId}: ${(e as Error).message}`); } } @@ -430,9 +433,8 @@ export async function startParallel( let wtPath: string; try { wtPath = createMilestoneWorktree(basePath, mid); - } catch { - // Worktree creation may fail in test environments or when git - // is not available. Fall back to a placeholder path. + } catch (e) { + logWarning("parallel", `createMilestoneWorktree fallback for ${mid}: ${(e as Error).message}`); wtPath = worktreePath(basePath, mid); } @@ -548,23 +550,32 @@ export function spawnWorker( let child: ChildProcess; try { + const workerEnv: Record = { + ...process.env, + GSD_MILESTONE_LOCK: milestoneId, + // Pass the real project root so workers don't need to re-derive it. + // Without this, process.cwd() resolves symlinks and the worktree + // path heuristic can match the user-level ~/.gsd instead of the + // project .gsd, causing writes to ~ and corrupting user config. + GSD_PROJECT_ROOT: basePath, + // Prevent workers from spawning their own parallel sessions + GSD_PARALLEL_WORKER: "1", + }; + + // Apply worker model override if configured, so workers use a cheaper + // model (e.g. Haiku) rather than inheriting the coordinator's model. + if (state.config.worker_model) { + workerEnv.GSD_WORKER_MODEL = state.config.worker_model; + } + child = spawn(process.execPath, [binPath, "headless", "--json", "auto"], { cwd: worker.worktreePath, - env: { - ...process.env, - GSD_MILESTONE_LOCK: milestoneId, - // Pass the real project root so workers don't need to re-derive it. - // Without this, process.cwd() resolves symlinks and the worktree - // path heuristic can match the user-level ~/.gsd instead of the - // project .gsd, causing writes to ~ and corrupting user config. - GSD_PROJECT_ROOT: basePath, - // Prevent workers from spawning their own parallel sessions - GSD_PARALLEL_WORKER: "1", - }, + env: workerEnv, stdio: ["ignore", "pipe", "pipe"], detached: false, }); - } catch { + } catch (e) { + logWarning("parallel", `spawnSync worker failed for ${milestoneId}: ${(e as Error).message}`); return false; } @@ -694,7 +705,8 @@ function resolveGsdBin(): string | null { let thisDir: string; try { thisDir = dirname(fileURLToPath(import.meta.url)); - } catch { + } catch (e) { + logWarning("parallel", `dirname(fileURLToPath) failed: ${(e as Error).message}`); thisDir = process.cwd(); } const candidates = [ @@ -722,7 +734,7 @@ function processWorkerLine(basePath: string, milestoneId: string, line: string): try { event = JSON.parse(line); } catch { - return; // Not valid JSON — skip (stderr leakage, debug output, etc.) + return; // Non-NDJSON lines (progress text, tool output) are expected — silent drop } const type = String(event.type ?? ""); @@ -817,7 +829,7 @@ export async function stopParallel( } else if (worker.pid !== process.pid) { process.kill(worker.pid, "SIGTERM"); } - } catch { /* process may already be dead */ } + } catch (e) { logWarning("parallel", `process.kill SIGTERM failed for pid ${worker.pid}: ${(e as Error).message}`); } } // Wait for the headless process to cascade SIGTERM to its RPC child. @@ -833,7 +845,7 @@ export async function stopParallel( } else if (worker.pid !== process.pid) { process.kill(worker.pid, "SIGKILL"); } - } catch { /* process may already be dead */ } + } catch (e) { logWarning("parallel", `process.kill SIGKILL failed for pid ${worker.pid}: ${(e as Error).message}`); } await waitForWorkerExit(worker, 250); } diff --git a/src/resources/extensions/gsd/parsers-legacy.ts b/src/resources/extensions/gsd/parsers-legacy.ts index c1a00e554..00ecb00c5 100644 --- a/src/resources/extensions/gsd/parsers-legacy.ts +++ b/src/resources/extensions/gsd/parsers-legacy.ts @@ -196,18 +196,30 @@ function _parsePlanImpl(content: string): SlicePlan { const mhSection = extractSection(body, 'Must-Haves'); const mustHaves = mhSection ? parseBullets(mhSection) : []; + // Parse tasks from ## Tasks section first, then scan the full body for any + // task checkboxes that were missed. Multi-task plans can interleave T01 detail + // headings (## Steps, ## Must-Haves) before T02's checkbox, which causes + // extractSection("Tasks") to stop at the first ## heading and miss T02+ (#3105). const tasksSection = extractSection(body, 'Tasks'); const tasks: TaskPlanEntry[] = []; - if (tasksSection) { - const taskLines = tasksSection.split('\n'); + // Parse task entries from a set of lines, appending to `tasks`. + const parseTaskLines = (lines: string[], knownIds: Set): void => { let currentTask: TaskPlanEntry | null = null; - for (const line of taskLines) { + for (const line of lines) { const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/); // Heading-style: ### T01 -- Title, ### T01: Title, ### T01 — Title - const hdMatch = !cbMatch ? line.match(/^#{2,4}\s+([\w.]+)\s*(?:--|—|:)\s*(.+)/) : null; + const hdMatch = !cbMatch + ? line.match(/^#{2,4}\s+([A-Z]+\d+(?:\.[A-Z]+\d+)*)\s*(?:--|—|:)\s*(.+)/) + : null; if (cbMatch || hdMatch) { + const taskId = cbMatch ? cbMatch[2] : hdMatch![1]; + // Skip tasks already found in the Tasks section + if (knownIds.has(taskId)) { + currentTask = null; + continue; + } if (currentTask) tasks.push(currentTask); if (cbMatch) { @@ -259,8 +271,17 @@ function _parsePlanImpl(content: string): SlicePlan { } } if (currentTask) tasks.push(currentTask); + }; + + if (tasksSection) { + parseTaskLines(tasksSection.split('\n'), new Set()); } + // Second pass: scan the full body for task checkboxes outside ## Tasks. + // This handles interleaved plans where T02+ appear after T01's detail headings. + const foundIds = new Set(tasks.map(t => t.id)); + parseTaskLines(body.split('\n'), foundIds); + const filesSection = extractSection(body, 'Files Likely Touched'); const filesLikelyTouched = filesSection ? parseBullets(filesSection) : []; diff --git a/src/resources/extensions/gsd/paths.ts b/src/resources/extensions/gsd/paths.ts index ccd3c59f6..8beaefdaa 100644 --- a/src/resources/extensions/gsd/paths.ts +++ b/src/resources/extensions/gsd/paths.ts @@ -264,6 +264,7 @@ export const GSD_ROOT_FILES = { REQUIREMENTS: "REQUIREMENTS.md", OVERRIDES: "OVERRIDES.md", KNOWLEDGE: "KNOWLEDGE.md", + CODEBASE: "CODEBASE.md", } as const; export type GSDRootFileKey = keyof typeof GSD_ROOT_FILES; @@ -276,6 +277,7 @@ const LEGACY_GSD_ROOT_FILES: Record = { REQUIREMENTS: "requirements.md", OVERRIDES: "overrides.md", KNOWLEDGE: "knowledge.md", + CODEBASE: "codebase.md", }; // ─── GSD Root Discovery ─────────────────────────────────────────────────────── @@ -307,16 +309,58 @@ export function gsdRoot(basePath: string): string { return result; } +/** + * Detect if a path is inside a .gsd/worktrees// structure. + * + * GSD auto-worktrees live at /.gsd/worktrees//. + * When gsdRoot() is called with such a path, we must NOT walk up to the + * project root's .gsd — each worktree manages its own .gsd state (#2594). + * + * Matches both forward-slash and platform-native separators to handle + * Windows paths (path.sep = '\\') and normalized Unix paths. + */ +function isInsideGsdWorktree(p: string): boolean { + // Match /.gsd/worktrees/ where is the final segment or + // followed by a separator. The segment must be non-empty. + const sepFwd = "/"; + const sepNative = "\\"; + const markers = [ + `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`, + `${sepNative}.gsd${sepNative}worktrees${sepNative}`, + ]; + for (const marker of markers) { + const idx = p.indexOf(marker); + if (idx === -1) continue; + // Verify there's a non-empty worktree name after the marker + const afterMarker = p.slice(idx + marker.length); + // The name is everything up to the next separator (or end of string) + const nameEnd = afterMarker.search(/[/\\]/); + const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd); + if (name.length > 0) return true; + } + return false; +} + function probeGsdRoot(rawBasePath: string): string { // 1. Fast path — check the input path directly const local = join(rawBasePath, ".gsd"); if (existsSync(local)) return local; + // 1b. Worktree guard (#2594) — if basePath is inside a .gsd/worktrees// + // structure, return the worktree-local .gsd path immediately. Without this, + // the git-root probe (step 2) or walk-up (step 3) escapes to the project + // root's .gsd, causing ensurePreconditions() and deriveState() to read/write + // state in the wrong location. + if (isInsideGsdWorktree(rawBasePath)) return local; + // Resolve symlinks so path comparisons work correctly across platforms // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable. let basePath: string; try { basePath = realpathSync.native(rawBasePath); } catch { basePath = rawBasePath; } + // Also check the resolved path for the worktree pattern (macOS /tmp → /private/tmp) + if (basePath !== rawBasePath && isInsideGsdWorktree(basePath)) return local; + // 2. Git root anchor — used as both probe target and walk-up boundary // Only walk if we're inside a git project — prevents escaping into // unrelated filesystem territory when running outside any repo. diff --git a/src/resources/extensions/gsd/phase-anchor.ts b/src/resources/extensions/gsd/phase-anchor.ts new file mode 100644 index 000000000..16f1df5e1 --- /dev/null +++ b/src/resources/extensions/gsd/phase-anchor.ts @@ -0,0 +1,71 @@ +/** + * Phase handoff anchors — compact structured summaries written between + * GSD auto-mode phases so downstream agents inherit decisions, blockers, + * and intent without re-inferring from scratch. + */ + +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { gsdRoot } from "./paths.js"; + +export interface PhaseAnchor { + phase: string; + milestoneId: string; + generatedAt: string; + intent: string; + decisions: string[]; + blockers: string[]; + nextSteps: string[]; +} + +function anchorsDir(basePath: string, milestoneId: string): string { + return join(gsdRoot(basePath), "milestones", milestoneId, "anchors"); +} + +function anchorPath(basePath: string, milestoneId: string, phase: string): string { + return join(anchorsDir(basePath, milestoneId), `${phase}.json`); +} + +export function writePhaseAnchor(basePath: string, milestoneId: string, anchor: PhaseAnchor): void { + const dir = anchorsDir(basePath, milestoneId); + if (!existsSync(dir)) { + mkdirSync(dir, { recursive: true }); + } + writeFileSync(anchorPath(basePath, milestoneId, anchor.phase), JSON.stringify(anchor, null, 2), "utf-8"); +} + +export function readPhaseAnchor(basePath: string, milestoneId: string, phase: string): PhaseAnchor | null { + const path = anchorPath(basePath, milestoneId, phase); + if (!existsSync(path)) return null; + try { + return JSON.parse(readFileSync(path, "utf-8")) as PhaseAnchor; + } catch { + return null; + } +} + +export function formatAnchorForPrompt(anchor: PhaseAnchor): string { + const lines: string[] = [ + `## Handoff from ${anchor.phase}`, + "", + `**Intent:** ${anchor.intent}`, + ]; + + if (anchor.decisions.length > 0) { + lines.push("", "**Decisions:**"); + for (const d of anchor.decisions) lines.push(`- ${d}`); + } + + if (anchor.blockers.length > 0) { + lines.push("", "**Blockers:**"); + for (const b of anchor.blockers) lines.push(`- ${b}`); + } + + if (anchor.nextSteps.length > 0) { + lines.push("", "**Next steps:**"); + for (const s of anchor.nextSteps) lines.push(`- ${s}`); + } + + lines.push("", "---"); + return lines.join("\n"); +} diff --git a/src/resources/extensions/gsd/post-execution-checks.ts b/src/resources/extensions/gsd/post-execution-checks.ts new file mode 100644 index 000000000..284c803c0 --- /dev/null +++ b/src/resources/extensions/gsd/post-execution-checks.ts @@ -0,0 +1,539 @@ +/** + * Post-Execution Checks — Validate task output after execution completes. + * + * Runs these checks against a completed task's output: + * 1. Import resolution — verify relative imports in key_files resolve to existing files + * 2. Cross-task signatures — detect hallucination cascades (function exists in task output + * but doesn't match prior tasks' actual code) + * 3. Pattern consistency — warn on async style drift, naming convention inconsistencies + * + * Design principles: + * - Pure functions taking (taskRow, priorTasks, basePath) for testability + * - Import checks are blocking failures; pattern checks are warnings + * - No AST parsers — uses regex heuristics + */ + +import { existsSync, readFileSync } from "node:fs"; +import { resolve, dirname, join, extname } from "node:path"; +import type { TaskRow } from "./gsd-db.ts"; + +// ─── Result Types ──────────────────────────────────────────────────────────── + +export interface PostExecutionCheckJSON { + /** Check category: import, signature, pattern */ + category: "import" | "signature" | "pattern"; + /** What was checked (e.g., file path, function name) */ + target: string; + /** Whether the check passed */ + passed: boolean; + /** Human-readable message explaining the result */ + message: string; + /** Whether this failure should block completion (only meaningful when passed=false) */ + blocking?: boolean; +} + +export interface PostExecutionResult { + /** Overall result: pass if no blocking failures, warn if non-blocking issues, fail if blocking issues */ + status: "pass" | "warn" | "fail"; + /** All check results */ + checks: PostExecutionCheckJSON[]; + /** Total duration in milliseconds */ + durationMs: number; +} + +// ─── Import Resolution Check ───────────────────────────────────────────────── + +/** + * Extract relative import paths from TypeScript/JavaScript source code. + * Returns array of { importPath, lineNum } for relative imports. + */ +export function extractRelativeImports( + source: string +): Array<{ importPath: string; lineNum: number }> { + const imports: Array<{ importPath: string; lineNum: number }> = []; + const lines = source.split("\n"); + + // Match: + // import ... from './path' + // import ... from "../path" + // import './path' + // require('./path') + // require("../path") + const importPattern = /(?:import\s+(?:.*?\s+from\s+)?|require\s*\(\s*)(['"])(\.\.?\/[^'"]+)\1/g; + + // Track if we're inside a block comment + let inBlockComment = false; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + + // Handle block comment boundaries + if (inBlockComment) { + if (line.includes("*/")) { + inBlockComment = false; + } + continue; + } + + // Check for block comment start (that doesn't end on same line) + const blockStart = line.indexOf("/*"); + const blockEnd = line.indexOf("*/"); + if (blockStart !== -1 && (blockEnd === -1 || blockEnd < blockStart)) { + inBlockComment = true; + continue; + } + + // Skip single-line comments (// at start or after whitespace) + const trimmed = line.trimStart(); + if (trimmed.startsWith("//")) { + continue; + } + + // Skip JSDoc-style lines (e.g., " * import ...") + if (trimmed.startsWith("*")) { + continue; + } + + let match: RegExpExecArray | null; + + // Reset lastIndex for each line + importPattern.lastIndex = 0; + + while ((match = importPattern.exec(line)) !== null) { + // Check if this match is after a // comment marker on the same line + const beforeMatch = line.substring(0, match.index); + if (beforeMatch.includes("//")) { + continue; + } + + imports.push({ + importPath: match[2], + lineNum: i + 1, + }); + } + } + + return imports; +} + +/** + * Check if a relative import resolves to an existing file. + * Handles .ts, .tsx, .js, .jsx extensions and index files. + * Also handles TypeScript ESM convention where imports use .js but resolve to .ts. + */ +export function resolveImportPath( + importPath: string, + sourceFile: string, + basePath: string +): { exists: boolean; resolvedPath: string | null } { + const sourceDir = dirname(resolve(basePath, sourceFile)); + const extensions = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]; + + // Handle TypeScript ESM convention: .js imports resolve to .ts files + // e.g., import './types.js' -> ./types.ts + let normalizedPath = importPath; + if (importPath.endsWith(".js")) { + normalizedPath = importPath.slice(0, -3); + } else if (importPath.endsWith(".jsx")) { + normalizedPath = importPath.slice(0, -4); + } else if (importPath.endsWith(".mjs")) { + normalizedPath = importPath.slice(0, -4); + } else if (importPath.endsWith(".cjs")) { + normalizedPath = importPath.slice(0, -4); + } + + // Try the normalized path with common extensions first + for (const ext of extensions) { + const fullPath = resolve(sourceDir, normalizedPath + ext); + if (existsSync(fullPath)) { + return { exists: true, resolvedPath: fullPath }; + } + } + + // Try as a directory with index file + for (const ext of extensions) { + const indexPath = resolve(sourceDir, normalizedPath, `index${ext}`); + if (existsSync(indexPath)) { + return { exists: true, resolvedPath: indexPath }; + } + } + + // Check if path already has extension (for .json, etc.) + const hasExt = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json"].some( + (ext) => importPath.endsWith(ext) + ); + if (hasExt) { + const fullPath = resolve(sourceDir, importPath); + if (existsSync(fullPath)) { + return { exists: true, resolvedPath: fullPath }; + } + } + + return { exists: false, resolvedPath: null }; +} + +/** + * Check that all relative imports in the task's key_files resolve to existing files. + * Reads modified files from task.key_files, extracts import statements via regex, + * verifies relative imports resolve to existing files. + */ +export function checkImportResolution( + taskRow: TaskRow, + _priorTasks: TaskRow[], + basePath: string +): PostExecutionCheckJSON[] { + const results: PostExecutionCheckJSON[] = []; + + // Get files from key_files + const filesToCheck = taskRow.key_files.filter((f) => { + const ext = extname(f); + return [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext); + }); + + for (const file of filesToCheck) { + const absolutePath = resolve(basePath, file); + + // Skip if file doesn't exist (might have been deleted or renamed) + if (!existsSync(absolutePath)) { + continue; + } + + let source: string; + try { + source = readFileSync(absolutePath, "utf-8"); + } catch { + continue; + } + + const imports = extractRelativeImports(source); + + for (const { importPath, lineNum } of imports) { + const resolution = resolveImportPath(importPath, file, basePath); + + if (!resolution.exists) { + results.push({ + category: "import", + target: `${file}:${lineNum}`, + passed: false, + message: `Import '${importPath}' in ${file}:${lineNum} does not resolve to an existing file`, + blocking: true, + }); + } + } + } + + return results; +} + +// ─── Cross-Task Signature Check ────────────────────────────────────────────── + +interface FunctionSignature { + name: string; + params: string; + returnType: string; + file: string; + lineNum: number; +} + +/** + * Extract function signatures from TypeScript/JavaScript source code. + */ +function extractFunctionSignatures( + source: string, + fileName: string +): FunctionSignature[] { + const signatures: FunctionSignature[] = []; + const lines = source.split("\n"); + + // Match function declarations and exports + // Patterns: + // function name(params): ReturnType + // export function name(params): ReturnType + // export async function name(params): Promise + // const name = (params): ReturnType => + // export const name = (params): ReturnType => + const funcPattern = + /(?:export\s+)?(?:async\s+)?(?:function\s+|const\s+)(\w+)(?:\s*=\s*)?\s*\(([^)]*)\)(?:\s*:\s*([^{=>\n]+))?/g; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + funcPattern.lastIndex = 0; + + let match: RegExpExecArray | null; + while ((match = funcPattern.exec(line)) !== null) { + const [, name, params, returnType] = match; + signatures.push({ + name, + params: normalizeParams(params), + returnType: normalizeType(returnType || "void"), + file: fileName, + lineNum: i + 1, + }); + } + } + + return signatures; +} + +/** + * Normalize parameter list for comparison. + */ +function normalizeParams(params: string): string { + return params + .replace(/\/\*[\s\S]*?\*\//g, "") // Remove block comments + .replace(/\/\/[^\n]*/g, "") // Remove line comments + .replace(/\s*=\s*[^,)]+/g, "") // Remove default values + .replace(/\s+/g, " ") // Normalize whitespace + .trim(); +} + +/** + * Normalize type for comparison. + */ +function normalizeType(type: string): string { + return type.replace(/\s+/g, " ").trim(); +} + +/** + * Compare function signatures in current task's output against prior tasks' key_files + * to catch hallucination cascades — when a task references functions that don't exist + * or have different signatures than what was actually created. + */ +export function checkCrossTaskSignatures( + taskRow: TaskRow, + priorTasks: TaskRow[], + basePath: string +): PostExecutionCheckJSON[] { + const results: PostExecutionCheckJSON[] = []; + + // Build map of functions from prior tasks' key_files + const priorSignatures = new Map(); + + for (const task of priorTasks) { + for (const file of task.key_files) { + const ext = extname(file); + if (![".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext)) continue; + + const absolutePath = resolve(basePath, file); + if (!existsSync(absolutePath)) continue; + + try { + const source = readFileSync(absolutePath, "utf-8"); + const sigs = extractFunctionSignatures(source, file); + for (const sig of sigs) { + const existing = priorSignatures.get(sig.name) || []; + existing.push(sig); + priorSignatures.set(sig.name, existing); + } + } catch { + // Skip unreadable files + } + } + } + + // Extract function calls/references from current task's key_files + // and check they match prior definitions + for (const file of taskRow.key_files) { + const ext = extname(file); + if (![".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext)) continue; + + const absolutePath = resolve(basePath, file); + if (!existsSync(absolutePath)) continue; + + try { + const source = readFileSync(absolutePath, "utf-8"); + const currentSigs = extractFunctionSignatures(source, file); + + // Check each function in current task against prior definitions + for (const currentSig of currentSigs) { + const priorDefs = priorSignatures.get(currentSig.name); + + // If this function was defined in a prior task, check for signature drift + if (priorDefs && priorDefs.length > 0) { + const priorDef = priorDefs[0]; // Use first definition + + // Check parameter mismatch + if (currentSig.params !== priorDef.params) { + results.push({ + category: "signature", + target: currentSig.name, + passed: false, + message: `Function '${currentSig.name}' in ${file}:${currentSig.lineNum} has parameters '${currentSig.params}' but prior definition in ${priorDef.file}:${priorDef.lineNum} has '${priorDef.params}'`, + blocking: false, // Warn only — may be intentional override + }); + } + + // Check return type mismatch + if (currentSig.returnType !== priorDef.returnType) { + results.push({ + category: "signature", + target: currentSig.name, + passed: false, + message: `Function '${currentSig.name}' in ${file}:${currentSig.lineNum} returns '${currentSig.returnType}' but prior definition in ${priorDef.file}:${priorDef.lineNum} returns '${priorDef.returnType}'`, + blocking: false, // Warn only — may be intentional override + }); + } + } + } + } catch { + // Skip unreadable files + } + } + + return results; +} + +// ─── Pattern Consistency Check ─────────────────────────────────────────────── + +/** + * Detect async style drift (mixing async/await with .then()) and + * naming convention inconsistencies within a task's key_files. + * Warn only — these are style issues, not correctness issues. + */ +export function checkPatternConsistency( + taskRow: TaskRow, + _priorTasks: TaskRow[], + basePath: string +): PostExecutionCheckJSON[] { + const results: PostExecutionCheckJSON[] = []; + + for (const file of taskRow.key_files) { + const ext = extname(file); + if (![".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"].includes(ext)) continue; + + const absolutePath = resolve(basePath, file); + if (!existsSync(absolutePath)) continue; + + try { + const source = readFileSync(absolutePath, "utf-8"); + + // Check for async style drift + const asyncStyleResult = checkAsyncStyleDrift(source, file); + if (asyncStyleResult) { + results.push(asyncStyleResult); + } + + // Check for naming convention inconsistencies + const namingResults = checkNamingConsistency(source, file); + results.push(...namingResults); + } catch { + // Skip unreadable files + } + } + + return results; +} + +/** + * Detect async style drift within a single file. + * Returns a warning if both async/await AND .then() promise chaining are used. + */ +function checkAsyncStyleDrift( + source: string, + fileName: string +): PostExecutionCheckJSON | null { + // Check for async/await usage + const hasAsyncAwait = /\basync\b[\s\S]*?\bawait\b/.test(source); + + // Check for .then() promise chaining (excluding comments) + // Filter out common false positives like Array.prototype.then doesn't exist + const hasThenChaining = /\.\s*then\s*\(/.test(source); + + // If both patterns are present, flag as style drift + if (hasAsyncAwait && hasThenChaining) { + return { + category: "pattern", + target: fileName, + passed: true, // Warning only + message: `File ${fileName} mixes async/await with .then() promise chaining — consider using consistent async style`, + blocking: false, + }; + } + + return null; +} + +/** + * Check for naming convention inconsistencies within a file. + * Detects mixing of camelCase and snake_case for similar identifier types. + */ +function checkNamingConsistency( + source: string, + fileName: string +): PostExecutionCheckJSON[] { + const results: PostExecutionCheckJSON[] = []; + + // Extract function names + const functionNames: string[] = []; + const funcPattern = /(?:function\s+|const\s+|let\s+|var\s+)(\w+)(?:\s*=\s*(?:async\s*)?\(|\s*\()/g; + let match: RegExpExecArray | null; + + while ((match = funcPattern.exec(source)) !== null) { + functionNames.push(match[1]); + } + + // Check for mixed naming conventions in functions + const camelCaseFuncs = functionNames.filter((n) => /^[a-z][a-zA-Z0-9]*$/.test(n) && /[A-Z]/.test(n)); + const snakeCaseFuncs = functionNames.filter((n) => /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/.test(n)); + + if (camelCaseFuncs.length > 0 && snakeCaseFuncs.length > 0) { + results.push({ + category: "pattern", + target: fileName, + passed: true, // Warning only + message: `File ${fileName} mixes camelCase (${camelCaseFuncs.slice(0, 2).join(", ")}) and snake_case (${snakeCaseFuncs.slice(0, 2).join(", ")}) function names`, + blocking: false, + }); + } + + return results; +} + +// ─── Main Entry Point ──────────────────────────────────────────────────────── + +/** + * Run all post-execution checks against a completed task. + * + * @param taskRow - The completed task row + * @param priorTasks - Array of TaskRow from prior completed tasks in the slice + * @param basePath - Base path for resolving file references + * @returns PostExecutionResult with status, checks, and duration + */ +export function runPostExecutionChecks( + taskRow: TaskRow, + priorTasks: TaskRow[], + basePath: string +): PostExecutionResult { + const startTime = Date.now(); + const allChecks: PostExecutionCheckJSON[] = []; + + // Run all checks + const importChecks = checkImportResolution(taskRow, priorTasks, basePath); + const signatureChecks = checkCrossTaskSignatures(taskRow, priorTasks, basePath); + const patternChecks = checkPatternConsistency(taskRow, priorTasks, basePath); + + allChecks.push(...importChecks, ...signatureChecks, ...patternChecks); + + const durationMs = Date.now() - startTime; + + // Determine overall status + const hasBlockingFailure = allChecks.some((c) => !c.passed && c.blocking); + const hasNonBlockingIssue = allChecks.some( + (c) => (!c.passed && !c.blocking) || (c.passed && c.category === "pattern") + ); + + let status: "pass" | "warn" | "fail"; + if (hasBlockingFailure) { + status = "fail"; + } else if (hasNonBlockingIssue) { + status = "warn"; + } else { + status = "pass"; + } + + return { + status, + checks: allChecks, + durationMs, + }; +} diff --git a/src/resources/extensions/gsd/pre-execution-checks.ts b/src/resources/extensions/gsd/pre-execution-checks.ts new file mode 100644 index 000000000..5e77bca85 --- /dev/null +++ b/src/resources/extensions/gsd/pre-execution-checks.ts @@ -0,0 +1,638 @@ +/** + * Pre-Execution Checks — Validate task plans before execution begins. + * + * Runs these checks against a slice's task plan: + * 1. Package existence — npm view calls in parallel with timeout + * 2. File path consistency — verify files exist or are in prior expected_output + * 3. Task ordering — detect impossible ordering (task reads file created later) + * 4. Interface contracts — detect contradictory function signatures (warn only) + * + * Design principles: + * - Pure functions taking (tasks: TaskRow[], basePath: string) for testability + * - Network failures warn, don't fail (R012 conservative design) + * - Total execution <2s target (R013) + * - No AST parsers — interface parsing is heuristic (regex on code blocks) + */ + +import { existsSync } from "node:fs"; +import { spawn } from "node:child_process"; +import { resolve } from "node:path"; +import type { TaskRow } from "./gsd-db.ts"; +import type { PreExecutionCheckJSON } from "./verification-evidence.ts"; + +const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm"; + +// ─── Result Types ──────────────────────────────────────────────────────────── + +export interface PreExecutionResult { + /** Overall result: pass if no blocking failures, warn if non-blocking issues, fail if blocking issues */ + status: "pass" | "warn" | "fail"; + /** All check results */ + checks: PreExecutionCheckJSON[]; + /** Total duration in milliseconds */ + durationMs: number; +} + +// ─── Package Existence Check ───────────────────────────────────────────────── + +/** + * Extract npm package names from task descriptions. + * Looks for: + * - `npm install ` patterns + * - Code blocks with `require('')` or `import ... from ''` + * - Explicit mentions like "uses lodash" or "package: axios" + */ +export function extractPackageReferences(description: string): string[] { + const packages = new Set(); + + // Common words that aren't package names but might appear after install + const stopwords = new Set([ + "then", "and", "the", "to", "a", "an", "in", "for", "with", "from", "or", + "npm", "yarn", "pnpm", "i", // Don't capture the command itself + ]); + + // npm install patterns (handles npm i, npm add, yarn add, pnpm add) + // Use a global pattern to find all install commands, then parse following tokens + const installCmdPattern = /(?:npm\s+(?:install|i|add)|yarn\s+add|pnpm\s+add)\s+/g; + let cmdMatch: RegExpExecArray | null; + + while ((cmdMatch = installCmdPattern.exec(description)) !== null) { + // Start after the install command + const afterCmd = description.slice(cmdMatch.index + cmdMatch[0].length); + + // Match package-like tokens (alphanumeric, @, /, -, _) until we hit + // something that's not a package (non-token char after whitespace) + const tokenPattern = /^([@a-zA-Z][a-zA-Z0-9@/_-]*)(?:\s+|$)/; + let remaining = afterCmd; + + while (remaining.length > 0) { + // Skip any flags like -D, --save-dev + const flagMatch = remaining.match(/^(-[a-zA-Z-]+)\s*/); + if (flagMatch) { + remaining = remaining.slice(flagMatch[0].length); + continue; + } + + // Try to match a package name + const pkgMatch = remaining.match(tokenPattern); + if (pkgMatch) { + const token = pkgMatch[1]; + // Skip stopwords - they indicate end of package list + if (stopwords.has(token.toLowerCase())) { + break; + } + packages.add(normalizePackageName(token)); + remaining = remaining.slice(pkgMatch[0].length); + } else { + // Not a package name, stop parsing this install command + break; + } + } + } + + // require('pkg') or import from 'pkg' in code blocks + const importPattern = /(?:require\s*\(\s*['"]|from\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g; + let importMatch: RegExpExecArray | null; + while ((importMatch = importPattern.exec(description)) !== null) { + // Skip relative imports and node builtins + const pkg = importMatch[1]; + if (!pkg.startsWith(".") && !pkg.startsWith("node:")) { + packages.add(normalizePackageName(pkg)); + } + } + + return Array.from(packages); +} + +/** + * Normalize package name to registry-checkable form. + * Handles scoped packages (@org/pkg) and subpaths (pkg/subpath → pkg). + */ +function normalizePackageName(raw: string): string { + // Scoped package: @org/pkg or @org/pkg/subpath + if (raw.startsWith("@")) { + const parts = raw.split("/"); + return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : raw; + } + // Regular package: pkg or pkg/subpath + return raw.split("/")[0]; +} + +/** + * Check if a package exists on npm registry. + * Returns null on success, error message on failure. + * Times out after timeoutMs (default 5000ms). + */ +async function checkPackageOnNpm( + packageName: string, + timeoutMs = 5000 +): Promise<{ exists: boolean; error?: string }> { + return new Promise((resolve) => { + const child = spawn(NPM_COMMAND, ["view", packageName, "name"], { + stdio: ["ignore", "pipe", "pipe"], + timeout: timeoutMs, + shell: process.platform === "win32", + }); + + let stdout = ""; + let stderr = ""; + + child.stdout.on("data", (data: Buffer) => { + stdout += data.toString(); + }); + child.stderr.on("data", (data: Buffer) => { + stderr += data.toString(); + }); + + const timer = setTimeout(() => { + child.kill("SIGTERM"); + resolve({ exists: false, error: `Timeout after ${timeoutMs}ms` }); + }, timeoutMs); + + child.on("close", (code) => { + clearTimeout(timer); + if (code === 0 && stdout.trim()) { + resolve({ exists: true }); + } else if (stderr.includes("404") || stderr.includes("not found")) { + resolve({ exists: false, error: `Package not found: ${packageName}` }); + } else if (code !== 0) { + // Network error or other issue — warn, don't fail + resolve({ exists: true, error: `npm view failed (code ${code}): ${stderr.slice(0, 100)}` }); + } else { + resolve({ exists: true }); + } + }); + + child.on("error", (err) => { + clearTimeout(timer); + resolve({ exists: true, error: `npm spawn error: ${err.message}` }); + }); + }); +} + +/** + * Check all package references in tasks for existence on npm. + * Runs checks in parallel with a 5s timeout per package. + * Network failures warn but don't fail (R012 conservative design). + */ +export async function checkPackageExistence( + tasks: TaskRow[], + _basePath: string +): Promise { + const results: PreExecutionCheckJSON[] = []; + const packagesToCheck = new Set(); + + // Collect all package references from task descriptions + for (const task of tasks) { + const packages = extractPackageReferences(task.description); + for (const pkg of packages) { + packagesToCheck.add(pkg); + } + } + + if (packagesToCheck.size === 0) { + return results; + } + + // Check packages in parallel + const checkPromises = Array.from(packagesToCheck).map(async (pkg) => { + const result = await checkPackageOnNpm(pkg); + return { pkg, result }; + }); + + const checkResults = await Promise.all(checkPromises); + + for (const { pkg, result } of checkResults) { + if (!result.exists && !result.error?.includes("Timeout") && !result.error?.includes("spawn error")) { + // Package genuinely doesn't exist — blocking failure + results.push({ + category: "package", + target: pkg, + passed: false, + message: result.error || `Package '${pkg}' not found on npm`, + blocking: true, + }); + } else if (result.error) { + // Network issue or timeout — warn but don't block + results.push({ + category: "package", + target: pkg, + passed: true, + message: `Warning: ${result.error}`, + blocking: false, + }); + } + // Silent success for existing packages — no need to report + } + + return results; +} + +// ─── File Path Consistency Check ───────────────────────────────────────────── + +/** + * Normalize a file path for consistent comparison. + * - Strips leading ./ + * - Normalizes path separators to forward slashes + * - Resolves redundant segments (e.g., foo/../bar → bar) + * + * This ensures that "./src/a.ts", "src/a.ts", and "src//a.ts" all compare equal. + */ +export function normalizeFilePath(filePath: string): string { + if (!filePath) return filePath; + + let normalized = extractPathFromAnnotation(filePath); + + // Normalize path separators to forward slashes + normalized = normalized.replace(/\\/g, "/"); + + // Remove leading ./ + while (normalized.startsWith("./")) { + normalized = normalized.slice(2); + } + + // Remove duplicate slashes + normalized = normalized.replace(/\/+/g, "/"); + + // Remove trailing slash unless it's the root + if (normalized.length > 1 && normalized.endsWith("/")) { + normalized = normalized.slice(0, -1); + } + + return normalized; +} + +function extractPathFromAnnotation(raw: string): string { + const trimmed = raw.trim(); + if (!trimmed) return trimmed; + + const backtickMatch = trimmed.match(/^(`+)([^`]+)\1(?:(?:\s+[—–-]\s+.+)|(?:\s+\([^()]+\)))?$/); + if (backtickMatch) { + return backtickMatch[2].trim(); + } + + const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/); + if (annotatedMatch) { + return annotatedMatch[1].trim(); + } + + // Fall back to the original behavior for already-plain paths. + return trimmed.replace(/`/g, ""); +} + +/** + * Planning units sometimes use task.inputs for prose like "Current enum shape" + * instead of concrete file paths. Those entries should not fail path checks. + * Keep validation for anything that still looks like a real file reference: + * explicit backticks, globs, separators, dot-paths, or single-token basenames + * like Dockerfile. + */ +function shouldValidateInputAsPath(raw: string): boolean { + const trimmed = raw.trim(); + if (!trimmed) return false; + + if (/^`+[^`]+`+/.test(trimmed)) { + return true; + } + + const candidate = extractPathFromAnnotation(trimmed); + if (!candidate) return false; + + if (!/\s/.test(candidate)) { + return true; + } + + return ( + candidate.startsWith("/") || + candidate.startsWith("./") || + candidate.startsWith("../") || + candidate.startsWith("~/") || + /[\\/]/.test(candidate) || + /[*?[\]{}]/.test(candidate) + ); +} + +/** + * Build a set of files that will be created by tasks up to (but not including) taskIndex. + * All paths are normalized for consistent comparison. + */ +function getExpectedOutputsUpTo(tasks: TaskRow[], taskIndex: number): Set { + const outputs = new Set(); + for (let i = 0; i < taskIndex; i++) { + for (const file of tasks[i].expected_output) { + outputs.add(normalizeFilePath(file)); + } + } + return outputs; +} + +/** + * Check that all files referenced in task.inputs either: + * 1. Exist on disk, OR + * 2. Are in a prior task's expected_output + * + * task.files ("files likely touched") is excluded — it intentionally includes + * files the task will create, so they don't need to pre-exist (#3626). + * + * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts. + */ +export function checkFilePathConsistency( + tasks: TaskRow[], + basePath: string +): PreExecutionCheckJSON[] { + const results: PreExecutionCheckJSON[] = []; + + for (let i = 0; i < tasks.length; i++) { + const task = tasks[i]; + const priorOutputs = getExpectedOutputsUpTo(tasks, i); + const filesToCheck = [...task.inputs]; + + for (const file of filesToCheck) { + // Skip empty strings + if (!file.trim()) continue; + if (!shouldValidateInputAsPath(file)) continue; + + // Normalize path for consistent comparison + const normalizedFile = normalizeFilePath(file); + + // Check if file exists on disk + const absolutePath = resolve(basePath, normalizedFile); + const existsOnDisk = existsSync(absolutePath); + + // Check if file is in prior expected outputs (priorOutputs already normalized) + const inPriorOutputs = priorOutputs.has(normalizedFile); + + if (!existsOnDisk && !inPriorOutputs) { + results.push({ + category: "file", + target: file, + passed: false, + message: `Task ${task.id} references '${file}' which doesn't exist and isn't created by prior tasks`, + blocking: true, + }); + } + } + } + + return results; +} + +// ─── Task Ordering Check ───────────────────────────────────────────────────── + +/** + * Detect impossible task ordering: task N reads a file that task N+M creates. + * This is a fatal error — the plan has an impossible dependency. + * + * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts. + */ +export function checkTaskOrdering( + tasks: TaskRow[], + basePath: string +): PreExecutionCheckJSON[] { + const results: PreExecutionCheckJSON[] = []; + + // Build map: normalized file → task index that creates it + const fileCreators = new Map(); + for (let i = 0; i < tasks.length; i++) { + const task = tasks[i]; + for (const file of task.expected_output) { + const normalizedFile = normalizeFilePath(file); + if (!fileCreators.has(normalizedFile)) { + fileCreators.set(normalizedFile, { taskId: task.id, index: i, originalPath: file }); + } + } + } + + // Check each task's inputs against file creators. + // Only check task.inputs — task.files ("files likely touched") intentionally + // includes files the task will create, so they don't indicate read-before-create (#3677). + for (let i = 0; i < tasks.length; i++) { + const task = tasks[i]; + const filesToCheck = [...task.inputs]; + + for (const file of filesToCheck) { + if (!shouldValidateInputAsPath(file)) continue; + + const normalizedFile = normalizeFilePath(file); + const creator = fileCreators.get(normalizedFile); + const absolutePath = resolve(basePath, normalizedFile); + const existsOnDisk = existsSync(absolutePath); + if (creator && creator.index > i && !existsOnDisk) { + // Task reads file that is created later — impossible ordering + results.push({ + category: "file", + target: file, + passed: false, + message: `Task ${task.id} reads '${file}' but it's created by task ${creator.taskId} (sequence violation)`, + blocking: true, + }); + } + } + } + + return results; +} + +// ─── Interface Contract Check ──────────────────────────────────────────────── + +interface FunctionSignature { + name: string; + params: string; + returnType: string; + taskId: string; + raw: string; +} + +/** + * Extract function signatures from code blocks in task description. + * Uses heuristic regex — not an AST parser. + */ +function extractFunctionSignatures(description: string, taskId: string): FunctionSignature[] { + const signatures: FunctionSignature[] = []; + + // Match code blocks (```...```) + const codeBlockPattern = /```(?:typescript|ts|javascript|js)?\n([\s\S]*?)```/g; + let blockMatch: RegExpExecArray | null; + + while ((blockMatch = codeBlockPattern.exec(description)) !== null) { + const codeBlock = blockMatch[1]; + + // Match function declarations and exports + // Patterns: + // function name(params): ReturnType + // export function name(params): ReturnType + // export async function name(params): Promise + // const name = (params): ReturnType => + // export const name = (params): ReturnType => + const funcPattern = /(?:export\s+)?(?:async\s+)?(?:function\s+|const\s+)(\w+)(?:\s*=\s*)?\s*\(([^)]*)\)(?:\s*:\s*([^{=>\n]+))?/g; + let funcMatch: RegExpExecArray | null; + + while ((funcMatch = funcPattern.exec(codeBlock)) !== null) { + const [raw, name, params, returnType] = funcMatch; + signatures.push({ + name, + params: normalizeParams(params), + returnType: normalizeType(returnType || "void"), + taskId, + raw: raw.trim(), + }); + } + + // Match interface method signatures + // Pattern: methodName(params): ReturnType; + const methodPattern = /^\s*(\w+)\s*\(([^)]*)\)\s*:\s*([^;]+);/gm; + let methodMatch: RegExpExecArray | null; + + while ((methodMatch = methodPattern.exec(codeBlock)) !== null) { + const [raw, name, params, returnType] = methodMatch; + signatures.push({ + name, + params: normalizeParams(params), + returnType: normalizeType(returnType), + taskId, + raw: raw.trim(), + }); + } + } + + return signatures; +} + +/** + * Normalize parameter list for comparison. + * Removes whitespace, comments, and default values. + */ +function normalizeParams(params: string): string { + return params + .replace(/\/\*[\s\S]*?\*\//g, "") // Remove block comments + .replace(/\/\/[^\n]*/g, "") // Remove line comments + .replace(/\s*=\s*[^,)]+/g, "") // Remove default values + .replace(/\s+/g, " ") // Normalize whitespace + .trim(); +} + +/** + * Normalize type for comparison. + */ +function normalizeType(type: string): string { + return type + .replace(/\s+/g, " ") + .trim(); +} + +/** + * Check for contradictory function signatures across tasks. + * Same function name with different signatures is a warning (not blocking). + */ +export function checkInterfaceContracts( + tasks: TaskRow[], + _basePath: string +): PreExecutionCheckJSON[] { + const results: PreExecutionCheckJSON[] = []; + + // Collect all signatures + const allSignatures: FunctionSignature[] = []; + for (const task of tasks) { + const sigs = extractFunctionSignatures(task.description, task.id); + allSignatures.push(...sigs); + } + + // Group by function name + const byName = new Map(); + for (const sig of allSignatures) { + const existing = byName.get(sig.name) || []; + existing.push(sig); + byName.set(sig.name, existing); + } + + // Check for contradictions + for (const [name, sigs] of byName) { + if (sigs.length < 2) continue; + + // Compare signatures + const first = sigs[0]; + for (let i = 1; i < sigs.length; i++) { + const current = sigs[i]; + + // Check parameter mismatch + if (first.params !== current.params) { + results.push({ + category: "schema", + target: name, + passed: true, // Warning only, not blocking + message: `Function '${name}' has different parameters: '${first.params}' (${first.taskId}) vs '${current.params}' (${current.taskId})`, + blocking: false, + }); + } + + // Check return type mismatch + if (first.returnType !== current.returnType) { + results.push({ + category: "schema", + target: name, + passed: true, // Warning only, not blocking + message: `Function '${name}' has different return types: '${first.returnType}' (${first.taskId}) vs '${current.returnType}' (${current.taskId})`, + blocking: false, + }); + } + } + } + + return results; +} + +// ─── Main Entry Point ──────────────────────────────────────────────────────── + +/** + * Run all pre-execution checks against a slice's task plan. + * + * @param tasks - Array of TaskRow from the slice + * @param basePath - Base path for resolving file references + * @returns PreExecutionResult with status, checks, and duration + */ +export async function runPreExecutionChecks( + tasks: TaskRow[], + basePath: string +): Promise { + const startTime = Date.now(); + const allChecks: PreExecutionCheckJSON[] = []; + + // Run sync checks first + const fileChecks = checkFilePathConsistency(tasks, basePath); + const orderingChecks = checkTaskOrdering(tasks, basePath); + const contractChecks = checkInterfaceContracts(tasks, basePath); + + allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks); + + // Run async package checks + const packageChecks = await checkPackageExistence(tasks, basePath); + allChecks.push(...packageChecks); + + const durationMs = Date.now() - startTime; + + // Determine overall status + const hasBlockingFailure = allChecks.some((c) => !c.passed && c.blocking); + const hasNonBlockingFailure = allChecks.some((c) => !c.passed && !c.blocking); + // Interface contract checks pass but still report warnings via message + const hasInterfaceWarning = allChecks.some( + (c) => c.category === "schema" && c.message && !c.message.startsWith("Warning:") + ); + const hasNetworkWarning = allChecks.some( + (c) => c.passed && c.message?.startsWith("Warning:") + ); + + let status: "pass" | "warn" | "fail"; + if (hasBlockingFailure) { + status = "fail"; + } else if (hasNonBlockingFailure || hasInterfaceWarning || hasNetworkWarning) { + status = "warn"; + } else { + status = "pass"; + } + + return { + status, + checks: allChecks, + durationMs, + }; +} diff --git a/src/resources/extensions/gsd/preferences-models.ts b/src/resources/extensions/gsd/preferences-models.ts index f5a488672..2e4171687 100644 --- a/src/resources/extensions/gsd/preferences-models.ts +++ b/src/resources/extensions/gsd/preferences-models.ts @@ -69,6 +69,7 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode break; case "complete-slice": case "complete-milestone": + case "worktree-merge": case "run-uat": phaseConfig = m.completion; break; @@ -106,6 +107,84 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode }; } +/** + * Resolve the default session model from GSD preferences. + * + * Used at auto-mode bootstrap to override the session model that was + * determined by settings.json (defaultProvider/defaultModel). When + * PREFERENCES.md (or project preferences) configures an `execution` model + * we treat that as the session default. Falls back through execution → + * planning → first configured model. + * + * Accepts an optional `sessionProvider` for bare model IDs that don't + * include an explicit provider prefix (e.g. `gpt-5.4` instead of + * `openai-codex/gpt-5.4`). When a bare ID is found and sessionProvider + * is available, the session provider is used. Without sessionProvider, + * bare IDs are still returned with provider set to the bare ID itself + * so downstream resolution (resolveModelId) can match it. + * + * Returns `{ provider, id }` or `undefined` if no model preference is + * configured. + */ +export function resolveDefaultSessionModel( + sessionProvider?: string, +): { provider: string; id: string } | undefined { + const prefs = loadEffectiveGSDPreferences(); + if (!prefs?.preferences.models) return undefined; + + const m = prefs.preferences.models as GSDModelConfigV2; + + // Priority: execution → planning → first configured value + const candidates: Array = [ + m.execution, + m.planning, + m.research, + m.discuss, + m.completion, + m.validation, + m.subagent, + ]; + + for (const cfg of candidates) { + if (!cfg) continue; + + // Normalize to provider + id from the various config shapes + let provider: string | undefined; + let id: string; + + if (typeof cfg === "string") { + const slashIdx = cfg.indexOf("/"); + if (slashIdx !== -1) { + provider = cfg.slice(0, slashIdx); + id = cfg.slice(slashIdx + 1); + } else { + // Bare model ID (e.g. "gpt-5.4") — use session provider as context + provider = sessionProvider; + id = cfg; + } + } else { + // Object config: { model, provider?, fallbacks? } + if (cfg.provider) { + provider = cfg.provider; + } else if (cfg.model.includes("/")) { + const slashIdx = cfg.model.indexOf("/"); + provider = cfg.model.slice(0, slashIdx); + id = cfg.model.slice(slashIdx + 1); + return { provider, id }; + } else { + provider = sessionProvider; + } + id = cfg.model; + } + + if (provider && id) { + return { provider, id }; + } + } + + return undefined; +} + /** * Determines the next fallback model to try when the current model fails. * If the current model is not in the configured list, returns the primary model. @@ -137,6 +216,18 @@ export function getNextFallbackModel( } } +/** + * Detect whether an error message indicates a transient network error + * (worth retrying the same model) vs a permanent provider error + * (auth failure, quota exceeded, etc. -- should fall back immediately). + */ +export function isTransientNetworkError(errorMsg: string): boolean { + if (!errorMsg) return false; + const hasNetworkSignal = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i.test(errorMsg); + const hasPermanentSignal = /auth|unauthorized|forbidden|invalid.*key|quota|billing/i.test(errorMsg); + return hasNetworkSignal && !hasPermanentSignal; +} + /** * Validate a model ID string. * Returns true if the ID looks like a valid model identifier. @@ -308,7 +399,7 @@ export function resolveContextSelection(): import("./types.js").ContextSelection } /** - * Resolve the search provider preference from PREFERENCES.md. + * Resolve the search provider preference from preferences.md. * Returns undefined if not configured (caller falls back to existing behavior). */ export function resolveSearchProviderFromPreferences(): GSDPreferences["search_provider"] | undefined { diff --git a/src/resources/extensions/gsd/preferences-skills.ts b/src/resources/extensions/gsd/preferences-skills.ts index 1ad5a6d39..d930ba0b4 100644 --- a/src/resources/extensions/gsd/preferences-skills.ts +++ b/src/resources/extensions/gsd/preferences-skills.ts @@ -24,13 +24,18 @@ export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolution /** * Known skill directories, in priority order. - * Global skills (~/.agents/skills/) take precedence over project skills. + * Searches both the skills.sh ecosystem directory (~/.agents/skills/) and + * Claude Code's official directory (~/.claude/skills/). Project-level + * directories for both conventions are included as well. * Legacy ~/.gsd/agent/skills/ is included as a fallback for pre-migration installs. */ export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> { const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [ { dir: join(homedir(), ".agents", "skills"), method: "user-skill" }, { dir: join(cwd, ".agents", "skills"), method: "project-skill" }, + // Claude Code official skill directories + { dir: join(homedir(), ".claude", "skills"), method: "user-skill" }, + { dir: join(cwd, ".claude", "skills"), method: "project-skill" }, ]; // Legacy fallback — read skills from old GSD directory only if migration hasn't completed const legacyDir = join(homedir(), ".gsd", "agent", "skills"); diff --git a/src/resources/extensions/gsd/preferences-types.ts b/src/resources/extensions/gsd/preferences-types.ts index 663c58376..47ed0c12b 100644 --- a/src/resources/extensions/gsd/preferences-types.ts +++ b/src/resources/extensions/gsd/preferences-types.ts @@ -20,7 +20,14 @@ import type { ReactiveExecutionConfig, GateEvaluationConfig, } from "./types.js"; -import type { DynamicRoutingConfig } from "./model-router.js"; +import type { DynamicRoutingConfig, ModelCapabilities } from "./model-router.js"; + +export interface ContextManagementConfig { + observation_masking?: boolean; // default: true + observation_mask_turns?: number; // default: 8, range: 1-50 + compaction_threshold_percent?: number; // default: 0.70, range: 0.5-0.95 + tool_result_max_chars?: number; // default: 800, range: 200-10000 +} import type { GitHubSyncConfig } from "../github-sync/types.js"; // ─── Workflow Modes ────────────────────────────────────────────────────────── @@ -93,14 +100,27 @@ export const KNOWN_PREFERENCE_KEYS = new Set([ "service_tier", "forensics_dedup", "show_token_cost", + "stale_commit_threshold_minutes", + "context_management", "experimental", + "codebase", + "slice_parallel", + "safety_harness", + "enhanced_verification", + "enhanced_verification_pre", + "enhanced_verification_post", + "enhanced_verification_strict", + "discuss_preparation", + "discuss_web_research", + "discuss_depth", ]); /** Canonical list of all dispatch unit types. */ export const KNOWN_UNIT_TYPES = [ "research-milestone", "plan-milestone", "research-slice", "plan-slice", "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap", - "run-uat", "complete-milestone", + "run-uat", "complete-milestone", "validate-milestone", "rewrite-docs", + "discuss-milestone", "discuss-slice", "worktree-merge", ] as const; export type UnitType = (typeof KNOWN_UNIT_TYPES)[number]; @@ -201,6 +221,16 @@ export interface ExperimentalPreferences { rtk?: boolean; } +/** Configuration for the codebase map generator (/gsd codebase). */ +export interface CodebaseMapPreferences { + /** Additional directory/file patterns to exclude (e.g. ["docs/", "fixtures/"]). Merged with built-in defaults. */ + exclude_patterns?: string[]; + /** Max files to include in the map. Default: 500. */ + max_files?: number; + /** Files-per-directory threshold before collapsing to a summary line. Default: 20. */ + collapse_threshold?: number; +} + export interface GSDPreferences { version?: number; mode?: WorkflowMode; @@ -225,6 +255,9 @@ export interface GSDPreferences { post_unit_hooks?: PostUnitHookConfig[]; pre_dispatch_hooks?: PreDispatchHookConfig[]; dynamic_routing?: DynamicRoutingConfig; + /** Per-model capability overrides. Deep-merged with built-in profiles for capability-aware routing (ADR-004). */ + modelOverrides?: Record }>; + context_management?: ContextManagementConfig; token_profile?: TokenProfile; phases?: PhaseSkipPreferences; auto_visualize?: boolean; @@ -252,11 +285,80 @@ export interface GSDPreferences { forensics_dedup?: boolean; /** Opt-in: show per-prompt and cumulative session token cost in the footer. Default: false. */ show_token_cost?: boolean; + /** + * Minutes without a commit before flagging uncommitted changes as stale. + * When the threshold is exceeded and the working tree is dirty, doctor will + * auto-commit a safety snapshot tagged with `[gsd safety]`. Default: 30. + * Set to 0 to disable. + */ + stale_commit_threshold_minutes?: number; /** * Opt-in experimental features. All features here are disabled by default. * See the preferences reference for details on each feature. */ experimental?: ExperimentalPreferences; + /** Configuration for the codebase map generator (/gsd codebase). */ + codebase?: CodebaseMapPreferences; + /** Slice-level parallelism within a milestone. Disabled by default. */ + slice_parallel?: { enabled?: boolean; max_workers?: number }; + /** LLM safety harness configuration. Monitors, validates, and constrains LLM behavior during auto-mode. Enabled by default with warn-and-continue policy. */ + safety_harness?: { + enabled?: boolean; + evidence_collection?: boolean; + file_change_validation?: boolean; + evidence_cross_reference?: boolean; + destructive_command_warnings?: boolean; + content_validation?: boolean; + checkpoints?: boolean; + auto_rollback?: boolean; + timeout_scale_cap?: number; + }; + + + // ─── Enhanced Verification ────────────────────────────────────────────────── + /** + * Enable enhanced verification (both pre-execution and post-execution checks). + * Default: true (opt-out, not opt-in). Set false to disable all enhanced verification. + */ + enhanced_verification?: boolean; + /** + * Enable pre-execution checks (package existence, file references, etc.). + * Only applies when enhanced_verification is true. + * Default: true. + */ + enhanced_verification_pre?: boolean; + /** + * Enable post-execution checks (runtime error detection, audit warnings, etc.). + * Only applies when enhanced_verification is true. + * Default: true. + */ + enhanced_verification_post?: boolean; + /** + * Strict mode: treat any pre-execution check failure as blocking. + * Default: false (warnings only for non-critical failures). + */ + enhanced_verification_strict?: boolean; + /** + * Enable the preparation phase before discussion sessions. + * Preparation analyzes the codebase, reviews prior context, and optionally researches the ecosystem. + * Default: true. + */ + discuss_preparation?: boolean; + /** + * Enable web research during preparation phase. + * When enabled, searches for best practices and known issues for the detected tech stack. + * Requires a search API key (TAVILY_API_KEY or BRAVE_API_KEY). + * Default: true. + */ + discuss_web_research?: boolean; + /** + * Depth of preparation analysis. + * - "quick": Minimal analysis, fastest (~10s) + * - "standard": Balanced analysis (~30s) + * - "thorough": Deep analysis with more file sampling (~60s) + * Default: "standard". + */ + discuss_depth?: "quick" | "standard" | "thorough"; } export interface LoadedGSDPreferences { diff --git a/src/resources/extensions/gsd/preferences-validation.ts b/src/resources/extensions/gsd/preferences-validation.ts index 6b4e0e217..e4ac3d3d6 100644 --- a/src/resources/extensions/gsd/preferences-validation.ts +++ b/src/resources/extensions/gsd/preferences-validation.ts @@ -428,6 +428,10 @@ export function validatePreferences(preferences: GSDPreferences): { if (typeof dr.hooks === "boolean") validDr.hooks = dr.hooks; else errors.push("dynamic_routing.hooks must be a boolean"); } + if (dr.capability_routing !== undefined) { + if (typeof dr.capability_routing === "boolean") validDr.capability_routing = dr.capability_routing; + else errors.push("dynamic_routing.capability_routing must be a boolean"); + } if (dr.tier_models !== undefined) { if (typeof dr.tier_models === "object" && dr.tier_models !== null) { const tm = dr.tier_models as Record; @@ -452,6 +456,40 @@ export function validatePreferences(preferences: GSDPreferences): { } } + // ─── Context Management ────────────────────────────────────────────── + if (preferences.context_management !== undefined) { + if (typeof preferences.context_management === "object" && preferences.context_management !== null) { + const cm = preferences.context_management as unknown as Record; + const validCm: Record = {}; + + if (cm.observation_masking !== undefined) { + if (typeof cm.observation_masking === "boolean") validCm.observation_masking = cm.observation_masking; + else errors.push("context_management.observation_masking must be a boolean"); + } + if (cm.observation_mask_turns !== undefined) { + const turns = cm.observation_mask_turns; + if (typeof turns === "number" && turns >= 1 && turns <= 50) validCm.observation_mask_turns = turns; + else errors.push("context_management.observation_mask_turns must be a number between 1 and 50"); + } + if (cm.compaction_threshold_percent !== undefined) { + const pct = cm.compaction_threshold_percent; + if (typeof pct === "number" && pct >= 0.5 && pct <= 0.95) validCm.compaction_threshold_percent = pct; + else errors.push("context_management.compaction_threshold_percent must be a number between 0.5 and 0.95"); + } + if (cm.tool_result_max_chars !== undefined) { + const chars = cm.tool_result_max_chars; + if (typeof chars === "number" && chars >= 200 && chars <= 10000) validCm.tool_result_max_chars = chars; + else errors.push("context_management.tool_result_max_chars must be a number between 200 and 10000"); + } + + if (Object.keys(validCm).length > 0) { + validated.context_management = validCm as any; + } + } else { + errors.push("context_management must be an object"); + } + } + // ─── Parallel Config ──────────────────────────────────────────────────── if (preferences.parallel && typeof preferences.parallel === "object") { const p = preferences.parallel as unknown as Record; @@ -492,6 +530,14 @@ export function validatePreferences(preferences: GSDPreferences): { } } + if (p.worker_model !== undefined) { + if (typeof p.worker_model === "string" && p.worker_model.length > 0) { + parallel.worker_model = p.worker_model; + } else { + errors.push("parallel.worker_model must be a non-empty string"); + } + } + if (Object.keys(parallel).length > 0) { validated.parallel = parallel as unknown as import("./types.js").ParallelConfig; } @@ -523,7 +569,15 @@ export function validatePreferences(preferences: GSDPreferences): { } } - const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode"]); + if (re.subagent_model !== undefined) { + if (typeof re.subagent_model === "string" && re.subagent_model.length > 0) { + validRe.subagent_model = re.subagent_model; + } else { + errors.push("reactive_execution.subagent_model must be a non-empty string"); + } + } + + const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode", "subagent_model"]); for (const key of Object.keys(re)) { if (!knownReKeys.has(key)) { warnings.push(`unknown reactive_execution key "${key}" — ignored`); @@ -819,5 +873,111 @@ export function validatePreferences(preferences: GSDPreferences): { } } + // ─── Codebase Map ────────────────────────────────────────────────── + if (preferences.codebase !== undefined) { + if (typeof preferences.codebase === "object" && preferences.codebase !== null) { + const cb = preferences.codebase as Record; + const validCb: import("./preferences-types.js").CodebaseMapPreferences = {}; + + if (cb.exclude_patterns !== undefined) { + if (Array.isArray(cb.exclude_patterns) && cb.exclude_patterns.every((p: unknown) => typeof p === "string")) { + validCb.exclude_patterns = cb.exclude_patterns as string[]; + } else { + errors.push("codebase.exclude_patterns must be an array of strings"); + } + } + if (cb.max_files !== undefined) { + const mf = typeof cb.max_files === "number" ? cb.max_files : Number(cb.max_files); + if (Number.isFinite(mf) && mf >= 1) { + validCb.max_files = Math.floor(mf); + } else { + errors.push("codebase.max_files must be a positive integer"); + } + } + if (cb.collapse_threshold !== undefined) { + const ct = typeof cb.collapse_threshold === "number" ? cb.collapse_threshold : Number(cb.collapse_threshold); + if (Number.isFinite(ct) && ct >= 1) { + validCb.collapse_threshold = Math.floor(ct); + } else { + errors.push("codebase.collapse_threshold must be a positive integer"); + } + } + + const knownCbKeys = new Set(["exclude_patterns", "max_files", "collapse_threshold"]); + for (const key of Object.keys(cb)) { + if (!knownCbKeys.has(key)) { + warnings.push(`unknown codebase key "${key}" — ignored`); + } + } + + if (Object.keys(validCb).length > 0) { + validated.codebase = validCb; + } + } else { + errors.push("codebase must be an object"); + } + } + + // ─── Enhanced Verification ────────────────────────────────────────────────── + if (preferences.enhanced_verification !== undefined) { + if (typeof preferences.enhanced_verification === "boolean") { + validated.enhanced_verification = preferences.enhanced_verification; + } else { + errors.push("enhanced_verification must be a boolean"); + } + } + + if (preferences.enhanced_verification_pre !== undefined) { + if (typeof preferences.enhanced_verification_pre === "boolean") { + validated.enhanced_verification_pre = preferences.enhanced_verification_pre; + } else { + errors.push("enhanced_verification_pre must be a boolean"); + } + } + + if (preferences.enhanced_verification_post !== undefined) { + if (typeof preferences.enhanced_verification_post === "boolean") { + validated.enhanced_verification_post = preferences.enhanced_verification_post; + } else { + errors.push("enhanced_verification_post must be a boolean"); + } + } + + if (preferences.enhanced_verification_strict !== undefined) { + if (typeof preferences.enhanced_verification_strict === "boolean") { + validated.enhanced_verification_strict = preferences.enhanced_verification_strict; + } else { + errors.push("enhanced_verification_strict must be a boolean"); + } + } + + // ─── Discuss Preparation ──────────────────────────────────────────── + if (preferences.discuss_preparation !== undefined) { + if (typeof preferences.discuss_preparation === "boolean") { + validated.discuss_preparation = preferences.discuss_preparation; + } else { + errors.push("discuss_preparation must be a boolean"); + } + } + + // ─── Discuss Web Research ─────────────────────────────────────────── + if (preferences.discuss_web_research !== undefined) { + if (typeof preferences.discuss_web_research === "boolean") { + validated.discuss_web_research = preferences.discuss_web_research; + } else { + errors.push("discuss_web_research must be a boolean"); + } + } + + // ─── Discuss Depth ────────────────────────────────────────────────── + if (preferences.discuss_depth !== undefined) { + const validDepths = new Set(["quick", "standard", "thorough"]); + if (typeof preferences.discuss_depth === "string" && validDepths.has(preferences.discuss_depth)) { + validated.discuss_depth = preferences.discuss_depth as GSDPreferences["discuss_depth"]; + } else { + errors.push(`discuss_depth must be one of: quick, standard, thorough`); + } + } + return { preferences: validated, errors, warnings }; } diff --git a/src/resources/extensions/gsd/preferences.ts b/src/resources/extensions/gsd/preferences.ts index 58badbd95..a2c86fdbd 100644 --- a/src/resources/extensions/gsd/preferences.ts +++ b/src/resources/extensions/gsd/preferences.ts @@ -19,6 +19,7 @@ import { parse as parseYaml } from "yaml"; import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js"; import type { DynamicRoutingConfig } from "./model-router.js"; import { normalizeStringArray } from "../shared/format-utils.js"; +import { logWarning } from "./workflow-logger.js"; import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js"; import { @@ -48,6 +49,7 @@ export type { AutoSupervisorConfig, RemoteQuestionsConfig, CmuxPreferences, + CodebaseMapPreferences, GSDPreferences, LoadedGSDPreferences, SkillResolution, @@ -69,6 +71,7 @@ export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, + isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, @@ -87,7 +90,7 @@ function gsdHome(): string { } function globalPreferencesPath(): string { - return join(gsdHome(), "PREFERENCES.md"); + return join(gsdHome(), "preferences.md"); } function legacyGlobalPreferencesPath(): string { @@ -95,16 +98,16 @@ function legacyGlobalPreferencesPath(): string { } function projectPreferencesPath(): string { - return join(gsdRoot(process.cwd()), "PREFERENCES.md"); -} -// Legacy: older versions used lowercase preferences.md. -// Check lowercase as a fallback so those files aren't silently ignored. -function globalPreferencesPathLegacy(): string { - return join(gsdHome(), "preferences.md"); -} -function projectPreferencesPathLegacy(): string { return join(gsdRoot(process.cwd()), "preferences.md"); } +// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake. +// Check uppercase as a fallback so those files aren't silently ignored. +function globalPreferencesPathUppercase(): string { + return join(gsdHome(), "PREFERENCES.md"); +} +function projectPreferencesPathUppercase(): string { + return join(gsdRoot(process.cwd()), "PREFERENCES.md"); +} export function getGlobalGSDPreferencesPath(): string { return globalPreferencesPath(); @@ -122,13 +125,13 @@ export function getProjectGSDPreferencesPath(): string { export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null { return loadPreferencesFile(globalPreferencesPath(), "global") - ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global") + ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global") ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global"); } export function loadProjectGSDPreferences(): LoadedGSDPreferences | null { return loadPreferencesFile(projectPreferencesPath(), "project") - ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project"); + ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project"); } export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null { @@ -197,10 +200,13 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG } let _warnedUnrecognizedFormat = false; +let _warnedSectionParse = false; -/** @internal Reset the warn-once flag — exported for testing only. */ +/** @internal Reset the warn-once flags — exported for testing only. */ export function _resetParseWarningFlag(): void { _warnedUnrecognizedFormat = false; + _warnedFrontmatterParse = false; + _warnedSectionParse = false; } /** @internal Exported for testing only */ @@ -221,13 +227,18 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null return parseHeadingListFormat(content); } - if (!_warnedUnrecognizedFormat) { + // Warn when a non-empty file exists but lacks frontmatter delimiters (#2036). + if (content.trim().length > 0 && !_warnedUnrecognizedFormat) { _warnedUnrecognizedFormat = true; - console.warn("[parsePreferencesMarkdown] PREFERENCES.md exists but uses an unrecognized format — skipping."); + console.warn( + "[GSD] Warning: preferences file has unrecognized format — content does not use YAML frontmatter delimiters (---). " + + "Wrap your preferences in --- fences. See https://github.com/gsd-build/gsd-2/issues/2036", + ); } return null; } +let _warnedFrontmatterParse = false; function parseFrontmatterBlock(frontmatter: string): GSDPreferences { try { const parsed = parseYaml(frontmatter); @@ -236,7 +247,11 @@ function parseFrontmatterBlock(frontmatter: string): GSDPreferences { } return parsed as GSDPreferences; } catch (e) { - console.error("[parseFrontmatterBlock] YAML parse error:", e); + // Warn at most once per session to avoid flooding TUI (#3376) + if (!_warnedFrontmatterParse) { + _warnedFrontmatterParse = true; + logWarning("guided", `YAML parse error in preferences frontmatter (suppressing further): ${(e as Error).message}`); + } return {} as GSDPreferences; } } @@ -295,8 +310,11 @@ function parseHeadingListFormat(content: string): GSDPreferences { } typed[targetSection] = value; - } catch { - /* malformed section — skip */ + } catch (e) { + if (!_warnedSectionParse) { + _warnedSectionParse = true; + logWarning("guided", `preferences section parse failed: ${(e as Error).message}`); + } } } @@ -360,6 +378,10 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr verification_commands: mergeStringLists(base.verification_commands, override.verification_commands), verification_auto_fix: override.verification_auto_fix ?? base.verification_auto_fix, verification_max_retries: override.verification_max_retries ?? base.verification_max_retries, + enhanced_verification: override.enhanced_verification ?? base.enhanced_verification, + enhanced_verification_pre: override.enhanced_verification_pre ?? base.enhanced_verification_pre, + enhanced_verification_post: override.enhanced_verification_post ?? base.enhanced_verification_post, + enhanced_verification_strict: override.enhanced_verification_strict ?? base.enhanced_verification_strict, search_provider: override.search_provider ?? base.search_provider, context_selection: override.context_selection ?? base.context_selection, auto_visualize: override.auto_visualize ?? base.auto_visualize, @@ -370,8 +392,19 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr service_tier: override.service_tier ?? base.service_tier, forensics_dedup: override.forensics_dedup ?? base.forensics_dedup, show_token_cost: override.show_token_cost ?? base.show_token_cost, - experimental: (base.experimental || override.experimental) - ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) } + codebase: (base.codebase || override.codebase) + ? { + ...(base.codebase ?? {}), + ...(override.codebase ?? {}), + // Merge exclude_patterns arrays rather than overriding + exclude_patterns: [ + ...((base.codebase?.exclude_patterns) ?? []), + ...((override.codebase?.exclude_patterns) ?? []), + ].filter(Boolean), + } + : undefined, + slice_parallel: (base.slice_parallel || override.slice_parallel) + ? { ...(base.slice_parallel ?? {}), ...(override.slice_parallel ?? {}) } : undefined, }; } @@ -519,7 +552,7 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] { * Resolve the effective git isolation mode from preferences. * Returns "none" (default), "worktree", or "branch". * - * Default is "none" so GSD works out of the box without PREFERENCES.md. + * Default is "none" so GSD works out of the box without preferences.md. * Worktree isolation requires explicit opt-in because it depends on git * branch infrastructure that must be set up before use. */ @@ -537,5 +570,6 @@ export function resolveParallelConfig(prefs: GSDPreferences | undefined): import budget_ceiling: prefs?.parallel?.budget_ceiling, merge_strategy: prefs?.parallel?.merge_strategy ?? "per-milestone", auto_merge: prefs?.parallel?.auto_merge ?? "confirm", + worker_model: prefs?.parallel?.worker_model, }; } diff --git a/src/resources/extensions/gsd/preparation.ts b/src/resources/extensions/gsd/preparation.ts new file mode 100644 index 000000000..0983eb18f --- /dev/null +++ b/src/resources/extensions/gsd/preparation.ts @@ -0,0 +1,1419 @@ +/** + * GSD Preparation — Structured brief generation for discussion LLM sessions. + * + * Produces structured briefs (codebase, prior context, ecosystem) before + * the discussion LLM session starts. + * + * Pure functions, zero UI dependencies (except for runPreparation orchestrator). + */ + +import { readdirSync, readFileSync, statSync, openSync, readSync, closeSync } from "node:fs"; +import { join, relative } from "node:path"; +import { readdirSync as readdirSyncNode } from "node:fs"; +import { + detectProjectSignals, + scanProjectFiles, + PROJECT_FILES, + type ProjectSignals, +} from "./detection.js"; +import { loadFile } from "./files.js"; + +// ─── Types ────────────────────────────────────────────────────────────────────── + +/** Detected patterns in the codebase. */ +export interface CodePatterns { + /** Primary async style: "async/await" | "callbacks" | "promises" | "mixed" */ + asyncStyle: "async/await" | "callbacks" | "promises" | "mixed" | "unknown"; + /** Primary error handling: "try/catch" | "error-callbacks" | "result-types" | "mixed" */ + errorHandling: "try/catch" | "error-callbacks" | "result-types" | "mixed" | "unknown"; + /** Primary naming convention: "camelCase" | "snake_case" | "PascalCase" | "mixed" */ + namingConvention: "camelCase" | "snake_case" | "PascalCase" | "mixed" | "unknown"; + /** Sample evidence strings for each pattern (for debugging/transparency) */ + evidence: { + asyncStyle: string[]; + errorHandling: string[]; + namingConvention: string[]; + }; + /** File counts for each pattern type (for formatted output) */ + fileCounts: { + asyncAwait: number; + promises: number; + callbacks: number; + tryCatch: number; + errorCallbacks: number; + resultTypes: number; + }; +} + +/** Language-specific pattern detection configuration. */ +export interface LanguagePatternEntry { + /** Display name for the language (e.g., "JavaScript/TypeScript") */ + displayName: string; + /** File extensions to sample for this language */ + extensions: string[]; + /** Async style detection patterns */ + asyncStyle: { + modern: RegExp; + modernLabel: string; + legacy: RegExp; + legacyLabel: string; + }; + /** Error handling detection patterns */ + errorHandling: { + structured: RegExp; + structuredLabel: string; + inline: RegExp; + inlineLabel: string; + }; +} + +/** Module structure detected in the codebase. */ +export interface ModuleStructure { + /** Top-level directories found (e.g., ["src", "lib", "test"]) */ + topLevelDirs: string[]; + /** Subdirectories within src/ or lib/ (e.g., ["components", "utils", "hooks"]) */ + srcSubdirs: string[]; + /** Total file count sampled */ + totalFilesSampled: number; +} + +/** A single decision entry parsed from DECISIONS.md. */ +export interface DecisionEntry { + id: string; + scope: string; + decision: string; + choice: string; + rationale: string; +} + +/** A single requirement entry parsed from REQUIREMENTS.md. */ +export interface RequirementEntry { + id: string; + description: string; + status: "active" | "validated" | "deferred" | "out-of-scope"; +} + +/** Prior context brief aggregated from GSD artifacts. */ +export interface PriorContextBrief { + /** Decisions grouped by scope. */ + decisions: { + byScope: Map; + totalCount: number; + }; + /** Requirements grouped by status. */ + requirements: { + active: RequirementEntry[]; + validated: RequirementEntry[]; + deferred: RequirementEntry[]; + totalCount: number; + }; + /** Knowledge entries (raw content, truncated). */ + knowledge: string; + /** Prior milestone summaries (combined, truncated). */ + summaries: string; +} + +/** Codebase analysis brief. */ +export interface CodebaseBrief { + /** Tech stack and language from detectProjectSignals */ + techStack: { + primaryLanguage?: string; + detectedFiles: string[]; + packageManager?: string; + isMonorepo: boolean; + hasTests: boolean; + hasCI: boolean; + }; + /** Module structure */ + moduleStructure: ModuleStructure; + /** Detected code patterns */ + patterns: CodePatterns; + /** Source files that were sampled for pattern extraction */ + sampledFiles: string[]; +} + +/** A single ecosystem research finding. */ +export interface EcosystemFinding { + /** Query that produced this finding */ + query: string; + /** Title or snippet from search result */ + title: string; + /** URL source */ + url?: string; + /** Brief content snippet */ + snippet: string; +} + +/** Ecosystem research brief from web search. */ +export interface EcosystemBrief { + /** Whether ecosystem research was performed */ + available: boolean; + /** Search queries that were executed */ + queries: string[]; + /** Aggregated findings from search results */ + findings: EcosystemFinding[]; + /** Reason why research was skipped (if available === false) */ + skippedReason?: string; + /** Which search provider was used */ + provider?: string; +} + +// ─── Constants ────────────────────────────────────────────────────────────────── + +/** Maximum characters for the codebase section. */ +const MAX_CODEBASE_BRIEF_CHARS = 3000; + +/** Number of files to sample for pattern extraction. */ +const SAMPLE_FILE_COUNT = 5; + +/** Maximum bytes to read from each sampled file. */ +const MAX_FILE_SAMPLE_BYTES = 8192; + +/** Directories to skip when sampling. */ +const SKIP_DIRS = new Set([ + "node_modules", + "dist", + "build", + ".git", + "coverage", + ".next", + ".nuxt", + "target", + ".turbo", + "vendor", + "__pycache__", + ".venv", + "venv", +]); + +/** File patterns to exclude when sampling. */ +const EXCLUDE_PATTERNS = [ + /\.test\.(ts|tsx|js|jsx|mjs|cjs)$/, + /\.spec\.(ts|tsx|js|jsx|mjs|cjs)$/, + /\.d\.ts$/, + /test-.*\.(ts|tsx|js|jsx)$/, + /.*\.min\.(js|css)$/, +]; + +/** File extensions to sample for pattern extraction (JS/TS default). */ +const SAMPLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]; + +/** Common source file extensions for universal pattern detection (naming convention). + * Used when the language is not in LANGUAGE_PATTERNS but we still want to detect camelCase/snake_case. */ +const UNIVERSAL_SOURCE_EXTENSIONS = [ + // JavaScript/TypeScript + ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", + // Python + ".py", ".pyw", ".pyi", + // Ruby + ".rb", ".rake", ".gemspec", + // Go + ".go", + // Rust + ".rs", + // Java/Kotlin + ".java", ".kt", ".kts", + // C/C++ + ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", + // C# + ".cs", + // Swift + ".swift", + // PHP + ".php", + // Scala + ".scala", + // Elixir/Erlang + ".ex", ".exs", ".erl", + // Haskell + ".hs", ".lhs", + // Shell + ".sh", ".bash", ".zsh", + // Lua + ".lua", + // Dart + ".dart", +]; + +// ─── Pattern Detection Regexes ────────────────────────────────────────────────── + +/** Async/await usage patterns. */ +const ASYNC_AWAIT_RE = /\basync\s+function\b|\basync\s*\(|\bawait\s+/g; + +/** Callback-style patterns (common patterns like done, callback, cb). */ +const CALLBACK_RE = /\b(callback|cb|done)\s*\(|\bfunction\s*\([^)]*\bfunction\b/g; + +/** Promise patterns (.then, .catch, new Promise). */ +const PROMISE_RE = /\.then\s*\(|\.catch\s*\(|\bnew\s+Promise\s*\(/g; + +/** Try/catch patterns. */ +const TRY_CATCH_RE = /\btry\s*\{[\s\S]*?\bcatch\s*\(/g; + +/** Error-first callback patterns. */ +const ERROR_CALLBACK_RE = /\bif\s*\(\s*(err|error)\s*\)|\(err(or)?\s*,/g; + +/** Result type patterns (Rust-style, fp-ts, etc.). */ +const RESULT_TYPE_RE = /\bResult<|\bEither<|\bisOk\(|\bisErr\(|\b(Ok|Err)\(/g; + +/** camelCase identifier patterns. */ +const CAMEL_CASE_RE = /\b[a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*\b/g; + +/** snake_case identifier patterns. */ +const SNAKE_CASE_RE = /\b[a-z][a-z0-9]*_[a-z0-9_]+\b/g; + +/** PascalCase identifier patterns (for types/classes). */ +const PASCAL_CASE_RE = /\bclass\s+[A-Z][a-zA-Z0-9]*|\binterface\s+[A-Z][a-zA-Z0-9]*|\btype\s+[A-Z][a-zA-Z0-9]*/g; + +// ─── Language Pattern Registry ────────────────────────────────────────────────── + +/** + * Registry of language-specific patterns for code analysis. + * Keys MUST match detection.ts LANGUAGE_MAP values exactly. + */ +export const LANGUAGE_PATTERNS: Record = { + "javascript/typescript": { + displayName: "JavaScript/TypeScript", + extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"], + asyncStyle: { + modern: /\basync\s+function\b|\basync\s*\(|\bawait\s+/g, + modernLabel: "async/await", + legacy: /\.then\s*\(|\.catch\s*\(|\bnew\s+Promise\s*\(/g, + legacyLabel: "promises", + }, + errorHandling: { + structured: /\btry\s*\{[\s\S]*?\bcatch\s*\(/g, + structuredLabel: "try/catch", + inline: /\bif\s*\(\s*(err|error)\s*\)|\(err(or)?\s*,/g, + inlineLabel: "error-callbacks", + }, + }, + python: { + displayName: "Python", + extensions: [".py", ".pyw", ".pyi"], + asyncStyle: { + modern: /\basync\s+def\b|\bawait\s+/g, + modernLabel: "async/await", + legacy: /\.add_done_callback\(|ThreadPoolExecutor|ProcessPoolExecutor/g, + legacyLabel: "futures/executors", + }, + errorHandling: { + structured: /\btry\s*:[\s\S]*?\bexcept\b/g, + structuredLabel: "try/except", + inline: /\braise\s+\w+Error|\bassert\s+/g, + inlineLabel: "raise/assert", + }, + }, + rust: { + displayName: "Rust", + extensions: [".rs"], + asyncStyle: { + modern: /\basync\s+fn\b|\.await\b/g, + modernLabel: "async/await", + legacy: /\bthread::spawn\(|\bmpsc::/g, + legacyLabel: "threads/channels", + }, + errorHandling: { + structured: /\bResult<|\bOption<|\?\s*;/g, + structuredLabel: "Result/Option", + inline: /\bunwrap\(\)|\bexpect\(/g, + inlineLabel: "unwrap/expect", + }, + }, + go: { + displayName: "Go", + extensions: [".go"], + asyncStyle: { + modern: /\bgo\s+func\b|\bgo\s+\w+\(/g, + modernLabel: "goroutines", + legacy: /\bchan\s+\w+|<-\s*\w+|\w+\s*<-/g, + legacyLabel: "channels", + }, + errorHandling: { + structured: /\bif\s+err\s*!=\s*nil\b/g, + structuredLabel: "if err != nil", + inline: /\bpanic\(|\brecover\(\)/g, + inlineLabel: "panic/recover", + }, + }, + java: { + displayName: "Java", + extensions: [".java"], + asyncStyle: { + modern: /\bCompletableFuture<|\bCompletionStage<|\bthenApply\(/g, + modernLabel: "CompletableFuture", + legacy: /\bThread\s+\w+\s*=|\bnew\s+Thread\(|\bExecutorService\b/g, + legacyLabel: "threads/executors", + }, + errorHandling: { + structured: /\btry\s*\{[\s\S]*?\bcatch\s*\(/g, + structuredLabel: "try/catch", + inline: /\bthrows\s+\w+Exception|\bthrow\s+new\s+\w+Exception/g, + inlineLabel: "throws/throw", + }, + }, + "java/kotlin": { + displayName: "Java/Kotlin", + extensions: [".java", ".kt", ".kts"], + asyncStyle: { + modern: /\bsuspend\s+fun\b|\blaunch\s*\{|\basync\s*\{|\bwithContext\(/g, + modernLabel: "coroutines", + legacy: /\bThread\s+\w+\s*=|\bnew\s+Thread\(|\bExecutorService\b|\bCompletableFuture { + // Get project signals from detection.ts + const signals = detectProjectSignals(basePath); + + // Detect module structure + const moduleStructure = detectModuleStructure(basePath); + + // Sample files and extract patterns, passing primary language for language-aware detection + const sampledFiles = sampleSourceFiles(basePath, signals.primaryLanguage); + const patterns = extractPatterns(basePath, sampledFiles, signals.primaryLanguage); + + return { + techStack: { + primaryLanguage: signals.primaryLanguage, + detectedFiles: signals.detectedFiles, + packageManager: signals.packageManager, + isMonorepo: signals.isMonorepo, + hasTests: signals.hasTests, + hasCI: signals.hasCI, + }, + moduleStructure, + patterns, + sampledFiles, + }; +} + +/** + * Detect the module structure of the codebase. + * + * @param basePath - Root directory of the project + * @returns ModuleStructure with top-level and src subdirs + */ +function detectModuleStructure(basePath: string): ModuleStructure { + const topLevelDirs: string[] = []; + const srcSubdirs: string[] = []; + + try { + const entries = readdirSync(basePath, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory() && !entry.name.startsWith(".") && !SKIP_DIRS.has(entry.name)) { + topLevelDirs.push(entry.name); + } + } + } catch { + // Directory not readable + } + + // Scan for subdirs in src/ or lib/ + for (const srcDir of ["src", "lib", "app"]) { + const srcPath = join(basePath, srcDir); + try { + const entries = readdirSync(srcPath, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isDirectory() && !entry.name.startsWith(".") && !SKIP_DIRS.has(entry.name)) { + srcSubdirs.push(entry.name); + } + } + } catch { + // Directory doesn't exist or not readable + } + } + + return { + topLevelDirs, + srcSubdirs: [...new Set(srcSubdirs)], // Dedupe + totalFilesSampled: 0, // Will be set after sampling + }; +} + +/** + * Sample source files from the codebase for pattern extraction. + * + * Prefers files in src/ directory, excludes test files and node_modules. + * Extension selection: + * - If language is in LANGUAGE_PATTERNS: use language-specific extensions + * - If language is undefined (no manifest): use JS/TS defaults (common case) + * - If language is set but not in LANGUAGE_PATTERNS: use UNIVERSAL_SOURCE_EXTENSIONS + * so we can still detect naming conventions even for unrecognized languages + * + * @param basePath - Root directory of the project + * @param primaryLanguage - Optional primary language identifier from detection.ts LANGUAGE_MAP + * @returns Array of relative file paths to sampled files + */ +function sampleSourceFiles(basePath: string, primaryLanguage?: string): string[] { + // Use scanProjectFiles from detection.ts for bounded recursion + const allFiles = scanProjectFiles(basePath); + + // Get extensions to sample based on language detection status + const languageEntry = primaryLanguage ? LANGUAGE_PATTERNS[primaryLanguage] : undefined; + let extensionsToSample: string[]; + + if (languageEntry) { + // Language is in registry — use its specific extensions + extensionsToSample = languageEntry.extensions; + } else if (primaryLanguage === undefined) { + // No language detected (no manifest) — use JS/TS defaults + extensionsToSample = SAMPLE_EXTENSIONS; + } else { + // Language detected but not in registry (e.g., Ruby, Haskell) + // Use universal extensions so we can still detect naming conventions + extensionsToSample = UNIVERSAL_SOURCE_EXTENSIONS; + } + + // Filter to target language files, excluding tests and dist + const candidates = allFiles.filter((file) => { + // Check extension + const hasValidExtension = extensionsToSample.some((ext) => file.endsWith(ext)); + if (!hasValidExtension) return false; + + // Check exclusion patterns + for (const pattern of EXCLUDE_PATTERNS) { + if (pattern.test(file)) return false; + } + + // Check for excluded directories in path + const parts = file.split(/[/\\]/); + for (const part of parts) { + if (SKIP_DIRS.has(part)) return false; + } + + return true; + }); + + // Prioritize files in src/ directory + const srcFiles = candidates.filter((f) => f.startsWith("src/") || f.startsWith("src\\")); + const otherFiles = candidates.filter((f) => !f.startsWith("src/") && !f.startsWith("src\\")); + + // Take SAMPLE_FILE_COUNT files, preferring src/ + const sampled: string[] = []; + + // First, add src files + for (const file of srcFiles) { + if (sampled.length >= SAMPLE_FILE_COUNT) break; + sampled.push(file); + } + + // Then add other files if needed + for (const file of otherFiles) { + if (sampled.length >= SAMPLE_FILE_COUNT) break; + sampled.push(file); + } + + return sampled; +} + +/** + * Extract code patterns from sampled files. + * + * Pattern detection behavior: + * 1. When primaryLanguage exists in LANGUAGE_PATTERNS → uses language-specific patterns + * 2. When primaryLanguage is undefined (no manifest) → falls back to JS/TS patterns + * since the sampled files are filtered by JS/TS extensions anyway + * 3. When primaryLanguage is a known value NOT in LANGUAGE_PATTERNS (e.g., "haskell", + * "elixir") → returns "unknown" for language-specific patterns instead of running + * JS/TS patterns which would produce misleading results + * + * Universal patterns (naming convention) always run regardless of language. + * + * @param basePath - Root directory of the project + * @param sampledFiles - Array of relative file paths + * @param primaryLanguage - Optional primary language identifier from detection.ts LANGUAGE_MAP + * @returns CodePatterns with detected patterns and evidence + */ +function extractPatterns(basePath: string, sampledFiles: string[], primaryLanguage?: string): CodePatterns { + const evidence = { + asyncStyle: [] as string[], + errorHandling: [] as string[], + namingConvention: [] as string[], + }; + + const counts = { + asyncAwait: 0, + callbacks: 0, + promises: 0, + tryCatch: 0, + errorCallbacks: 0, + resultTypes: 0, + camelCase: 0, + snakeCase: 0, + pascalCase: 0, + }; + + // Track how many files contain each pattern type (for formatted output) + const fileCounts = { + asyncAwait: 0, + promises: 0, + callbacks: 0, + tryCatch: 0, + errorCallbacks: 0, + resultTypes: 0, + }; + + // Get language-specific patterns if available + // When primaryLanguage is undefined, fall back to JS/TS (sampled files are JS/TS extensions) + // When primaryLanguage is set but not in registry, skip language-specific patterns entirely + const languageEntry = primaryLanguage + ? LANGUAGE_PATTERNS[primaryLanguage] + : LANGUAGE_PATTERNS["javascript/typescript"]; // Fallback for undefined only + + // Language is "unsupported" only when it's explicitly set but not in our registry + // undefined → use JS/TS fallback (the sampled files are .ts/.js anyway) + // "haskell" → unsupported, don't run JS patterns against Haskell code + const languageUnsupported = primaryLanguage !== undefined && !LANGUAGE_PATTERNS[primaryLanguage]; + + // If language is explicitly set but not in registry, add evidence explaining why patterns aren't available + if (languageUnsupported) { + evidence.asyncStyle.push(`Language "${primaryLanguage}" not in pattern registry — async style detection not available`); + evidence.errorHandling.push(`Language "${primaryLanguage}" not in pattern registry — error handling detection not available`); + } + + for (const file of sampledFiles) { + let content: string; + try { + const fullPath = join(basePath, file); + const buffer = Buffer.alloc(MAX_FILE_SAMPLE_BYTES); + const fd = openSync(fullPath, "r"); + try { + const bytesRead = readSync(fd, buffer, 0, MAX_FILE_SAMPLE_BYTES, 0); + content = buffer.toString("utf-8", 0, bytesRead); + } finally { + closeSync(fd); + } + } catch { + continue; // Skip unreadable files + } + + // Only run language-specific patterns if we have a valid language entry + // This prevents misleading results from running JS/TS patterns against Haskell, etc. + if (!languageUnsupported && languageEntry) { + // Count async patterns using language-appropriate patterns + // Use String.match() to avoid mutating lastIndex on regex with /g flag + const asyncModernMatches = content.match(languageEntry.asyncStyle.modern) || []; + counts.asyncAwait += asyncModernMatches.length; + if (asyncModernMatches.length > 0) { + fileCounts.asyncAwait++; + if (evidence.asyncStyle.length < 3) { + evidence.asyncStyle.push(`${file}: ${languageEntry.asyncStyle.modernLabel} (${asyncModernMatches.length} occurrences)`); + } + } + + // For JS/TS, also check callbacks (universal pattern) + if (primaryLanguage === "javascript/typescript") { + const callbackMatches = content.match(CALLBACK_RE) || []; + counts.callbacks += callbackMatches.length; + if (callbackMatches.length > 0) { + fileCounts.callbacks++; + if (evidence.asyncStyle.length < 3) { + evidence.asyncStyle.push(`${file}: callbacks (${callbackMatches.length} occurrences)`); + } + } + } + + const asyncLegacyMatches = content.match(languageEntry.asyncStyle.legacy) || []; + counts.promises += asyncLegacyMatches.length; + if (asyncLegacyMatches.length > 0) { + fileCounts.promises++; + if (evidence.asyncStyle.length < 3) { + evidence.asyncStyle.push(`${file}: ${languageEntry.asyncStyle.legacyLabel} (${asyncLegacyMatches.length} occurrences)`); + } + } + + // Count error handling patterns using language-appropriate patterns + const errorStructuredMatches = content.match(languageEntry.errorHandling.structured) || []; + counts.tryCatch += errorStructuredMatches.length; + if (errorStructuredMatches.length > 0) { + fileCounts.tryCatch++; + if (evidence.errorHandling.length < 3) { + evidence.errorHandling.push(`${file}: ${languageEntry.errorHandling.structuredLabel} (${errorStructuredMatches.length} occurrences)`); + } + } + + const errorInlineMatches = content.match(languageEntry.errorHandling.inline) || []; + counts.errorCallbacks += errorInlineMatches.length; + if (errorInlineMatches.length > 0) { + fileCounts.errorCallbacks++; + if (evidence.errorHandling.length < 3) { + evidence.errorHandling.push(`${file}: ${languageEntry.errorHandling.inlineLabel} (${errorInlineMatches.length} occurrences)`); + } + } + + // Result types are still useful for some languages (Rust, fp-ts) + const resultTypeMatches = content.match(RESULT_TYPE_RE) || []; + counts.resultTypes += resultTypeMatches.length; + if (resultTypeMatches.length > 0) { + fileCounts.resultTypes++; + if (evidence.errorHandling.length < 3) { + evidence.errorHandling.push(`${file}: result-types (${resultTypeMatches.length} occurrences)`); + } + } + } + + // Count naming convention patterns (universal across all languages) + // These patterns work regardless of whether the language is in the registry + const camelMatches = content.match(CAMEL_CASE_RE) || []; + counts.camelCase += camelMatches.length; + + const snakeMatches = content.match(SNAKE_CASE_RE) || []; + counts.snakeCase += snakeMatches.length; + + const pascalMatches = content.match(PASCAL_CASE_RE) || []; + counts.pascalCase += pascalMatches.length; + } + + // Add naming evidence + if (counts.camelCase > 0) { + evidence.namingConvention.push(`camelCase: ${counts.camelCase} occurrences`); + } + if (counts.snakeCase > 0) { + evidence.namingConvention.push(`snake_case: ${counts.snakeCase} occurrences`); + } + if (counts.pascalCase > 0) { + evidence.namingConvention.push(`PascalCase: ${counts.pascalCase} occurrences`); + } + + // For explicitly set but unrecognized languages, return "unknown" for language-specific patterns + // but still provide naming convention detection (which is universal) + if (languageUnsupported) { + return { + asyncStyle: "unknown", + errorHandling: "unknown", + namingConvention: determineNamingConvention(counts), + evidence, + fileCounts, + }; + } + + return { + asyncStyle: determineAsyncStyle(counts), + errorHandling: determineErrorHandling(counts), + namingConvention: determineNamingConvention(counts), + evidence, + fileCounts, + }; +} + +/** + * Determine the primary async style based on pattern counts. + */ +function determineAsyncStyle(counts: { + asyncAwait: number; + callbacks: number; + promises: number; +}): CodePatterns["asyncStyle"] { + const total = counts.asyncAwait + counts.callbacks + counts.promises; + if (total === 0) return "unknown"; + + const asyncAwaitRatio = counts.asyncAwait / total; + const callbackRatio = counts.callbacks / total; + const promiseRatio = counts.promises / total; + + // If one style dominates (>60%), report it + if (asyncAwaitRatio > 0.6) return "async/await"; + if (callbackRatio > 0.6) return "callbacks"; + if (promiseRatio > 0.6) return "promises"; + + return "mixed"; +} + +/** + * Determine the primary error handling style based on pattern counts. + */ +function determineErrorHandling(counts: { + tryCatch: number; + errorCallbacks: number; + resultTypes: number; +}): CodePatterns["errorHandling"] { + const total = counts.tryCatch + counts.errorCallbacks + counts.resultTypes; + if (total === 0) return "unknown"; + + const tryCatchRatio = counts.tryCatch / total; + const errorCallbackRatio = counts.errorCallbacks / total; + const resultTypeRatio = counts.resultTypes / total; + + if (tryCatchRatio > 0.6) return "try/catch"; + if (errorCallbackRatio > 0.6) return "error-callbacks"; + if (resultTypeRatio > 0.6) return "result-types"; + + return "mixed"; +} + +/** + * Determine the primary naming convention based on pattern counts. + */ +function determineNamingConvention(counts: { + camelCase: number; + snakeCase: number; + pascalCase: number; +}): CodePatterns["namingConvention"] { + const total = counts.camelCase + counts.snakeCase + counts.pascalCase; + if (total === 0) return "unknown"; + + // PascalCase is usually for types/classes, so we compare camelCase vs snake_case + const camelRatio = counts.camelCase / total; + const snakeRatio = counts.snakeCase / total; + + if (camelRatio > 0.6) return "camelCase"; + if (snakeRatio > 0.6) return "snake_case"; + if (counts.pascalCase > counts.camelCase && counts.pascalCase > counts.snakeCase) return "PascalCase"; + + return "mixed"; +} + +// ─── Formatting ───────────────────────────────────────────────────────────────── + +/** + * Format a CodebaseBrief as LLM-readable markdown. + * + * @param brief - The codebase brief to format + * @returns Markdown string capped at MAX_CODEBASE_BRIEF_CHARS + */ +export function formatCodebaseBrief(brief: CodebaseBrief): string { + const sections: string[] = []; + + // Tech Stack section + sections.push("## Tech Stack"); + if (brief.techStack.primaryLanguage) { + sections.push(`- **Language:** ${brief.techStack.primaryLanguage}`); + } + if (brief.techStack.packageManager) { + sections.push(`- **Package Manager:** ${brief.techStack.packageManager}`); + } + if (brief.techStack.detectedFiles.length > 0) { + const files = brief.techStack.detectedFiles.slice(0, 10).join(", "); + sections.push(`- **Project Files:** ${files}`); + } + sections.push(`- **Monorepo:** ${brief.techStack.isMonorepo ? "Yes" : "No"}`); + sections.push(`- **Has Tests:** ${brief.techStack.hasTests ? "Yes" : "No"}`); + sections.push(`- **Has CI:** ${brief.techStack.hasCI ? "Yes" : "No"}`); + + // Module Structure section + sections.push(""); + sections.push("## Module Structure"); + if (brief.moduleStructure.topLevelDirs.length > 0) { + sections.push(`- **Top-level dirs:** ${brief.moduleStructure.topLevelDirs.join(", ")}`); + } + if (brief.moduleStructure.srcSubdirs.length > 0) { + sections.push(`- **Source subdirs:** ${brief.moduleStructure.srcSubdirs.join(", ")}`); + } + + // Code Patterns section + sections.push(""); + sections.push("## Code Patterns"); + + // Format async style with file counts + const fc = brief.patterns.fileCounts; + if (brief.patterns.asyncStyle === "unknown") { + sections.push(`- **Async Style:** ${brief.patterns.asyncStyle}`); + } else { + const asyncParts: string[] = []; + if (fc.asyncAwait > 0) asyncParts.push(`${fc.asyncAwait} async/await`); + if (fc.promises > 0) asyncParts.push(`${fc.promises} .then()`); + if (fc.callbacks > 0) asyncParts.push(`${fc.callbacks} callback`); + const asyncDetail = asyncParts.length > 0 ? ` (${asyncParts.map(p => p + " files").join(" vs ")})` : ""; + sections.push(`- **Async Style:** ${brief.patterns.asyncStyle}${asyncDetail}`); + } + + // Format error handling with file counts + if (brief.patterns.errorHandling === "unknown") { + sections.push(`- **Error Handling:** ${brief.patterns.errorHandling}`); + } else { + const errorParts: string[] = []; + if (fc.tryCatch > 0) errorParts.push(`${fc.tryCatch} try/catch`); + if (fc.errorCallbacks > 0) errorParts.push(`${fc.errorCallbacks} error-callback`); + if (fc.resultTypes > 0) errorParts.push(`${fc.resultTypes} result-type`); + const errorDetail = errorParts.length > 0 ? ` (${errorParts.map(p => p + " files").join(" vs ")})` : ""; + sections.push(`- **Error Handling:** ${brief.patterns.errorHandling}${errorDetail}`); + } + + sections.push(`- **Naming Convention:** ${brief.patterns.namingConvention}`); + + let result = sections.join("\n"); + + // Truncate if necessary + if (result.length > MAX_CODEBASE_BRIEF_CHARS) { + result = result.slice(0, MAX_CODEBASE_BRIEF_CHARS - 3) + "..."; + } + + return result; +} + +// ─── Prior Context Aggregation ────────────────────────────────────────────────── + +/** Maximum characters per section in the prior context brief. */ +const MAX_SECTION_CHARS = 2000; + +/** Maximum total characters for the prior context brief. */ +const MAX_PRIOR_CONTEXT_CHARS = 6000; + +/** + * Aggregate prior context from GSD artifacts. + * + * Reads DECISIONS.md, REQUIREMENTS.md, KNOWLEDGE.md from the .gsd directory + * and milestone summaries from each milestone's MILESTONE-SUMMARY.md file. + * + * @param basePath - Root directory of the project (contains .gsd/) + * @returns PriorContextBrief with aggregated context + */ +export async function aggregatePriorContext(basePath: string): Promise { + const gsdPath = join(basePath, ".gsd"); + + // Load decisions + const decisionsContent = await loadFile(join(gsdPath, "DECISIONS.md")); + const decisions = parseDecisions(decisionsContent); + + // Load requirements + const requirementsContent = await loadFile(join(gsdPath, "REQUIREMENTS.md")); + const requirements = parseRequirements(requirementsContent); + + // Load knowledge + const knowledgeContent = await loadFile(join(gsdPath, "KNOWLEDGE.md")); + const knowledge = truncateSection(knowledgeContent || "", MAX_SECTION_CHARS); + + // Load milestone summaries + const summaries = await loadMilestoneSummaries(gsdPath); + + return { + decisions, + requirements, + knowledge: knowledge || "No prior knowledge recorded.", + summaries: summaries || "No prior milestone summaries.", + }; +} + +/** + * Parse decisions from DECISIONS.md content. + * + * Groups decisions by scope (e.g., "pattern", "architecture"). + */ +function parseDecisions(content: string | null): PriorContextBrief["decisions"] { + const byScope = new Map(); + + if (!content) { + return { byScope, totalCount: 0 }; + } + + // Parse table rows: | D001 | M001/S01 | pattern | ... | + // Skip header rows (start with | # or |---) + const lines = content.split("\n"); + let totalCount = 0; + + for (const line of lines) { + const trimmed = line.trim(); + + // Skip non-table lines, header, and separator rows + if (!trimmed.startsWith("|")) continue; + if (trimmed.startsWith("| #") || trimmed.startsWith("|---") || trimmed.startsWith("| -")) continue; + + // Parse: | D001 | M001/S01 | pattern | Decision | Choice | Rationale | Revisable? | Made By | + const cells = trimmed + .split("|") + .map((c) => c.trim()) + .filter((c) => c.length > 0); + + if (cells.length < 6) continue; + + const id = cells[0]; // D001 + if (!id.match(/^D\d+$/)) continue; // Must be a decision ID + + const scope = cells[2]; // pattern, architecture, etc. + const decision = cells[3]; + const choice = cells[4]; + const rationale = cells[5]; + + const entry: DecisionEntry = { id, scope, decision, choice, rationale }; + + if (!byScope.has(scope)) { + byScope.set(scope, []); + } + byScope.get(scope)!.push(entry); + totalCount++; + } + + return { byScope, totalCount }; +} + +/** + * Parse requirements from REQUIREMENTS.md content. + * + * Groups requirements by status (active, validated, deferred). + */ +function parseRequirements(content: string | null): PriorContextBrief["requirements"] { + const result: PriorContextBrief["requirements"] = { + active: [], + validated: [], + deferred: [], + totalCount: 0, + }; + + if (!content) { + return result; + } + + // Parse requirement entries: ### R101 — Description + // Look for Status: line to determine status + const reqBlocks = content.split(/(?=^### R\d+)/m); + + for (const block of reqBlocks) { + const idMatch = block.match(/^### (R\d+)\s*—\s*(.+)/m); + if (!idMatch) continue; + + const id = idMatch[1]; + const description = idMatch[2].trim(); + + // Extract status from "- Status: active" line + const statusMatch = block.match(/^-\s*Status:\s*(\w+)/m); + const statusRaw = statusMatch ? statusMatch[1].toLowerCase() : "active"; + + let status: RequirementEntry["status"] = "active"; + if (statusRaw === "validated") status = "validated"; + else if (statusRaw === "deferred") status = "deferred"; + else if (statusRaw === "out-of-scope" || statusRaw === "outofscope") status = "out-of-scope"; + + const entry: RequirementEntry = { id, description, status }; + + if (status === "active") result.active.push(entry); + else if (status === "validated") result.validated.push(entry); + else if (status === "deferred") result.deferred.push(entry); + + result.totalCount++; + } + + return result; +} + +/** + * Load and combine milestone summaries from each milestone directory. + * + * Returns combined content, truncated to MAX_SECTION_CHARS. + */ +async function loadMilestoneSummaries(gsdPath: string): Promise { + const milestonesPath = join(gsdPath, "milestones"); + const summaries: string[] = []; + + try { + const entries = readdirSyncNode(milestonesPath, { withFileTypes: true }); + const milestoneIds = entries + .filter((e) => e.isDirectory() && e.name.match(/^M\d+/)) + .map((e) => e.name) + .sort(); // Sort by milestone ID + + for (const mid of milestoneIds) { + const summaryPath = join(milestonesPath, mid, "MILESTONE-SUMMARY.md"); + const content = await loadFile(summaryPath); + if (content) { + // Extract the one-liner and first section for brevity + const oneLiner = extractOneLiner(content); + summaries.push(`### ${mid}\n${oneLiner}`); + } + } + } catch { + // Milestones directory doesn't exist or not readable + } + + if (summaries.length === 0) { + return ""; + } + + return truncateSection(summaries.join("\n\n"), MAX_SECTION_CHARS); +} + +/** + * Extract the one-liner summary from a MILESTONE-SUMMARY.md. + * + * Looks for bold text on a line by itself (e.g., "**Completed X and Y**"). + */ +function extractOneLiner(content: string): string { + const lines = content.split("\n"); + for (const line of lines) { + const trimmed = line.trim(); + // Look for **bold text** that's the whole line + if (trimmed.startsWith("**") && trimmed.endsWith("**") && trimmed.length > 4) { + return trimmed.slice(2, -2); + } + } + // Fallback: return first non-empty, non-heading line + for (const line of lines) { + const trimmed = line.trim(); + if (trimmed && !trimmed.startsWith("#") && !trimmed.startsWith("---")) { + return trimmed.slice(0, 200); + } + } + return "Summary available"; +} + +/** + * Truncate content to maxChars without cutting mid-section. + * + * Prefers to cut at section boundaries (## headings) or paragraph breaks. + */ +function truncateSection(content: string, maxChars: number): string { + if (content.length <= maxChars) { + return content; + } + + const SECTION_SUFFIX = "\n\n[truncated]"; // 14 chars + const WORD_SUFFIX = "... [truncated]"; // 15 chars + + // Reserve space for suffix in all slicing operations + const sectionMaxSlice = maxChars - SECTION_SUFFIX.length; + const wordMaxSlice = maxChars - WORD_SUFFIX.length; + + // Try to cut at a section boundary + const truncated = content.slice(0, sectionMaxSlice); + const lastSection = truncated.lastIndexOf("\n## "); + if (lastSection > sectionMaxSlice * 0.5) { + return truncated.slice(0, lastSection).trim() + SECTION_SUFFIX; + } + + // Try to cut at a paragraph break + const lastPara = truncated.lastIndexOf("\n\n"); + if (lastPara > sectionMaxSlice * 0.5) { + return truncated.slice(0, lastPara).trim() + SECTION_SUFFIX; + } + + // Last resort: cut at word boundary + const wordTruncated = content.slice(0, wordMaxSlice); + const lastSpace = wordTruncated.lastIndexOf(" "); + if (lastSpace > wordMaxSlice * 0.8) { + return wordTruncated.slice(0, lastSpace).trim() + WORD_SUFFIX; + } + + return content.slice(0, wordMaxSlice) + WORD_SUFFIX; +} + +/** + * Format a PriorContextBrief as LLM-readable markdown. + * + * @param brief - The prior context brief to format + * @returns Markdown string capped at MAX_PRIOR_CONTEXT_CHARS + */ +export function formatPriorContextBrief(brief: PriorContextBrief): string { + const sections: string[] = []; + + // Decisions section + sections.push("## Prior Decisions"); + if (brief.decisions.totalCount === 0) { + sections.push("No prior decisions recorded."); + } else { + sections.push(`${brief.decisions.totalCount} decisions recorded.`); + sections.push(""); + + // Group by scope + for (const [scope, entries] of brief.decisions.byScope) { + sections.push(`### ${scope}`); + for (const entry of entries.slice(0, 5)) { // Limit per scope + sections.push(`- **${entry.id}:** ${entry.decision} → ${entry.choice}`); + } + if (entries.length > 5) { + sections.push(`- _(${entries.length - 5} more in this scope)_`); + } + sections.push(""); + } + } + + // Requirements section + sections.push("## Prior Requirements"); + const reqTotal = brief.requirements.totalCount; + if (reqTotal === 0) { + sections.push("No prior requirements recorded."); + } else { + sections.push( + `${reqTotal} requirements: ${brief.requirements.active.length} active, ` + + `${brief.requirements.validated.length} validated, ` + + `${brief.requirements.deferred.length} deferred.`, + ); + sections.push(""); + + // Show active requirements (most relevant) + if (brief.requirements.active.length > 0) { + sections.push("### Active"); + for (const req of brief.requirements.active.slice(0, 10)) { + sections.push(`- **${req.id}:** ${req.description}`); + } + if (brief.requirements.active.length > 10) { + sections.push(`- _(${brief.requirements.active.length - 10} more active)_`); + } + sections.push(""); + } + + // Show validated (recently completed) + if (brief.requirements.validated.length > 0) { + sections.push("### Validated"); + for (const req of brief.requirements.validated.slice(0, 5)) { + sections.push(`- **${req.id}:** ${req.description}`); + } + if (brief.requirements.validated.length > 5) { + sections.push(`- _(${brief.requirements.validated.length - 5} more validated)_`); + } + sections.push(""); + } + } + + // Knowledge section + sections.push("## Prior Knowledge"); + if (brief.knowledge === "No prior knowledge recorded.") { + sections.push(brief.knowledge); + } else { + sections.push(truncateSection(brief.knowledge, MAX_SECTION_CHARS)); + } + sections.push(""); + + // Summaries section + sections.push("## Prior Milestone Summaries"); + if (brief.summaries === "No prior milestone summaries.") { + sections.push(brief.summaries); + } else { + sections.push(truncateSection(brief.summaries, MAX_SECTION_CHARS)); + } + + let result = sections.join("\n"); + + // Final truncation if total exceeds max + if (result.length > MAX_PRIOR_CONTEXT_CHARS) { + result = truncateSection(result, MAX_PRIOR_CONTEXT_CHARS); + } + + return result; +} + +// ─── Ecosystem Research ───────────────────────────────────────────────────────── + +/** Maximum characters for the ecosystem brief. */ +const MAX_ECOSYSTEM_BRIEF_CHARS = 4000; + +/** + * Research the ecosystem for best practices and known issues. + * + * Ecosystem research is now performed during the discussion session (between + * Layer 1 and Layer 2) using whatever web search tools are available to the + * LLM — native Anthropic web search for Claude, search-the-web for other + * providers. The preparation phase focuses on mechanical work only. + * + * @param _techStack - Array of technology names from codebase analysis (unused) + * @param _basePath - Root directory of the project (unused) + * @returns EcosystemBrief indicating research happens during discussion + */ +export async function researchEcosystem( + _techStack: string[], + _basePath: string, +): Promise { + return { + available: false, + queries: [], + findings: [], + skippedReason: "Ecosystem research is performed during the discussion using web search tools, not during preparation.", + }; +} + +/** + * Format an EcosystemBrief as LLM-readable markdown. + * + * @param brief - The ecosystem brief to format + * @returns Markdown string capped at MAX_ECOSYSTEM_BRIEF_CHARS + */ +// ─── Preparation Result ───────────────────────────────────────────────────────── + +/** + * Combined result from the preparation phase. + * Includes briefs from all three analyzers, plus metadata about the run. + */ +export interface PreparationResult { + /** Codebase analysis brief. */ + codebase: CodebaseBrief; + /** Formatted codebase brief as markdown. */ + codebaseBrief: string; + /** Prior context brief. */ + priorContext: PriorContextBrief; + /** Formatted prior context brief as markdown. */ + priorContextBrief: string; + /** Ecosystem research brief. */ + ecosystem: EcosystemBrief; + /** Formatted ecosystem brief as markdown. */ + ecosystemBrief: string; + /** Whether preparation was enabled. */ + enabled: boolean; + /** Whether ecosystem research was performed. */ + ecosystemResearchPerformed: boolean; + /** Total duration of preparation in milliseconds. */ + durationMs: number; +} + +/** + * Minimal UI context interface for preparation phase. + * Mirrors the notify method from ExtensionUIContext. + */ +export interface PreparationUIContext { + notify(message: string, type?: "info" | "warning" | "error" | "success"): void; +} + +/** + * Minimal preferences interface for preparation phase. + * Only includes the preferences needed by runPreparation. + */ +export interface PreparationPreferences { + /** Enable the preparation phase. Default: true. */ + discuss_preparation?: boolean; + /** Enable web research during preparation. Default: true. */ + discuss_web_research?: boolean; + /** Depth of analysis. Default: "standard". */ + discuss_depth?: "quick" | "standard" | "thorough"; +} + +/** + * Run the preparation phase before a discussion session. + * + * Orchestrates all three analyzers (codebase, prior context, ecosystem) + * with TUI progress updates. Returns early if preparation is disabled. + * + * @param basePath - Root directory of the project + * @param ui - UI context for progress notifications (null = silent mode) + * @param prefs - Preferences controlling preparation behavior + * @returns PreparationResult with all briefs and metadata + */ +export async function runPreparation( + basePath: string, + ui: PreparationUIContext | null, + prefs: PreparationPreferences, +): Promise { + const startTime = performance.now(); + + // Check if preparation is disabled + const preparationEnabled = prefs.discuss_preparation !== false; // Default: true + + if (!preparationEnabled) { + // Return minimal result with empty briefs + const emptyCodebase: CodebaseBrief = { + techStack: { + primaryLanguage: undefined, + detectedFiles: [], + packageManager: undefined, + isMonorepo: false, + hasTests: false, + hasCI: false, + }, + moduleStructure: { + topLevelDirs: [], + srcSubdirs: [], + totalFilesSampled: 0, + }, + patterns: { + asyncStyle: "unknown", + errorHandling: "unknown", + namingConvention: "unknown", + evidence: { + asyncStyle: [], + errorHandling: [], + namingConvention: [], + }, + fileCounts: { + asyncAwait: 0, + promises: 0, + callbacks: 0, + tryCatch: 0, + errorCallbacks: 0, + resultTypes: 0, + }, + }, + sampledFiles: [], + }; + + const emptyPriorContext: PriorContextBrief = { + decisions: { + byScope: new Map(), + totalCount: 0, + }, + requirements: { + active: [], + validated: [], + deferred: [], + totalCount: 0, + }, + knowledge: "No prior knowledge recorded.", + summaries: "No prior milestone summaries.", + }; + + const emptyEcosystem: EcosystemBrief = { + available: false, + queries: [], + findings: [], + skippedReason: "Preparation phase disabled.", + }; + + return { + codebase: emptyCodebase, + codebaseBrief: "", + priorContext: emptyPriorContext, + priorContextBrief: "", + ecosystem: emptyEcosystem, + ecosystemBrief: "", + enabled: false, + ecosystemResearchPerformed: false, + durationMs: performance.now() - startTime, + }; + } + + // --- Phase 1: Analyze codebase --- + ui?.notify("Analyzing codebase...", "info"); + const codebase = await analyzeCodebase(basePath); + const codebaseBrief = formatCodebaseBrief(codebase); + ui?.notify("✓ Analyzed codebase", "success"); + + // --- Phase 2: Review prior context --- + ui?.notify("Reviewing prior context...", "info"); + const priorContext = await aggregatePriorContext(basePath); + const priorContextBrief = formatPriorContextBrief(priorContext); + ui?.notify("✓ Reviewed prior context", "success"); + + // --- Ecosystem research --- + // Ecosystem research is now performed during the discussion session (between + // Layer 1 and Layer 2) using available web search tools. The preparation + // phase focuses on mechanical work only. + const ecosystem: EcosystemBrief = await researchEcosystem([], basePath); + const ecosystemBrief = formatEcosystemBrief(ecosystem); + + return { + codebase, + codebaseBrief, + priorContext, + priorContextBrief, + ecosystem, + ecosystemBrief, + enabled: true, + ecosystemResearchPerformed: false, + durationMs: performance.now() - startTime, + }; +} + +/** + * Format an EcosystemBrief as LLM-readable markdown. + * + * Since ecosystem research now always returns unavailable from the preparation + * phase (research happens during discussion using web search tools), this + * function returns a simple fixed message. + * + * @param _brief - The ecosystem brief (unused, always unavailable from preparation) + * @returns Markdown string directing the LLM to perform research during discussion + */ +export function formatEcosystemBrief(_brief: EcosystemBrief): string { + return "## Ecosystem Research\n\nEcosystem research is performed during the discussion using web search tools."; +} diff --git a/src/resources/extensions/gsd/prompt-loader.ts b/src/resources/extensions/gsd/prompt-loader.ts index b5e2a37ab..aa01d583a 100644 --- a/src/resources/extensions/gsd/prompt-loader.ts +++ b/src/resources/extensions/gsd/prompt-loader.ts @@ -22,6 +22,7 @@ import { GSDError, GSD_PARSE_ERROR } from "./errors.js"; import { join, dirname } from "node:path"; import { fileURLToPath } from "node:url"; import { homedir } from "node:os"; +import { logWarning } from "./workflow-logger.js"; /** * Resolve the GSD extension directory. @@ -50,6 +51,14 @@ const __extensionDir = resolveExtensionDir(); const promptsDir = join(__extensionDir, "prompts"); const templatesDir = join(__extensionDir, "templates"); +/** + * Return the resolved templates directory path for use in prompts. + * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575) + */ +export function getTemplatesDir(): string { + return templatesDir; +} + // Cache all templates eagerly at module load — a running session uses the // template versions that were on disk at startup, immune to later overwrites. const templateCache = new Map(); @@ -72,7 +81,7 @@ function warmCache(): void { // prompts/ may not exist in test environments — lazy loading still works. // Emit a diagnostic when running outside tests so wrong-path bugs are visible. if (!process.env.VITEST && !process.env.NODE_TEST) { - process.stderr.write(`[gsd:prompt-loader] warmCache: prompts dir not found: ${promptsDir}\n`); + logWarning("prompt", `warmCache: prompts dir not found: ${promptsDir}`); } } @@ -87,7 +96,7 @@ function warmCache(): void { } catch { // templates/ may not exist in test environments — lazy loading still works. if (!process.env.VITEST && !process.env.NODE_TEST) { - process.stderr.write(`[gsd:prompt-loader] warmCache: templates dir not found: ${templatesDir}\n`); + logWarning("prompt", `warmCache: templates dir not found: ${templatesDir}`); } } } @@ -134,7 +143,10 @@ export function loadPrompt(name: string, vars: Record = {}): str } for (const [key, value] of Object.entries(effectiveVars)) { - content = content.replaceAll(`{{${key}}}`, value); + // Use split/join instead of replaceAll to avoid JavaScript's special + // replacement patterns ($', $`, $&) being interpreted in the value. + // See: https://github.com/gsd-build/gsd-2/issues/2968 + content = content.split(`{{${key}}}`).join(value); } return content.trim(); diff --git a/src/resources/extensions/gsd/prompts/complete-milestone.md b/src/resources/extensions/gsd/prompts/complete-milestone.md index 91ac07e5d..ca11b93d7 100644 --- a/src/resources/extensions/gsd/prompts/complete-milestone.md +++ b/src/resources/extensions/gsd/prompts/complete-milestone.md @@ -24,9 +24,11 @@ Then: 7. Fill the **Decision Re-evaluation** table in the milestone summary. For each key decision from `.gsd/DECISIONS.md` made during this milestone, evaluate whether it is still valid given what was actually built. Flag decisions that should be revisited next milestone. 8. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof. +**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools — never via direct SQL. + ### Verification Gate — STOP if verification failed -**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 9.** +**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 10.** **Failure path** (verification failed): - Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete. @@ -37,7 +39,8 @@ Then: **Success path** (all verifications passed — continue with steps 9–13): -9. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding. +9. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted. +10. **Persist completion through `gsd_complete_milestone`.** Call it with the parameters below. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding. **Required parameters:** - `milestoneId` (string) — Milestone ID (e.g. M001) @@ -55,12 +58,11 @@ Then: **Optional parameters:** - `followUps` (string) — Follow-up items for future milestones - `deviations` (string) — Deviations from the original plan -10. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. -11. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state. +11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh. 12. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`. 13. Do not commit manually — the system auto-commits your changes after this unit completes. - Say: "Milestone {{milestoneId}} complete." -**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run. +**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run. **If a verification tool itself fails, errors, or returns unexpected output, treat it as a verification failure** — never rationalize past a tool error ("tool didn't respond, assuming success" is forbidden). A tool that cannot verify is a tool that did not verify. **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories. diff --git a/src/resources/extensions/gsd/prompts/complete-slice.md b/src/resources/extensions/gsd/prompts/complete-slice.md index e062a4aee..746729d82 100644 --- a/src/resources/extensions/gsd/prompts/complete-slice.md +++ b/src/resources/extensions/gsd/prompts/complete-slice.md @@ -21,17 +21,21 @@ All relevant context has been preloaded below — the slice plan, all task summa Then: 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above 2. {{skillActivation}} -3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first. +3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first. Task artifacts use a **flat file layout** directly inside `tasks/` (for example `T01-SUMMARY.md`, `T02-SUMMARY.md`) rather than per-task subdirectories. If you need to count or re-read task summaries during verification, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never use `tasks/*/SUMMARY.md` — that glob expects subdirectories that do not exist. 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections. 5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns. -6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database. -7. Write `{{sliceSummaryPath}}` (compress all task summaries). -8. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. +6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database. +7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts. +8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. 9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing. 10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations. -11. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically. +11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically. 12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds. -13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed. +13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh. + +**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option. + +**File system safety:** Task summaries are preloaded in the inlined context above. Task artifacts use a **flat file layout** — files such as `T01-SUMMARY.md` and `T02-SUMMARY.md` live directly inside the `tasks/` directory, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first. Never use `tasks/*/SUMMARY.md`, and never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories. **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.** diff --git a/src/resources/extensions/gsd/prompts/discuss-headless.md b/src/resources/extensions/gsd/prompts/discuss-headless.md index 6840fa749..ddd10d454 100644 --- a/src/resources/extensions/gsd/prompts/discuss-headless.md +++ b/src/resources/extensions/gsd/prompts/discuss-headless.md @@ -38,7 +38,7 @@ Do a mandatory investigation pass before making any decisions. This is not optio 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the spec references external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough. **Web search budget:** Budget carefully across investigation + focused research: -- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation. +- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation. - Prefer `search_and_read` for one-shot topic research. - Target 2-3 web searches in this investigation pass. Save remaining budget for focused research. - Do NOT repeat the same or similar queries. diff --git a/src/resources/extensions/gsd/prompts/discuss.md b/src/resources/extensions/gsd/prompts/discuss.md index 4a52b344e..4ebf24892 100644 --- a/src/resources/extensions/gsd/prompts/discuss.md +++ b/src/resources/extensions/gsd/prompts/discuss.md @@ -28,6 +28,8 @@ After reflection is confirmed, decide the approach based on the actual scope — **Anti-reduction rule:** If the user describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or try to reduce scope unless the user explicitly asks for an MVP or minimal version. When something is complex or risky, phase it into a later milestone — do not cut it. The user's ambition is the target, and your job is to sequence it intelligently, not shrink it. +{{preparationContext}} + ## Mandatory Investigation Before First Question Round Before asking your first question, do a mandatory investigation pass. This is not optional. @@ -37,7 +39,7 @@ Before asking your first question, do a mandatory investigation pass. This is no 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the user referenced external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough. **Web search budget:** You have a limited number of web searches per turn (typically 3-5). The discuss phase spans many turns (investigation, question rounds, focused research, requirements), so budget carefully: -- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation — they don't consume the web search budget. +- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation — they don't consume the web search budget. - Prefer `search_and_read` for one-shot topic research — it combines search + page fetch in a single call. - Target 2-3 web searches in the investigation pass. Save remaining budget for the focused research pass before roadmap creation. - Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. @@ -47,6 +49,26 @@ This happens ONCE, before the first round. The goal: your first questions should For subsequent rounds, continue investigating between rounds — check docs, search, or scout as needed to make each round's questions smarter. But the first-round investigation is mandatory and explicit. Distribute searches across turns rather than clustering them in one turn. +## Question Rounds + +Ask **1–3 questions per round**. Keep each round tightly focused on one or two of the depth checklist dimensions — do not try to cover all six in one round. + +**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple calls with the same or overlapping questions — wait for the user's response before asking the next round.** + +**If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round. + +After each answer set, investigate further if any answer opens a new unknown, then ask the next round. + +### Round cadence + +After each round of answers, decide whether you already have enough depth to write strong output. + +- **Incremental persistence:** After every 2 question rounds, silently save a `{{milestoneId}}-CONTEXT-DRAFT.md` using `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"` and `milestone_id: "{{milestoneId}}"`. This protects confirmed work against session crashes. Do NOT mention this save to the user. +- If not ready, continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round. +- **Depth-matching rule:** Simple, well-defined work needs fewer rounds — maybe 1–2. Large, ambiguous visions need more — maybe 4+. Do not pad rounds to hit a number. Stop when the Depth Enforcement checklist below is fully satisfied. +- Do not count the reflection step as a question round. Rounds start after reflection is confirmed. +- When you genuinely believe the depth checklist is satisfied, move to the Depth Verification step below. Do not ask a separate "ready to wrap up?" gate — the depth verification IS the gate. + ## Questioning Philosophy You are a thinking partner, not an interviewer. @@ -92,28 +114,28 @@ Do NOT offer to proceed until ALL of the following are satisfied. Track these in Before offering to proceed, demonstrate absorption: reference specific things the user emphasized, specific terminology they used, specific nuance they sharpened — and show how those shaped your understanding. Synthesize, don't recite. "Your emphasis on X led me to prioritize Y over Z" is good. "You said X, you said Y, you said Z" is not. The user should feel heard in the specifics, not just acknowledged in the abstract. -**Questioning depth should match scope.** Simple, well-defined work needs fewer rounds — maybe 1-2. Large, ambiguous visions need more — maybe 4+. Don't pad rounds to hit a number. Stop when the depth checklist is satisfied and you genuinely understand the work. - -Do not count the reflection step as a question round. Rounds start after reflection is confirmed. - ## Depth Verification Before moving to the wrap-up gate, present a structured depth summary as a checkpoint. **Print the summary as normal chat text first** — this is where the formatting renders properly. Structure the summary across the depth checklist dimensions using the user's own terminology and framing. Cover: what you understood them to be building, what shaped your understanding most (their emphasis, constraints, concerns), and any areas where you're least confident in your understanding. -**Then** use `ask_user_questions` with a short confirmation question — NOT the summary itself. The question field is designed for single sentences, not multi-paragraph summaries. +**Then confirm:** -**Convention:** The question ID must contain `depth_verification` (e.g., `depth_verification_confirm`). This naming convention enables downstream mechanical detection of this step. +**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with: +- header: "Depth Check" +- question: "Did I capture the depth right?" +- options: "Yes, you got it (Recommended)", "Not quite — let me clarify" +- **The question ID must contain `depth_verification`** (e.g., `depth_verification_confirm`) — this naming convention enables downstream mechanical detection and the write-gate. -Example flow: -1. Print in chat: the full depth summary with markdown formatting (headers, bold, bullets) -2. Call `ask_user_questions` with: header "Depth Check", question "Did I capture the depth right?", options "Yes, you got it (Recommended)" and "Not quite — let me clarify" +**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation before proceeding. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask. Never rationalize past a missing confirmation. If they clarify, absorb the correction and re-verify. The depth verification is the required write-gate. Do **not** add another meta "ready to proceed?" checkpoint immediately after it unless there is still material ambiguity. +**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around. + ## Wrap-up Gate Once the depth checklist is fully satisfied, move directly into requirements and roadmap preview. Do not insert a separate "are you ready to continue?" gate unless the user explicitly wants to keep brainstorming or you still see material ambiguity. @@ -171,7 +193,7 @@ For multi-milestone projects, requirements should span the full vision. Requirem If the project is new or has no `REQUIREMENTS.md`, surface candidate requirements in chat before writing the roadmap. Ask for correction only on material omissions, wrong ownership, or wrong scope. If the user has already been specific and raises no substantive objection, treat the requirement set as confirmed and continue. -**Print the requirements in chat before writing the roadmap.** Do not say "here are the requirements" and then only write them to a file. The user must see them in the terminal. Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope). After the table, ask: "Confirm, adjust, or add?" +**Print the requirements in chat before writing the roadmap.** Do not say "here are the requirements" and then only write them to a file. The user must see them in the terminal. Print a markdown table with columns: ID, Title, Status, Owner, Source. Group by status (Active, Deferred, Out of Scope). After the table, ask: "Confirm, adjust, or add?" **Non-bypassable:** If the user does not respond or gives an ambiguous answer, you MUST re-ask — never proceed to roadmap creation without explicit requirement confirmation. ## Scope Assessment @@ -183,7 +205,7 @@ Before moving to output, confirm the size estimate from your reflection still ho Before writing any files, **print the planned roadmap in chat** so the user can see and approve it. Print a markdown table with columns: Slice, Title, Risk, Depends, Demo. One row per slice. Below the table, print the milestone definition of done as a bullet list. -If the user raises a substantive objection, adjust the roadmap. Otherwise, present the roadmap and ask: "Ready to write, or want to adjust?" — one gate, not two. +If the user raises a substantive objection, adjust the roadmap. Otherwise, present the roadmap and ask: "Ready to write, or want to adjust?" — one gate, not two. **Non-bypassable:** If the user does not respond or gives an ambiguous answer, you MUST re-ask — never write files without explicit approval. A missing response is not a "yes." ### Naming Convention @@ -240,7 +262,7 @@ If a milestone has no dependencies, omit the frontmatter. The dependency chain f #### Phase 3: Sequential readiness gate for remaining milestones -For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then use `ask_user_questions` to let the user correct that recommendation. Present three options: +For each remaining milestone **one at a time, in sequence**, decide the most likely readiness mode from the evidence you already have, then present the three options below to the user. **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. **If `{{structuredQuestionsAvailable}}` is `false`:** present the options as a plain-text numbered list and ask the user to type their choice. **Non-bypassable:** If the user does not respond, gives an ambiguous answer, or the tool fails, you MUST re-ask — never rationalize past the block or auto-select a readiness mode. Present three options: - **"Discuss now"** — The user wants to conduct a focused discussion for this milestone in the current session, while the context from the broader discussion is still fresh. Proceed with a focused discussion for this milestone (reflection → investigation → questioning → depth verification). When the discussion concludes, write a full `CONTEXT.md`. Then move to the gate for the next milestone. - **"Write draft for later"** — This milestone has seed material from the current conversation but needs its own dedicated discussion in a future session. Write a `CONTEXT-DRAFT.md` capturing the seed material (what was discussed, key ideas, provisional scope, open questions). Mark it clearly as a draft, not a finalized context. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user: "M00x has draft context — needs discussion. Run /gsd." The `/gsd` wizard shows a "Discuss from draft" option that seeds the new discussion with this draft, so nothing from the current conversation is lost. After the dedicated discussion produces a full CONTEXT.md, the draft file is automatically deleted. @@ -252,9 +274,9 @@ Before writing each milestone's CONTEXT.md (whether primary or secondary), you M 1. **Read the actual code** for every file or module you reference. Confirm APIs exist, check what functions actually do, identify phantom capabilities (code that exists but isn't wired up). 2. **Check for stale assumptions** — the codebase changes. Verify referenced modules still work as described. -3. **Present findings** — use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID (e.g., `depth_verification_M002`). Present: what you're about to write, key technical findings from investigation, risks the code review surfaced. +3. **Present findings** — **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID (e.g., `depth_verification_M002`). Present: what you're about to write, key technical findings from investigation, risks the code review surfaced. **If `{{structuredQuestionsAvailable}}` is `false`:** present the same findings in plain text and ask for explicit confirmation before proceeding. -**The system mechanically blocks CONTEXT.md writes until the per-milestone depth verification passes.** Each milestone needs its own verification — one global verification does not unlock all milestones. +**The system mechanically blocks CONTEXT.md writes until the per-milestone depth verification passes** (structured path: user selects "(Recommended)" option; plain-text path: user explicitly confirms). Each milestone needs its own verification — one global verification does not unlock all milestones. **Why sequential, not batch:** After writing the primary milestone's context and roadmap, the agent still has context window capacity. Asking one milestone at a time lets the user decide per-milestone whether to invest that remaining capacity in a focused discussion now, or defer to a future session. A batch question ("Ready/Draft/Queue for M002, M003, M004?") forces the user to decide everything upfront without knowing how much session capacity remains. diff --git a/src/resources/extensions/gsd/prompts/doctor-heal.md b/src/resources/extensions/gsd/prompts/doctor-heal.md index 3270ae070..36181312a 100644 --- a/src/resources/extensions/gsd/prompts/doctor-heal.md +++ b/src/resources/extensions/gsd/prompts/doctor-heal.md @@ -9,6 +9,7 @@ Rules: 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content. 5. After each repair cluster, verify the relevant invariant directly from disk. 6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared. +7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes. ## Doctor Summary diff --git a/src/resources/extensions/gsd/prompts/execute-task.md b/src/resources/extensions/gsd/prompts/execute-task.md index 9428fa68a..9895dd6a4 100644 --- a/src/resources/extensions/gsd/prompts/execute-task.md +++ b/src/resources/extensions/gsd/prompts/execute-task.md @@ -12,6 +12,8 @@ A researcher explored the codebase and a planner decomposed the work — you are {{runtimeContext}} +{{phaseAnchorSection}} + {{resumeSection}} {{carryForwardSection}} @@ -30,29 +32,30 @@ Then: 0. Narrate step transitions, key implementation decisions, and verification outcomes as you work. Keep it terse — one line between tool-call clusters, not between every call — but write complete sentences in user-facing prose, not shorthand notes or scratchpad fragments. 1. {{skillActivation}} Follow any activated skills before writing code. If no skills match this task, skip this step. 2. Execute the steps in the inlined task plan, adapting minor local mismatches when the surrounding code differs from the planner's snapshot -3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature. -4. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail). -5. When implementing non-trivial runtime behavior (async flows, API boundaries, background processes, error paths), add or preserve agent-usable observability. Skip this for simple changes where it doesn't apply. +3. Before any `Write` that creates an artifact or output file, check whether that path already exists. If it does, read it first and decide whether the work is already done, should be extended, or truly needs replacement. "Create" in the plan does **not** mean the file is missing — a prior session may already have started it. +4. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature. +5. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail). +6. When implementing non-trivial runtime behavior (async flows, API boundaries, background processes, error paths), add or preserve agent-usable observability. Skip this for simple changes where it doesn't apply. **Background process rule:** Never use bare `command &` to run background processes. The shell's `&` operator leaves stdout/stderr attached to the parent, which causes the Bash tool to hang indefinitely waiting for those streams to close. Always redirect output before backgrounding: - Correct: `command > /dev/null 2>&1 &` or `nohup command > /dev/null 2>&1 &` - Example: `python -m http.server 8080 > /dev/null 2>&1 &` (NOT `python -m http.server 8080 &`) - Preferred: use the `bg_shell` tool if available — it manages process lifecycle correctly without stream-inheritance issues -6. If the task plan includes a **Failure Modes** section (Q5), implement the error/timeout/malformed handling specified. Verify each dependency's failure path is handled. Skip if the section is absent. -7. If the task plan includes a **Load Profile** section (Q6), implement protections for the identified 10x breakpoint (connection pooling, rate limiting, pagination, etc.). Skip if absent. -8. If the task plan includes a **Negative Tests** section (Q7), write the specified negative test cases alongside the happy-path tests — malformed inputs, error paths, and boundary conditions. Skip if absent. -9. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors) -10. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary. -11. After the verification gate runs (you'll see gate results in stderr/notify output), populate the `## Verification Evidence` table in your task summary with the check results. Use the `formatEvidenceTable` format: one row per check with command, exit code, verdict (✅ pass / ❌ fail), and duration. If no verification commands were discovered, note that in the section. -12. If the task touches UI, browser flows, DOM behavior, or user-visible web state: +7. If the task plan includes a **Failure Modes** section (Q5), implement the error/timeout/malformed handling specified. Verify each dependency's failure path is handled. Skip if the section is absent. +8. If the task plan includes a **Load Profile** section (Q6), implement protections for the identified 10x breakpoint (connection pooling, rate limiting, pagination, etc.). Skip if absent. +9. If the task plan includes a **Negative Tests** section (Q7), write the specified negative test cases alongside the happy-path tests — malformed inputs, error paths, and boundary conditions. Skip if absent. +10. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors) +11. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary. +12. After the verification gate runs (you'll see gate results in stderr/notify output), populate the `## Verification Evidence` table in your task summary with the check results. Use the `formatEvidenceTable` format: one row per check with command, exit code, verdict (✅ pass / ❌ fail), and duration. If no verification commands were discovered, note that in the section. +13. If the task touches UI, browser flows, DOM behavior, or user-visible web state: - exercise the real flow in the browser - prefer `browser_batch` when the next few actions are obvious and sequential - prefer `browser_assert` for explicit pass/fail verification of the intended outcome - use `browser_diff` when an action's effect is ambiguous - use console/network/dialog diagnostics when validating async, stateful, or failure-prone UI - record verification in terms of explicit checks passed/failed, not only prose interpretation -13. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section. -14. **If execution is running long or verification fails:** +14. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section. +15. **If execution is running long or verification fails:** **Context budget:** You have approximately **{{verificationBudget}}** reserved for verification context. If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step. @@ -63,16 +66,18 @@ Then: - Distinguish "I know" from "I assume." Observable facts (the error says X) are strong evidence. Assumptions (this library should work this way) need verification. - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there. - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix. -15. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice. -16. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made. -17. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things. -18. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md` -19. Write `{{taskSummaryPath}}` -20. Call `gsd_complete_task` with milestone_id, slice_id, task_id, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically. -21. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message. +16. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice. +17. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made. +18. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things. +19. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md` +20. Use that template to prepare the completion content you will pass to `gsd_complete_task` using the camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Do **not** manually write `{{taskSummaryPath}}` — the DB-backed tool is the canonical write path and renders the summary file for you. +21. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and the completion fields derived from the template. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, renders `{{taskSummaryPath}}`, and updates PLAN.md automatically. +22. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message. All work stays in your working directory: `{{workingDirectory}}`. -**You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.** +**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the task summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option. + +**You MUST call `gsd_complete_task` before finishing. Do not manually write `{{taskSummaryPath}}`.** When done, say: "Task {{taskId}} complete." diff --git a/src/resources/extensions/gsd/prompts/forensics.md b/src/resources/extensions/gsd/prompts/forensics.md index 32933af20..ffcd01151 100644 --- a/src/resources/extensions/gsd/prompts/forensics.md +++ b/src/resources/extensions/gsd/prompts/forensics.md @@ -102,6 +102,8 @@ A stale lock (PID is dead) means the previous auto-mode session crashed mid-unit A unit dispatched more than once (`type/id` appears multiple times) indicates a stuck loop — the unit completed but artifact verification failed. +{{dedupSection}} + ## Investigation Protocol 1. **Start with the pre-parsed forensic report** above. The anomaly section contains automated findings — treat these as leads, not conclusions. @@ -114,6 +116,8 @@ A unit dispatched more than once (`type/id` appears multiple times) indicates a 5. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it. + **DB inspection:** If you need to check DB state as part of investigation, use `gsd_milestone_status` — never run `sqlite3 .gsd/gsd.db` or `node -e require('better-sqlite3')` directly. The engine holds a WAL write lock; direct access will either fail or return stale data. + 6. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files. 7. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is: @@ -133,8 +137,6 @@ Explain your findings: - **Code snippet** — the problematic code and what it should do instead - **Recovery** — what the user can do right now to get unstuck -{{dedupSection}} - Then **offer GitHub issue creation**: "Would you like me to create a GitHub issue for this on gsd-build/gsd-2?" **CRITICAL: The `github_issues` tool ONLY targets the current user's repository — it has no `repo` parameter. You MUST use `gh issue create --repo gsd-build/gsd-2` via the `bash` tool to file on the correct repo. Do NOT use the `github_issues` tool for this.** diff --git a/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md b/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md index b8746d1d1..efa3cda62 100644 --- a/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md +++ b/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md @@ -8,12 +8,14 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, a ## Interview Protocol +{{fastPathInstruction}} + ### Before your first question round Do a lightweight targeted investigation so your questions are grounded in reality: - Scout the codebase (`rg`, `find`, or `scout`) to understand what already exists that this milestone touches or builds on - Check the roadmap context above (if present) to understand what surrounds this milestone -- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `web_search` for library documentation +- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation - Identify the 3–5 biggest behavioural and architectural unknowns: things where the user's answer will materially change what gets built **Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. @@ -30,7 +32,7 @@ Ask **1–3 questions per round**. Keep each question focused on one of: - **The biggest technical unknowns / risks** — what could fail, what hasn't been proven - **What external systems/services this touches** — APIs, databases, third-party services -**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. +**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` for each round. 1–3 questions per call, each as a separate question object. Keep option labels short (3–5 words). Always include a freeform "Other / let me explain" option. When the user picks that option or writes a long freeform answer, switch to plain text follow-up for that thread before resuming structured questions. **IMPORTANT: Call `ask_user_questions` exactly once per turn. Never make multiple calls with the same or overlapping questions — wait for the user's response before asking the next round.** **If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round. @@ -40,7 +42,8 @@ After the user answers, investigate further if any answer opens a new unknown, t After each round of answers, decide whether you already have enough depth to write a strong context file. -- If not, investigate any newly-opened unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round. +- **Incremental persistence:** After every 2 question rounds, silently save a `{{milestoneId}}-CONTEXT-DRAFT.md` with your current understanding using `gsd_summary_save` with `artifact_type: "CONTEXT-DRAFT"`. This protects against session crashes losing all confirmed work. Do NOT mention this save to the user — it's invisible bookkeeping. The final context file will overwrite it. +- If not ready, investigate any newly-opened unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round. - Use a single wrap-up prompt only when you genuinely believe the depth checklist is satisfied or the user signals they want to stop. - **If `{{structuredQuestionsAvailable}}` is `true` and you need that wrap-up prompt:** use `ask_user_questions` with options: - "Write the context file" *(recommended when depth is satisfied)* @@ -89,14 +92,16 @@ Before moving to the wrap-up gate, verify you have covered: - header: "Depth Check" - question: "Did I capture the depth right?" - options: "Yes, you got it (Recommended)", "Not quite — let me clarify" -- **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream. +- **The question ID must contain `depth_verification` and the milestone id** (e.g. `depth_verification_{{milestoneId}}_confirm`) — this enables the write-gate downstream and keeps verification scoped to the milestone being discussed. -**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for confirmation before proceeding. +**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for explicit confirmation before proceeding. **The same non-bypassable gate applies to the plain-text path** — if the user does not respond, gives an ambiguous answer, or does not explicitly confirm, you MUST re-ask. Never rationalize past a missing confirmation. If they clarify, absorb the correction and re-verify. The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it. +**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around. + --- ## Output diff --git a/src/resources/extensions/gsd/prompts/guided-discuss-slice.md b/src/resources/extensions/gsd/prompts/guided-discuss-slice.md index c6ab831ee..e182bc417 100644 --- a/src/resources/extensions/gsd/prompts/guided-discuss-slice.md +++ b/src/resources/extensions/gsd/prompts/guided-discuss-slice.md @@ -13,7 +13,7 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve Do a lightweight targeted investigation so your questions are grounded in reality: - Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on - Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it -- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `web_search` for library documentation +- Use `resolve_library` / `get_library_docs` for unfamiliar libraries — prefer this over `search-the-web` for library documentation - Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built **Web search budget:** You have a limited number of web searches per turn (typically 3-5). Prefer `resolve_library` / `get_library_docs` for library documentation and `search_and_read` for one-shot topic research — they are more budget-efficient. Target 2-3 web searches in the investigation pass. Distribute remaining searches across subsequent question rounds rather than clustering them. @@ -22,7 +22,9 @@ Do **not** go deep — just enough that your questions reflect what's actually t ### Question rounds -Ask **1–3 questions per round** using `ask_user_questions`. Keep each question focused on one of: +**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.** +**If `{{structuredQuestionsAvailable}}` is `false`:** Ask **1–3 questions per round** in plain text. Number them and wait for the user's response before asking the next round. +Keep each question focused on one of: - **UX and user-facing behaviour** — what does the user see, click, trigger, or experience? - **Edge cases and failure states** — what happens when things go wrong or are in unusual states? - **Scope boundaries** — what is explicitly in vs out for this slice? What deferred to later? @@ -34,17 +36,18 @@ After the user answers, investigate further if any answer opens a new unknown, t After each round of answers, decide whether you already have enough signal to write the slice context cleanly. +- **Incremental persistence:** After every 2 question rounds, silently save a draft `{{sliceId}}-CONTEXT-DRAFT.md` in `{{sliceDirPath}}` using `gsd_summary_save` with `milestone_id: {{milestoneId}}`, `slice_id: {{sliceId}}`, `artifact_type: "CONTEXT-DRAFT"`. This protects against session crashes losing confirmed work. Do NOT mention this to the user. The final context file will replace it. - If not, investigate any new unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round. - Ask a single wrap-up question only when you genuinely believe the slice is well understood or the user signals they want to stop. -- When you do ask it, use `ask_user_questions` with: - - "Write the context file" *(recommended when the slice is well understood)* - - "One more pass" +- When you do ask it, offer two choices: "Write the context file" *(recommended when the slice is well understood)* or "One more pass". Use `ask_user_questions` if available, otherwise ask in plain text. + +**CRITICAL — Non-bypassable gate:** Do NOT write the context file until the user explicitly selects "Write the context file." If `ask_user_questions` fails, errors, returns no response, or the user's response does not match a provided option, you MUST re-ask — never rationalize past the block. "Tool not responding, I'll proceed," "auth issues," or "the slice seems well understood, I'll write it" are all **forbidden**. The gate exists to protect the user's work; treat a block as an instruction to wait, not an obstacle to work around. --- ## Output -Once the user is ready to wrap up: +Once the user has explicitly confirmed they are ready to write the context file: 1. Use the **Slice Context** output template below 2. `mkdir -p {{sliceDirPath}}` diff --git a/src/resources/extensions/gsd/prompts/guided-resume-task.md b/src/resources/extensions/gsd/prompts/guided-resume-task.md index 3b15c0cad..71cbea2e5 100644 --- a/src/resources/extensions/gsd/prompts/guided-resume-task.md +++ b/src/resources/extensions/gsd/prompts/guided-resume-task.md @@ -1 +1 @@ -Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, read it, and use it as the recovery contract for where to pick up. Do **not** delete the continue file immediately. Keep it until the task is successfully completed or you have written a newer summary/continue artifact that clearly supersedes it. If the resumed attempt fails again, update or replace the continue file so no recovery context is lost. {{skillActivation}} +Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, read it, and use it as the recovery contract for where to pick up. Before you create any expected artifact or output file, check whether it already exists and read it first — a prior session may already have started or completed that work. Do **not** delete the continue file immediately. Keep it until the task is successfully completed or you have written a newer summary/continue artifact that clearly supersedes it. If the resumed attempt fails again, update or replace the continue file so no recovery context is lost. {{skillActivation}} diff --git a/src/resources/extensions/gsd/prompts/parallel-research-slices.md b/src/resources/extensions/gsd/prompts/parallel-research-slices.md new file mode 100644 index 000000000..22c18d9f6 --- /dev/null +++ b/src/resources/extensions/gsd/prompts/parallel-research-slices.md @@ -0,0 +1,23 @@ +# Parallel Slice Research + +You are dispatching parallel research agents for **{{sliceCount}} slices** in milestone **{{mid}} — {{midTitle}}**. + +## Slices to Research + +{{sliceList}} + +## Mission + +Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode**. Each subagent will independently research its slice and write a RESEARCH file. + +## Execution Protocol + +1. Call `subagent` with `tasks: [...]` containing one entry per slice below +2. Wait for ALL subagents to complete +3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory) +4. If any subagent failed to write its RESEARCH file, re-run it individually +5. Report which slices completed research and which (if any) failed + +## Subagent Prompts + +{{subagentPrompts}} diff --git a/src/resources/extensions/gsd/prompts/plan-slice.md b/src/resources/extensions/gsd/prompts/plan-slice.md index 6b38c4667..69e103f72 100644 --- a/src/resources/extensions/gsd/prompts/plan-slice.md +++ b/src/resources/extensions/gsd/prompts/plan-slice.md @@ -82,6 +82,8 @@ Then: The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`. +**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the plan. If a decision genuinely requires human input, write a note in the relevant task's description and call `gsd_plan_slice` with what you have. + **You MUST call `gsd_plan_slice` to persist the planning state before finishing.** When done, say: "Slice {{sliceId}} planned." diff --git a/src/resources/extensions/gsd/prompts/queue.md b/src/resources/extensions/gsd/prompts/queue.md index 34620bd4e..5bbdd7b2a 100644 --- a/src/resources/extensions/gsd/prompts/queue.md +++ b/src/resources/extensions/gsd/prompts/queue.md @@ -103,6 +103,8 @@ The user confirms or corrects before you write. One depth verification per miles **If you skip this step, the system will block the CONTEXT.md write and return an error telling you to complete verification first.** +**CRITICAL — Non-bypassable gate:** The system mechanically blocks CONTEXT.md writes until the user selects the "(Recommended)" option. If the user declines, cancels, or the tool fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). The gate exists to protect the user's work; treat a block as an instruction, not an obstacle to work around. + ## Output Phase Once the user is satisfied, in a single pass for **each** new milestone: diff --git a/src/resources/extensions/gsd/prompts/reassess-roadmap.md b/src/resources/extensions/gsd/prompts/reassess-roadmap.md index ca2fa55a8..64b2a6d65 100644 --- a/src/resources/extensions/gsd/prompts/reassess-roadmap.md +++ b/src/resources/extensions/gsd/prompts/reassess-roadmap.md @@ -63,4 +63,6 @@ If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, up {{commitInstruction}} +**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`. Use `gsd_milestone_status` to read current milestone and slice state. All roadmap mutations go through `gsd_reassess_roadmap` — the tool writes to the DB and re-renders ROADMAP.md atomically. + When done, say: "Roadmap reassessed." diff --git a/src/resources/extensions/gsd/prompts/rethink.md b/src/resources/extensions/gsd/prompts/rethink.md index da2a91495..9f083a9f0 100644 --- a/src/resources/extensions/gsd/prompts/rethink.md +++ b/src/resources/extensions/gsd/prompts/rethink.md @@ -12,7 +12,7 @@ You are a project reorganization assistant for a GSD (Get Shit Done) project. Th 1. Present the current milestone order as a clear numbered list with status indicators (e.g. ✅ complete, ▶ active, ⏳ pending, ⏸ parked) 2. Ask: **"What would you like to change?"** -3. Execute changes conversationally, confirming destructive operations before proceeding +3. Execute changes conversationally, confirming destructive operations before proceeding. **Non-bypassable:** For any destructive operation (discard, skip, reorder that breaks dependencies), you MUST get explicit user confirmation before executing. If the user does not respond, gives an ambiguous answer, or `ask_user_questions` fails, you MUST re-ask — never rationalize past the block. A missing confirmation is a "do not proceed." ## Supported Operations @@ -45,8 +45,20 @@ reason: "" ### Unpark a milestone Remove the `{ID}-PARKED.md` file from the milestone directory to reactivate it. +### Skip a slice +Mark a slice as skipped so auto-mode advances past it without executing. **You MUST call the `gsd_skip_slice` tool** — editing the roadmap markdown alone is NOT sufficient because auto-mode reads slice status from the database, not the roadmap file: +``` +gsd_skip_slice({ milestoneId: "M003", sliceId: "S02", reason: "Descoped — feature moved to M005" }) +``` +Skipped slices are treated as closed by the state machine (like "complete" but distinct). Use when a slice is no longer needed or has been superseded. The slice data is preserved for reference. +**Do NOT** just check the slice checkbox in the roadmap — this does not update the DB and auto-mode will resume the slice. + +**CRITICAL — Non-bypassable gate:** Skipping a slice is a permanent DB operation. You MUST confirm with the user before calling `gsd_skip_slice`. If the user does not respond or gives an ambiguous answer, you MUST re-ask — never proceed without explicit approval. + ### Discard a milestone -**Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. **Always confirm with the user before discarding.** Warn explicitly if the milestone has completed work. +**Permanently** delete a milestone directory and prune it from QUEUE-ORDER.json. + +**CRITICAL — Non-bypassable gate:** Discarding is irreversible. You MUST confirm with the user before discarding. Warn explicitly if the milestone has completed work. If the user does not respond or gives an ambiguous answer, you MUST re-ask — never rationalize past the block. A missing confirmation is a "do not discard." ### Add a new milestone Use the `gsd_milestone_generate_id` tool to get the next ID, then call `gsd_summary_save` with `milestone_id: {ID}`, `artifact_type: "CONTEXT"`, and the scope/goals/success criteria as `content` — the tool writes the context file to disk and persists to DB. Update QUEUE-ORDER.json to place it at the desired position. @@ -80,4 +92,4 @@ If a proposed order would violate constraints, explain the issue and suggest alt - Do NOT park completed milestones — it would corrupt dependency satisfaction - Park is preferred over discard when a milestone has any completed work - Always persist queue order changes to `.gsd/QUEUE-ORDER.json` -- After changes, run `git add .gsd/ && git commit -m "docs(gsd): rethink milestone plan"` to persist (rethink runs interactively outside auto-mode, so no system auto-commit) +- {{commitInstruction}} diff --git a/src/resources/extensions/gsd/prompts/system.md b/src/resources/extensions/gsd/prompts/system.md index 0d1eb0ada..45998c36e 100644 --- a/src/resources/extensions/gsd/prompts/system.md +++ b/src/resources/extensions/gsd/prompts/system.md @@ -24,13 +24,9 @@ Leave the project in a state where the next agent can immediately understand wha ## Skills -GSD ships with bundled skills. Load the relevant skill file with the `read` tool before starting work when the task matches. +GSD ships with bundled skills. Load the relevant skill file with the `read` tool before starting work when the task matches. Use bare skill names — GSD resolves them to the correct path automatically. -| Trigger | Skill to load | -|---|---| -| Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling | `~/.gsd/agent/skills/frontend-design/SKILL.md` | -| macOS or iOS apps - SwiftUI, Xcode, App Store | `~/.gsd/agent/skills/swiftui/SKILL.md` | -| Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.gsd/agent/skills/debug-like-expert/SKILL.md` | +{{bundledSkillsTable}} ## Hard Rules @@ -42,7 +38,7 @@ GSD ships with bundled skills. Load the relevant skill file with the `read` tool - Never print, echo, log, or restate secrets or credentials. Report only key names and applied/skipped status. - Never ask the user to edit `.env` files or set secrets manually. Use `secure_env_collect`. - In enduring files, write current state only unless the file is explicitly historical. -- **Never take outward-facing actions on GitHub (or any external service) without explicit user confirmation.** This includes: creating issues, closing issues, merging PRs, approving PRs, posting comments, pushing to remote branches, publishing packages, or any other action that affects state outside the local filesystem. Read-only operations (listing, viewing, diffing) are fine. Always present what you intend to do and get a clear "yes" before executing. +- **Never take outward-facing actions on GitHub (or any external service) without explicit user confirmation.** This includes: creating issues, closing issues, merging PRs, approving PRs, posting comments, pushing to remote branches, publishing packages, or any other action that affects state outside the local filesystem. Read-only operations (listing, viewing, diffing) are fine. Always present what you intend to do and get a clear "yes" before executing. **Non-bypassable:** If the user does not respond, gives an ambiguous answer, or `ask_user_questions` fails, you MUST re-ask — never rationalize past the block ("tool not responding, I'll proceed" is forbidden). A missing "yes" is a "no." If a `GSD Skill Preferences` block is present below this contract, treat it as explicit durable guidance for which skills to use, prefer, or avoid during GSD work. Follow it where it does not conflict with required GSD artifact rules, verification requirements, or higher-priority system/developer instructions. @@ -66,6 +62,7 @@ Titles live inside file content (headings, frontmatter), not in file or director REQUIREMENTS.md (requirement contract - tracks active/validated/deferred/out-of-scope) DECISIONS.md (append-only register of architectural and pattern decisions) KNOWLEDGE.md (append-only register of project-specific rules, patterns, and lessons learned) + CODEBASE.md (generated codebase map cache — auto-refreshed when tracked files change) OVERRIDES.md (user-issued overrides that supersede plan content via /gsd steer) QUEUE.md (append-only log of queued milestones via /gsd queue) STATE.md @@ -108,6 +105,7 @@ In all modes, slices commit sequentially on the active branch; there are no per- - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change. - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made - **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow. +- **CODEBASE.md** is a generated structural cache of the tracked repository. GSD auto-refreshes it when tracked files change and injects it into system context when available. Use `/gsd codebase update` only when you need to force an immediate refresh. - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing. - **Milestones** are major project phases (M001, M002, ...) - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins. @@ -119,7 +117,7 @@ In all modes, slices commit sequentially on the active branch; there are no per- ### Artifact Templates Templates showing the expected format for each artifact type are in: -`~/.gsd/agent/extensions/gsd/templates/` +`{{templatesDir}}` **Always read the relevant template before writing an artifact** to match the expected structure exactly. The parsers that read these files depend on specific formatting: @@ -135,8 +133,9 @@ Templates showing the expected format for each artifact type are in: - `/gsd status` - progress dashboard overlay - `/gsd queue` - queue future milestones (safe while auto-mode is running) - `/gsd quick ` - quick task with GSD guarantees (atomic commits, state tracking) but no milestone ceremony -- `Ctrl+Alt+G` - toggle dashboard overlay -- `Ctrl+Alt+B` - show shell processes +- `/gsd codebase [generate|update|stats]` - manage the `.gsd/CODEBASE.md` cache used for prompt context +- `{{shortcutDashboard}}` - toggle dashboard overlay +- `{{shortcutShell}}` - show shell processes ## Execution Heuristics @@ -175,6 +174,7 @@ Templates showing the expected format for each artifact type are in: - Never guess at library APIs from training data — use `get_library_docs`. - Never ask the user to run a command, set a variable, or check something you can check yourself. - Never await stale async jobs after editing source — `cancel_job` them first, then re-run. +- Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')` — the database uses a single-writer WAL connection managed by the engine. Direct access causes reader/writer conflicts and bypasses validation logic. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools exclusively for all DB reads and writes. ### Ask vs infer diff --git a/src/resources/extensions/gsd/prompts/triage-captures.md b/src/resources/extensions/gsd/prompts/triage-captures.md index 60dd5ca95..460336fe0 100644 --- a/src/resources/extensions/gsd/prompts/triage-captures.md +++ b/src/resources/extensions/gsd/prompts/triage-captures.md @@ -20,6 +20,8 @@ The user captured thoughts during execution using `/gsd capture`. Your job is to For each capture, classify it as one of: +- **stop**: User directive to halt auto-mode immediately. Use when the user says "stop", "halt", "abort", "don't continue", "pause", or otherwise wants execution to cease. Auto-mode will pause after the current unit completes. Examples: "stop running", "halt execution", "don't continue". +- **backtrack**: User directive to abandon the current milestone and return to a previous one. The user believes earlier milestones missed critical features or need rework. Include the target milestone ID (e.g., M003) in the Resolution field. Auto-mode will pause and write a regression marker. Examples: "restart from M003", "go back to milestone 3", "M004 and M005 failed, restart from M003". - **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value. - **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work. - **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement. @@ -28,10 +30,12 @@ For each capture, classify it as one of: ## Decision Guidelines +- **ALWAYS classify as stop** when the user explicitly says "stop", "halt", "abort", or "don't continue". Never shoe-horn a stop directive into "replan" or "note". +- **ALWAYS classify as backtrack** when the user references returning to a previous milestone, restarting from an earlier point, or abandoning current milestone work. Include the target milestone ID in the Resolution field (e.g., "Backtrack to M003"). - Prefer **quick-task** when the work is clearly small and self-contained. - Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones. - Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope. -- Use **replan** only when remaining incomplete tasks need to change — not just for adding work. +- Use **replan** only when remaining incomplete tasks in the *current slice* need to change — not for cross-milestone issues. - Use **note** for observations that don't require action. - When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject. @@ -46,7 +50,8 @@ For each capture, classify it as one of: - If applicable, which files would be affected For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact. - For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification. + For captures classified as **stop** or **backtrack**, auto-confirm without asking — these are urgent user directives that must be honored immediately. + For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification. **Non-bypassable:** If `ask_user_questions` fails, errors, or the user does not respond, you MUST re-ask — never auto-confirm these classifications without explicit user approval. 3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification: - Change `**Status:** pending` to `**Status:** resolved` @@ -54,6 +59,7 @@ For each capture, classify it as one of: - Add `**Resolution:** ` - Add `**Rationale:** ` - Add `**Resolved:** ` + - Add `**Milestone:** ` (e.g., `**Milestone:** M003`) 4. **Summarize** what was triaged: how many captures, what classifications were assigned, and what actions are pending (e.g., "2 quick-tasks ready for execution, 1 deferred to S03"). diff --git a/src/resources/extensions/gsd/prompts/validate-milestone.md b/src/resources/extensions/gsd/prompts/validate-milestone.md index 9653118a3..aa6aa75a6 100644 --- a/src/resources/extensions/gsd/prompts/validate-milestone.md +++ b/src/resources/extensions/gsd/prompts/validate-milestone.md @@ -1,46 +1,84 @@ -You are executing GSD auto-mode. +# Milestone Validation — Parallel Review -## UNIT: Validate Milestone {{milestoneId}} ("{{milestoneTitle}}") +You are the validation orchestrator for **{{milestoneId}} — {{milestoneTitle}}**. ## Working Directory Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. -## Your Role in the Pipeline +## Mission -All slices are done. Before the milestone can be completed, you must validate that the planned work was delivered as specified. Compare the roadmap's success criteria and slice definitions against the actual slice summaries and UAT results. This is a reconciliation gate — catch gaps, regressions, or missing deliverables before the milestone is sealed. +Dispatch 3 independent parallel reviewers, then synthesize their findings into the final VALIDATION verdict. This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues. -All relevant context has been preloaded below — the roadmap, all slice summaries, UAT results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files. +## Context + +All relevant context has been preloaded below — the roadmap, all slice summaries, assessment results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files. {{inlinedContext}} -{{skillActivation}} +## Execution Protocol -## Validation Steps +### Step 1 — Dispatch Parallel Reviewers -1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion. -2. For each **slice** in the roadmap, verify its demo/deliverable claim against its summary. Flag any slice whose summary does not substantiate its claimed output. -3. Check **cross-slice integration points** — do boundary map entries (produces/consumes) align with what was actually built? -4. Check **requirement coverage** — are all active requirements addressed by at least one slice? -5. If **Verification Classes** are provided in the inlined context above, check each non-empty class: - - For each verification class (Contract, Integration, Operational, UAT), determine whether slice summaries, UAT results, or observable behavior provide evidence that this verification tier was addressed. - - Document the compliance status of each class in a dedicated verification classes section. - - If `Operational` verification is non-empty and no evidence of operational verification exists, flag this explicitly — it means planned operational checks (migrations, deployments, runtime verification) were not proven. - - A milestone with unaddressed verification classes may still pass if the gaps are minor, but the gaps MUST be documented in the Deferred Work Inventory. -6. Determine a verdict: - - `pass` — all criteria met, all slices delivered, no gaps - - `needs-attention` — minor gaps that do not block completion (document them) - - `needs-remediation` — material gaps found; remediation slices must be added to the roadmap +Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously: -## Persist Validation +**Reviewer A — Requirements Coverage** +Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` (or equivalent requirements file). For each requirement, check the slice SUMMARY files in `.gsd/{{milestoneId}}/` to determine if it is: COVERED (clearly demonstrated), PARTIAL (mentioned but not fully demonstrated), or MISSING (no evidence). Output a markdown table with columns: Requirement | Status | Evidence. End with a one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing." -**Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verificationClasses` (when non-empty), `verdictRationale`, and `remediationPlan` (if verdict is `needs-remediation`). The tool writes the validation to the DB and renders VALIDATION.md to disk. +**Reviewer B — Cross-Slice Integration** +Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, check that the producing slice's SUMMARY confirms it produced the artifact, and the consuming slice's SUMMARY confirms it consumed it. Output a markdown table: Boundary | Producer Summary | Consumer Summary | Status. End with a one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps." + +**Reviewer C — Assessment & Acceptance Criteria** +Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for ASSESSMENT files in each slice directory. Verify each acceptance criterion maps to either a passing assessment result or clear SUMMARY evidence. Then review the inlined milestone verification classes from planning. For each non-empty planned class, output a markdown table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If no verification classes were planned, say that explicitly. Output two sections: `Acceptance Criteria` with a checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with a one-line verdict: PASS if all criteria and verification classes are covered, NEEDS-ATTENTION if gaps exist." + +### Step 2 — Synthesize Findings + +After all reviewers complete, aggregate their verdicts: +- If ALL reviewers say PASS → overall verdict: `pass` +- If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention` +- If any reviewer says FAIL → overall verdict: `needs-remediation` + +### Step 3 — Persist Validation + +Prepare the validation content you will pass to `gsd_validate_milestone`. Do **not** manually write `{{validationPath}}` — the DB-backed tool is the canonical write path and renders the validation file for you. + +```markdown +--- +verdict: +remediation_round: {{remediationRound}} +reviewers: 3 +--- + +# Milestone Validation: {{milestoneId}} + +## Reviewer A — Requirements Coverage + + +## Reviewer B — Cross-Slice Integration + + +## Reviewer C — Assessment & Acceptance Criteria + + +## Synthesis +<2-3 sentences summarizing overall findings and verdict rationale> + +## Remediation Plan + +``` + +Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`. +Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses` so the persisted validation output uses the canonical class names `Contract`, `Integration`, `Operational`, and `UAT`. + +**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation. If verdict is `needs-remediation`: -- After calling `gsd_validate_milestone`, use `gsd_reassess_roadmap` to add remediation slices. Pass `milestoneId`, a synthetic `completedSliceId` (e.g. "VALIDATION"), `verdict: "roadmap-adjusted"`, `assessment` text, and `sliceChanges` with the new slices in the `added` array. The tool persists the changes to the DB and re-renders ROADMAP.md. -- These remediation slices will be planned and executed before validation re-runs. +- Use `gsd_reassess_roadmap` to add the remediation slices instead of editing `{{roadmapPath}}` manually +- Those slices will be planned and executed before validation re-runs + +**You MUST call `gsd_validate_milestone` before finishing. Do not manually write `{{validationPath}}`.** **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories. diff --git a/src/resources/extensions/gsd/prompts/worktree-merge.md b/src/resources/extensions/gsd/prompts/worktree-merge.md index 65f865f21..5057e7255 100644 --- a/src/resources/extensions/gsd/prompts/worktree-merge.md +++ b/src/resources/extensions/gsd/prompts/worktree-merge.md @@ -90,9 +90,11 @@ Present a merge plan to the user: Ask the user to confirm the merge plan before proceeding. +**CRITICAL — Non-bypassable gate:** Do NOT execute any merge commands until the user explicitly approves the merge plan. If `ask_user_questions` fails, errors, returns no response, or the user's response is ambiguous, you MUST re-ask — never rationalize past the block. "No response, I'll proceed with the clean merges," "the plan looks safe, merging," or any other self-authorization is **forbidden**. The gate exists to protect the user's branches; treat a block as an instruction to wait, not an obstacle to work around. + ### Step 4: Execute Merge -Once confirmed, run all commands from `{{mainTreePath}}` (your CWD): +Once the user has explicitly confirmed, run all commands from `{{mainTreePath}}` (your CWD): 1. Ensure you are on the target branch: `git checkout {{mainBranch}}` 2. If there are conflicts requiring manual reconciliation, apply the reconciled versions first diff --git a/src/resources/extensions/gsd/quick.ts b/src/resources/extensions/gsd/quick.ts index aa83a5553..ad513e46d 100644 --- a/src/resources/extensions/gsd/quick.ts +++ b/src/resources/extensions/gsd/quick.ts @@ -192,28 +192,33 @@ export async function handleQuick( const taskDirRel = `.gsd/quick/${taskNum}-${slug}`; const date = new Date().toISOString().split("T")[0]; - // Create git branch for the quick task + // Create git branch for the quick task (unless isolation:none — #3337) const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {}; const git = new GitServiceImpl(basePath, gitPrefs); const branchName = `gsd/quick/${taskNum}-${slug}`; let originalBranch = git.getCurrentBranch(); - let branchCreated = false; - try { - const current = originalBranch; - if (current !== branchName) { - // Auto-commit any dirty state before switching - try { - git.autoCommit("quick-task", `Q${taskNum}`, []); - } catch { /* nothing to commit — fine */ } + const { getIsolationMode } = await import("./preferences.js"); + const usesBranch = getIsolationMode() !== "none"; - runGit(basePath, ["checkout", "-b", branchName]); - branchCreated = true; + let branchCreated = false; + if (usesBranch) { + try { + const current = originalBranch; + if (current !== branchName) { + // Auto-commit any dirty state before switching + try { + git.autoCommit("quick-task", `Q${taskNum}`, []); + } catch { /* nothing to commit — fine */ } + + runGit(basePath, ["checkout", "-b", branchName]); + branchCreated = true; + } + } catch (err) { + // Branch creation failed — continue on current branch + const message = err instanceof Error ? err.message : String(err); + ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning"); } - } catch (err) { - // Branch creation failed — continue on current branch - const message = err instanceof Error ? err.message : String(err); - ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning"); } const actualBranch = branchCreated ? branchName : git.getCurrentBranch(); diff --git a/src/resources/extensions/gsd/reactive-graph.ts b/src/resources/extensions/gsd/reactive-graph.ts index eb76999f6..dff1718df 100644 --- a/src/resources/extensions/gsd/reactive-graph.ts +++ b/src/resources/extensions/gsd/reactive-graph.ts @@ -131,6 +131,24 @@ export function isGraphAmbiguous(graph: DerivedTaskNode[]): boolean { ); } +/** + * Returns tasks that are missing IO annotations (no inputFiles and no outputFiles). + * These tasks prevent parallel dispatch by making the graph ambiguous. + * Used to surface actionable diagnostics when parallel execution falls back to sequential. + */ +export function getMissingAnnotationTasks( + graph: DerivedTaskNode[], +): Array<{ id: string; title: string }> { + return graph + .filter( + (node) => + !node.done && + node.inputFiles.length === 0 && + node.outputFiles.length === 0, + ) + .map((node) => ({ id: node.id, title: node.title })); +} + /** * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete * tasks remain. This indicates a circular dependency or impossible state. diff --git a/src/resources/extensions/gsd/repo-identity.ts b/src/resources/extensions/gsd/repo-identity.ts index 39204ab91..8de304f36 100644 --- a/src/resources/extensions/gsd/repo-identity.ts +++ b/src/resources/extensions/gsd/repo-identity.ts @@ -8,7 +8,7 @@ import { createHash } from "node:crypto"; import { execFileSync } from "node:child_process"; -import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; import { basename, dirname, join, resolve } from "node:path"; @@ -276,9 +276,14 @@ export function validateProjectId(id: string): boolean { * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected * to have already happened at startup via `validateProjectId`). * - * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated - * to 12 hex chars. Deterministic: same repo always produces the same hash - * regardless of which worktree the caller is inside. + * For repos with a remote URL, returns SHA-256 of the remote URL only — + * this makes the identity stable across directory moves/renames (#2750). + * + * For local-only repos (no remote), includes the git root in the hash. + * Local repos use a `.gsd-id` marker file for recovery after moves. + * + * Deterministic: same repo always produces the same hash regardless of + * which worktree the caller is inside. */ export function repoIdentity(basePath: string): string { const projectId = process.env.GSD_PROJECT_ID; @@ -286,8 +291,14 @@ export function repoIdentity(basePath: string): string { return projectId; } const remoteUrl = getRemoteUrl(basePath); + if (remoteUrl) { + // Remote URL alone uniquely identifies the repo — path is redundant. + // This makes moves transparent for repos with remotes (#2750). + return createHash("sha256").update(remoteUrl).digest("hex").slice(0, 12); + } + // Local-only repo: include git root since there's no remote to anchor identity. const root = resolveGitRoot(basePath); - const input = `${remoteUrl}\n${root}`; + const input = `\n${root}`; return createHash("sha256").update(input).digest("hex").slice(0, 12); } @@ -351,21 +362,148 @@ export function cleanNumberedGsdVariants(projectPath: string): string[] { return removed; } +// ─── .gsd-id Marker ───────────────────────────────────────────────────────── + +/** + * Write a `.gsd-id` marker file in the project root. + * + * This file records the identity hash used for the external state directory. + * For local-only repos (no remote), this marker survives directory moves and + * enables automatic recovery of orphaned state (#2750). + * + * The marker is gitignored by ensureGitignore(). Non-fatal: failure to write + * the marker must never block project setup. + */ +function writeGsdIdMarker(projectPath: string, identity: string): void { + try { + const markerPath = join(projectPath, ".gsd-id"); + // Only write if content differs to avoid unnecessary disk writes. + if (existsSync(markerPath)) { + try { + if (readFileSync(markerPath, "utf-8").trim() === identity) return; + } catch { /* fall through and overwrite */ } + } + writeFileSync(markerPath, identity + "\n", "utf-8"); + } catch { + // Non-fatal — marker write failure should not block project setup + } +} + +/** + * Read the `.gsd-id` marker from the project root. + * Returns the identity hash, or null if the marker doesn't exist or is unreadable. + */ +function readGsdIdMarker(projectPath: string): string | null { + try { + const markerPath = join(projectPath, ".gsd-id"); + if (!existsSync(markerPath)) return null; + const content = readFileSync(markerPath, "utf-8").trim(); + return /^[a-zA-Z0-9_-]+$/.test(content) ? content : null; + } catch { + return null; + } +} + +/** + * Check whether an external state directory has meaningful content. + * Returns true if the directory contains any files or subdirectories + * beyond just repo-meta.json. + */ +function hasProjectState(externalPath: string): boolean { + try { + if (!existsSync(externalPath)) return false; + const entries = readdirSync(externalPath); + return entries.some(e => e !== "repo-meta.json"); + } catch { + return false; + } +} + +/** + * Resolve the external state directory, with recovery for relocated projects. + * + * For local-only repos where the computed identity produces an empty state dir, + * checks the `.gsd-id` marker for the original identity hash and recovers + * the old state directory if it still exists and contains data (#2750). + * + * Returns the resolved external path (may differ from the computed identity). + */ +function resolveExternalPathWithRecovery(projectPath: string): string { + const computedPath = externalGsdRoot(projectPath); + const computedId = repoIdentity(projectPath); + + // Check if computed path already has state — fast path, no recovery needed. + if (hasProjectState(computedPath)) { + return computedPath; + } + + // Check for .gsd-id marker from a previous location. + const markerId = readGsdIdMarker(projectPath); + if (markerId && markerId !== computedId) { + // The marker points to a different identity — the repo was likely moved. + const base = process.env.GSD_STATE_DIR || gsdHome; + const markerPath = join(base, "projects", markerId); + if (hasProjectState(markerPath)) { + // Recover: use the old state directory and update the marker to the new identity. + // Move the state from the old hash dir to the new one so future lookups work + // without the marker. + try { + mkdirSync(computedPath, { recursive: true }); + const entries = readdirSync(markerPath); + for (const entry of entries) { + try { + const src = join(markerPath, entry); + const dst = join(computedPath, entry); + // Use rename for same-filesystem (fast) or fall back to copy. + try { + renameSync(src, dst); + } catch { + cpSync(src, dst, { recursive: true, force: true }); + } + } catch { /* continue with remaining entries */ } + } + // Clean up old directory after successful migration. + try { rmSync(markerPath, { recursive: true, force: true }); } catch { /* non-fatal */ } + } catch { + // If migration fails, just point at the old directory. + return markerPath; + } + } + } + + return computedPath; +} + // ─── Symlink Management ───────────────────────────────────────────────────── /** * Ensure the `/.gsd` symlink points to the external state directory. * * 1. Clean up any macOS numbered collision variants (`.gsd 2`, `.gsd 3`, etc.) - * 2. mkdir -p the external dir - * 3. If `/.gsd` doesn't exist → create symlink - * 4. If `/.gsd` is already the correct symlink → no-op - * 5. If `/.gsd` is a real directory → return as-is (migration handles later) + * 2. Resolve external dir (with relocation recovery via `.gsd-id` marker) + * 3. mkdir -p the external dir + * 4. If `/.gsd` doesn't exist → create symlink + * 5. If `/.gsd` is already the correct symlink → no-op + * 6. If `/.gsd` is a real directory → return as-is (migration handles later) + * 7. Write `.gsd-id` marker for future relocation recovery * * Returns the resolved external path. */ export function ensureGsdSymlink(projectPath: string): string { - const externalPath = externalGsdRoot(projectPath); + const result = ensureGsdSymlinkCore(projectPath); + + // Write .gsd-id marker so future relocations can recover this state (#2750). + // Only write for the project root (not subdirectories or worktrees that + // delegate to a parent .gsd). + if (!isInsideWorktree(projectPath)) { + writeGsdIdMarker(projectPath, repoIdentity(projectPath)); + } + + return result; +} + +function ensureGsdSymlinkCore(projectPath: string): string { + const externalPath = resolveExternalPathWithRecovery(projectPath); const localGsd = join(projectPath, ".gsd"); const inWorktree = isInsideWorktree(projectPath); @@ -418,12 +556,28 @@ export function ensureGsdSymlink(projectPath: string): string { const replaceWithSymlink = (): string => { rmSync(localGsd, { recursive: true, force: true }); + // Defensive: remove any residual entry (e.g. dangling symlink) before creating. + try { unlinkSync(localGsd); } catch { /* already gone */ } symlinkSync(externalPath, localGsd, "junction"); return externalPath; }; + // Check for dangling symlinks (e.g. after relocation recovery removed the old + // state dir). existsSync follows symlinks, so it returns false for dangling ones. + // lstatSync does NOT follow, so we can detect the dangling symlink and replace it. if (!existsSync(localGsd)) { - // Nothing exists yet — create symlink + try { + const stat = lstatSync(localGsd); + if (stat.isSymbolicLink()) { + // Dangling symlink — replace with correct one (#2750). + return replaceWithSymlink(); + } + } catch { + // lstat also failed — nothing exists at this path + } + // Nothing exists yet — create symlink. + // Defensive: remove any residual entry to avoid EEXIST race (#2750). + try { unlinkSync(localGsd); } catch { /* nothing to remove */ } symlinkSync(externalPath, localGsd, "junction"); return externalPath; } @@ -442,6 +596,27 @@ export function ensureGsdSymlink(projectPath: string): string { if (inWorktree) { return replaceWithSymlink(); } + // After identity hash change (e.g. upgrade from path-based to remote-only + // hash, or relocation recovery), migrate data from old target to new path + // and update the symlink (#2750). + if (!hasProjectState(externalPath) && hasProjectState(target)) { + try { + mkdirSync(externalPath, { recursive: true }); + const oldEntries = readdirSync(target); + for (const entry of oldEntries) { + try { + const src = join(target, entry); + const dst = join(externalPath, entry); + try { renameSync(src, dst); } catch { cpSync(src, dst, { recursive: true, force: true }); } + } catch { /* continue */ } + } + try { rmSync(target, { recursive: true, force: true }); } catch { /* non-fatal */ } + return replaceWithSymlink(); + } catch { + // Migration failed — preserve old symlink + return target; + } + } // Outside worktrees, preserve custom overrides or legacy symlinks. return target; } diff --git a/src/resources/extensions/gsd/rethink.ts b/src/resources/extensions/gsd/rethink.ts index a6f049b77..1f7d3e0dd 100644 --- a/src/resources/extensions/gsd/rethink.ts +++ b/src/resources/extensions/gsd/rethink.ts @@ -19,6 +19,7 @@ import { isParked, getParkedReason } from "./milestone-actions.js"; import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js"; import { buildExistingMilestonesContext } from "./guided-flow-queue.js"; import { loadPrompt } from "./prompt-loader.js"; +import { isGsdGitignored } from "./gitignore.js"; // ─── Entry Point ────────────────────────────────────────────────────────────── @@ -53,9 +54,14 @@ export async function handleRethink( const rethinkData = buildRethinkData(basePath, milestoneIds, state, queueOrder); const existingMilestonesContext = await buildExistingMilestonesContext(basePath, milestoneIds, state); + const commitInstruction = isGsdGitignored(basePath) + ? "Do not commit planning artifacts — .gsd/ is gitignored in this project." + : 'After changes, run `git add .gsd/ && git commit -m "docs(gsd): rethink milestone plan"` to persist (rethink runs interactively outside auto-mode, so no system auto-commit)'; + const content = loadPrompt("rethink", { rethinkData, existingMilestonesContext, + commitInstruction, }); pi.sendMessage( @@ -106,8 +112,11 @@ function buildRethinkData( if (dbAvailable && status !== "complete") { const slices = getMilestoneSlices(mid); if (slices.length > 0) { - const done = slices.filter(s => s.status === "complete").length; - sliceInfo = `${done}/${slices.length} complete`; + const done = slices.filter(s => s.status === "complete" || s.status === "done").length; + const skipped = slices.filter(s => s.status === "skipped").length; + sliceInfo = skipped > 0 + ? `${done}/${slices.length} complete, ${skipped} skipped` + : `${done}/${slices.length} complete`; } } diff --git a/src/resources/extensions/gsd/roadmap-mutations.ts b/src/resources/extensions/gsd/roadmap-mutations.ts index 39521462b..251c315a9 100644 --- a/src/resources/extensions/gsd/roadmap-mutations.ts +++ b/src/resources/extensions/gsd/roadmap-mutations.ts @@ -39,7 +39,7 @@ export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: strin new RegExp(`^(#{1,4}\\s+(?:\\*{0,2})(?:Slice\\s+)?${sid}\\*{0,2}[:\\s.\\u2014\\u2013-]+\\s*)(.+)`, "m"), (match, prefix, title) => { // Already marked done — no-op - if (/^\u2713/.test(title) || /\(Complete\)\s*$/i.test(title)) return match; + if (/^[\u2713\u2705]/.test(title) || /[\u2705]\s*$/.test(title) || /\(Complete\)\s*$/i.test(title)) return match; return `${prefix}\u2713 ${title}`; }, ); diff --git a/src/resources/extensions/gsd/roadmap-slices.ts b/src/resources/extensions/gsd/roadmap-slices.ts index 5031f004f..33ec34b83 100644 --- a/src/resources/extensions/gsd/roadmap-slices.ts +++ b/src/resources/extensions/gsd/roadmap-slices.ts @@ -66,6 +66,17 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] { const lines = section.split("\n"); const slices: RoadmapSliceEntry[] = []; + // Detect dependency column index from the header row (#3383, #3336). + // Only parse deps from this column (or cells with explicit "depends"/"deps" keywords). + let depColumnIndex = -1; + for (const line of lines) { + if (!line.includes("|")) continue; + if (/S\d+/.test(line)) break; // reached data rows + const headerCells = line.split("|").map(c => c.trim()).filter(Boolean); + depColumnIndex = headerCells.findIndex(c => /^(depends|deps|depend)/i.test(c)); + if (depColumnIndex >= 0) break; + } + for (const line of lines) { // Skip non-table lines, separator lines (|---|---|), and header rows if (!line.includes("|")) continue; @@ -82,7 +93,7 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] { const fullRow = line.toLowerCase(); const done = /\[x\]/i.test(line) || - /[✅☑✓]/.test(line) || + /[✅☑✓✔]/.test(line) || /\bdone\b/.test(fullRow) || /\bcomplete(?:d)?\b/.test(fullRow); @@ -95,12 +106,17 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] { if (/\bmedium\b/.test(cellLower) || /\bmed\b/.test(cellLower)) { risk = "medium"; break; } } - // Extract dependencies from cells containing S-prefixed IDs (excluding the slice's own ID) + // Extract dependencies only from the dependency column or cells with + // explicit "depends"/"deps" keywords — never from title cells (#3383). let depends: string[] = []; - for (const cell of cells) { - if (/depends|deps/i.test(cell) || (cell.match(/S\d+/g)?.length ?? 0) > 0) { - const depIds = (cell.match(/S\d+/g) ?? []).filter(d => d !== id); - if (depIds.length > 0 || /none|—|-/i.test(cell)) { + if (depColumnIndex >= 0 && cells[depColumnIndex]) { + const depCell = cells[depColumnIndex]!; + const depIds = (depCell.match(/S\d+/g) ?? []).filter(d => d !== id); + depends = expandDependencies(depIds); + } else { + for (const cell of cells) { + if (/depends|deps/i.test(cell)) { + const depIds = (cell.match(/S\d+/g) ?? []).filter(d => d !== id); depends = expandDependencies(depIds); break; } @@ -219,13 +235,14 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] { function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] { const slices: RoadmapSliceEntry[] = []; // Match H1-H4 headers containing S with optional "Slice" prefix, bold markers, - // and optional checkmark completion marker before the slice ID. + // numeric prefixes (e.g., "1.", "(1)"), bracketed IDs (e.g., "[S01]"), + // optional checkmark completion marker, and optional leading indentation. // Separator after the ID is flexible: colon, dash, em/en dash, dot, or just whitespace. - const headerPattern = /^#{1,4}\s+\*{0,2}(?:\u2713\s+)?(?:Slice\s+)?(S\d+)\*{0,2}[:\s.\u2014\u2013-]*\s*(.+)/gm; + const headerPattern = /^\s*#{1,4}\s+\*{0,2}(?:[\u2713\u2705]\s+)?(?:\d+[.)]\s+)?(?:\(\d+\)\s+)?(?:Slice\s+)?\[?(S\d+)\]?\*{0,2}[:\s.\u2014\u2013-]*\s*(.+)/gm; let match: RegExpExecArray | null; // Check for checkmark before the slice ID (e.g., "## checkmark S01: Title") - const prefixCheckPattern = /^#{1,4}\s+\*{0,2}\u2713\s+/; + const prefixCheckPattern = /^\s*#{1,4}\s+\*{0,2}[\u2713\u2705]\s+/; while ((match = headerPattern.exec(content)) !== null) { const id = match[1]!; @@ -239,9 +256,14 @@ function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] { const line = match[0]; let done = prefixCheckPattern.test(line); - if (!done && title.startsWith("\u2713")) { + if (!done && /^[\u2713\u2705]/.test(title)) { done = true; - title = title.replace(/^\u2713\s*/, ""); + title = title.replace(/^[\u2713\u2705]\s*/, ""); + } + + if (!done && /[\u2705]\s*$/.test(title)) { + done = true; + title = title.replace(/\s*[\u2705]\s*$/, ""); } if (!done && /\(Complete\)\s*$/i.test(title)) { @@ -251,7 +273,7 @@ function parseProseSliceHeaders(content: string): RoadmapSliceEntry[] { // Try to extract depends from prose: "Depends on: S01" or "**Depends on:** S01, S02" const afterHeader = content.slice(match.index + match[0].length); - const nextHeader = afterHeader.search(/^#{1,4}\s/m); + const nextHeader = afterHeader.search(/^\s*#{1,4}\s/m); const section = nextHeader !== -1 ? afterHeader.slice(0, nextHeader) : afterHeader.slice(0, 500); const depsMatch = section.match(/\*{0,2}Depends\s+on:?\*{0,2}\s*(.+)/i); diff --git a/src/resources/extensions/gsd/rule-registry.ts b/src/resources/extensions/gsd/rule-registry.ts index e61893606..7a697257a 100644 --- a/src/resources/extensions/gsd/rule-registry.ts +++ b/src/resources/extensions/gsd/rule-registry.ts @@ -6,6 +6,7 @@ // // A module-level singleton accessor allows existing code to migrate incrementally. +import { logWarning } from "./workflow-logger.js"; import type { UnifiedRule, RulePhase } from "./rule-types.js"; import type { DispatchAction, DispatchContext, DispatchRule } from "./auto-dispatch.js"; import type { @@ -387,8 +388,8 @@ export class RuleRegistry { const dir = join(basePath, ".gsd"); if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); writeFileSync(this._hookStatePath(basePath), JSON.stringify(state, null, 2), "utf-8"); - } catch { - // Non-fatal — state is recreatable from artifacts + } catch (e) { + logWarning("registry", `failed to persist hook state: ${(e as Error).message}`); } } @@ -407,8 +408,8 @@ export class RuleRegistry { } } } - } catch { - // Non-fatal — fresh state is fine + } catch (e) { + logWarning("registry", `failed to restore hook state: ${(e as Error).message}`); } } @@ -423,8 +424,8 @@ export class RuleRegistry { "utf-8", ); } - } catch { - // Non-fatal + } catch (e) { + logWarning("registry", `failed to clear hook state: ${(e as Error).message}`); } } diff --git a/src/resources/extensions/gsd/safe-fs.ts b/src/resources/extensions/gsd/safe-fs.ts index 8872b8b28..3080c00be 100644 --- a/src/resources/extensions/gsd/safe-fs.ts +++ b/src/resources/extensions/gsd/safe-fs.ts @@ -1,23 +1,24 @@ import { existsSync, mkdirSync, cpSync, type CopySyncOptions } from "node:fs" import { dirname } from "node:path" +import { logWarning } from "./workflow-logger.js" /** * Safely creates a directory. Returns true if successful, false on error. - * Logs to stderr when GSD_DEBUG is set. + * Logs warnings via workflow-logger on failure. */ export function safeMkdir(dirPath: string): boolean { try { mkdirSync(dirPath, { recursive: true }) return true } catch (err) { - if (process.env.GSD_DEBUG) console.error(`[gsd] mkdir failed: ${dirPath}`, err) + logWarning("fs", `mkdir failed: ${dirPath}: ${(err as Error).message}`) return false } } /** * Safely copies src to dst. Returns true if successful, false if src doesn't exist or copy fails. - * Logs to stderr when GSD_DEBUG is set. + * Logs warnings via workflow-logger on failure. */ export function safeCopy(src: string, dst: string, opts?: CopySyncOptions): boolean { if (!existsSync(src)) return false @@ -25,7 +26,7 @@ export function safeCopy(src: string, dst: string, opts?: CopySyncOptions): bool cpSync(src, dst, opts) return true } catch (err) { - if (process.env.GSD_DEBUG) console.error(`[gsd] copy failed: ${src} → ${dst}`, err) + logWarning("fs", `copy failed: ${src} → ${dst}: ${(err as Error).message}`) return false } } @@ -41,7 +42,7 @@ export function safeCopyRecursive(src: string, dst: string, opts?: Omit + */ + +import { existsSync, readFileSync } from "node:fs"; +import { logWarning } from "../workflow-logger.js"; + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface ContentViolation { + severity: "warning"; + reason: string; +} + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Validate content quality for a completed unit. + * Returns an array of violations. Empty array = content looks acceptable. + * + * @param unitType - The type of unit that completed (e.g. "plan-slice") + * @param artifactPath - Absolute path to the primary artifact file + */ +export function validateContent( + unitType: string, + artifactPath: string | null, +): ContentViolation[] { + if (!artifactPath || !existsSync(artifactPath)) return []; + + const validator = VALIDATORS[unitType]; + if (!validator) return []; + + try { + const content = readFileSync(artifactPath, "utf-8"); + return validator(content); + } catch (e) { + logWarning("safety", `content validation read failed: ${(e as Error).message}`); + return []; + } +} + +// ─── Validators ───────────────────────────────────────────────────────────── + +type ContentValidatorFn = (content: string) => ContentViolation[]; + +const VALIDATORS: Record = { + "plan-slice": validatePlanSlice, + "plan-milestone": validatePlanMilestone, +}; + +function validatePlanSlice(content: string): ContentViolation[] { + const violations: ContentViolation[] = []; + + // Must have at least 1 task entry — single-task slices are valid (#3649) + const taskCount = (content.match(/- \[[ x]\] \*\*T\d+/g) || []).length; + if (taskCount < 1) { + violations.push({ + severity: "warning", + reason: `Slice plan has ${taskCount} task(s) — expected at least 1`, + }); + } + + // Should have a Files Likely Touched section + if (!content.includes("## Files Likely Touched") && !content.includes("## Files")) { + violations.push({ + severity: "warning", + reason: "Slice plan missing 'Files Likely Touched' section", + }); + } + + // Should have a verification section + if (!content.includes("Verify") && !content.includes("verify")) { + violations.push({ + severity: "warning", + reason: "Slice plan has no verification instructions", + }); + } + + return violations; +} + +function validatePlanMilestone(content: string): ContentViolation[] { + const violations: ContentViolation[] = []; + + // Must have at least 1 slice entry + const sliceCount = (content.match(/##\s+S\d+/g) || []).length; + if (sliceCount < 1) { + violations.push({ + severity: "warning", + reason: `Milestone roadmap has ${sliceCount} slice(s) — expected at least 1`, + }); + } + + return violations; +} diff --git a/src/resources/extensions/gsd/safety/destructive-guard.ts b/src/resources/extensions/gsd/safety/destructive-guard.ts new file mode 100644 index 000000000..9d8e635bd --- /dev/null +++ b/src/resources/extensions/gsd/safety/destructive-guard.ts @@ -0,0 +1,49 @@ +/** + * Destructive command classifier for auto-mode safety harness. + * Classifies bash commands and warns on potentially destructive operations. + * Does NOT block — only classifies for logging/notification. + * + * Copyright (c) 2026 Jeremy McSpadden + */ + +// ─── Pattern Definitions ──────────────────────────────────────────────────── + +interface DestructivePattern { + pattern: RegExp; + label: string; +} + +const DESTRUCTIVE_PATTERNS: readonly DestructivePattern[] = [ + { pattern: /\brm\s+(-[^\s]*[rfRF][^\s]*\s+|.*\s+-[^\s]*[rfRF])/, label: "recursive delete" }, + { pattern: /\bgit\s+push\s+.*--force/, label: "force push" }, + { pattern: /\bgit\s+push\s+-f\b/, label: "force push" }, + { pattern: /\bgit\s+reset\s+--hard/, label: "hard reset" }, + { pattern: /\bgit\s+clean\s+-[^\s]*[fdxFDX]/, label: "git clean" }, + { pattern: /\bgit\s+checkout\s+--\s+\./, label: "discard all changes" }, + { pattern: /\bdrop\s+(database|table|index)\b/i, label: "SQL drop" }, + { pattern: /\btruncate\s+table\b/i, label: "SQL truncate" }, + { pattern: /\bchmod\s+777\b/, label: "world-writable permissions" }, + { pattern: /\bcurl\s.*\|\s*(bash|sh|zsh)\b/, label: "pipe to shell" }, +]; + +// ─── Public API ───────────────────────────────────────────────────────────── + +export interface CommandClassification { + destructive: boolean; + labels: string[]; +} + +/** + * Classify a bash command for destructive operations. + * Returns the list of matched destructive pattern labels. + */ +export function classifyCommand(command: string): CommandClassification { + const labels: string[] = []; + for (const { pattern, label } of DESTRUCTIVE_PATTERNS) { + if (pattern.test(command)) { + // Deduplicate labels (e.g., two force-push patterns) + if (!labels.includes(label)) labels.push(label); + } + } + return { destructive: labels.length > 0, labels }; +} diff --git a/src/resources/extensions/gsd/safety/evidence-collector.ts b/src/resources/extensions/gsd/safety/evidence-collector.ts new file mode 100644 index 000000000..9d57363cf --- /dev/null +++ b/src/resources/extensions/gsd/safety/evidence-collector.ts @@ -0,0 +1,151 @@ +/** + * Real-time tool call evidence collector for auto-mode safety harness. + * Tracks every bash command, file write, and file edit during a unit execution. + * Evidence is compared against LLM completion claims in evidence-cross-ref.ts. + * + * Follows the same module-level Map pattern as auto-tool-tracking.ts. + * Copyright (c) 2026 Jeremy McSpadden + */ + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface BashEvidence { + kind: "bash"; + toolCallId: string; + command: string; + exitCode: number; + outputSnippet: string; + timestamp: number; +} + +export interface FileWriteEvidence { + kind: "write"; + toolCallId: string; + path: string; + timestamp: number; +} + +export interface FileEditEvidence { + kind: "edit"; + toolCallId: string; + path: string; + timestamp: number; +} + +export type EvidenceEntry = BashEvidence | FileWriteEvidence | FileEditEvidence; + +// ─── Module State ─────────────────────────────────────────────────────────── + +let unitEvidence: EvidenceEntry[] = []; + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** Reset all evidence for a new unit. Call at unit start. */ +export function resetEvidence(): void { + unitEvidence = []; +} + +/** Get a read-only view of all evidence collected for the current unit. */ +export function getEvidence(): readonly EvidenceEntry[] { + return unitEvidence; +} + +/** Get only bash evidence entries. */ +export function getBashEvidence(): readonly BashEvidence[] { + return unitEvidence.filter((e): e is BashEvidence => e.kind === "bash"); +} + +/** Get all file paths touched (write + edit). */ +export function getFilePaths(): string[] { + return unitEvidence + .filter((e): e is FileWriteEvidence | FileEditEvidence => e.kind === "write" || e.kind === "edit") + .map(e => e.path); +} + +// ─── Recording (called from register-hooks.ts) ───────────────────────────── + +/** + * Record a tool call at dispatch time (before execution). + * Exit codes and output are filled in by recordToolResult after execution. + */ +export function recordToolCall(toolName: string, input: Record): void { + if (toolName === "bash" || toolName === "Bash") { + unitEvidence.push({ + kind: "bash", + toolCallId: "", + command: String(input.command ?? ""), + exitCode: -1, + outputSnippet: "", + timestamp: Date.now(), + }); + } else if (toolName === "write" || toolName === "Write") { + unitEvidence.push({ + kind: "write", + toolCallId: "", + path: String(input.file_path ?? input.path ?? ""), + timestamp: Date.now(), + }); + } else if (toolName === "edit" || toolName === "Edit") { + unitEvidence.push({ + kind: "edit", + toolCallId: "", + path: String(input.file_path ?? input.path ?? ""), + timestamp: Date.now(), + }); + } +} + +/** + * Record a tool execution result. Matches the most recent unresolved entry + * of the same kind and fills in the toolCallId, exit code, and output. + */ +export function recordToolResult( + toolCallId: string, + toolName: string, + result: unknown, + isError: boolean, +): void { + const normalizedName = toolName.toLowerCase(); + + if (normalizedName === "bash") { + const entry = findLastUnresolved("bash") as BashEvidence | undefined; + if (entry) { + entry.toolCallId = toolCallId; + const text = extractResultText(result); + entry.outputSnippet = text.slice(0, 500); + const exitMatch = text.match(/Command exited with code (\d+)/); + entry.exitCode = exitMatch ? Number(exitMatch[1]) : (isError ? 1 : 0); + } + } else if (normalizedName === "write" || normalizedName === "edit") { + const entry = findLastUnresolved(normalizedName as "write" | "edit"); + if (entry) { + entry.toolCallId = toolCallId; + } + } +} + +// ─── Internals ────────────────────────────────────────────────────────────── + +function findLastUnresolved(kind: string): EvidenceEntry | undefined { + for (let i = unitEvidence.length - 1; i >= 0; i--) { + if (unitEvidence[i].kind === kind && unitEvidence[i].toolCallId === "") { + return unitEvidence[i]; + } + } + return undefined; +} + +function extractResultText(result: unknown): string { + if (typeof result === "string") return result; + if (result && typeof result === "object") { + const r = result as Record; + if (Array.isArray(r.content)) { + const textBlock = r.content.find( + (c: unknown) => typeof c === "object" && c !== null && (c as Record).type === "text", + ) as Record | undefined; + if (textBlock && typeof textBlock.text === "string") return textBlock.text; + } + if (typeof r.text === "string") return r.text; + } + return String(result ?? ""); +} diff --git a/src/resources/extensions/gsd/safety/evidence-cross-ref.ts b/src/resources/extensions/gsd/safety/evidence-cross-ref.ts new file mode 100644 index 000000000..2a57f6962 --- /dev/null +++ b/src/resources/extensions/gsd/safety/evidence-cross-ref.ts @@ -0,0 +1,120 @@ +/** + * Evidence cross-reference for auto-mode safety harness. + * Compares the LLM's claimed verification evidence (command + exitCode) + * against actual bash tool calls recorded by the evidence collector. + * + * Copyright (c) 2026 Jeremy McSpadden + */ + +import type { BashEvidence, EvidenceEntry } from "./evidence-collector.js"; + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface ClaimedEvidence { + command: string; + exitCode: number; + verdict: string; +} + +export interface EvidenceMismatch { + severity: "warning" | "error"; + claimed: ClaimedEvidence; + actual: BashEvidence | null; + reason: string; +} + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Cross-reference claimed verification evidence against actual bash tool calls. + * + * Returns an array of mismatches. Empty array = all claims verified. + * Skips entries that were coerced from strings (already flagged by db-tools.ts). + */ +export function crossReferenceEvidence( + claimedEvidence: readonly ClaimedEvidence[], + actualEvidence: readonly EvidenceEntry[], +): EvidenceMismatch[] { + const bashCalls = actualEvidence.filter( + (e): e is BashEvidence => e.kind === "bash", + ); + const mismatches: EvidenceMismatch[] = []; + + for (const claimed of claimedEvidence) { + // Skip coerced entries — they're already flagged with exitCode: -1 + // and verdict: "unknown (coerced from string)" by db-tools.ts + if (claimed.verdict?.includes("coerced from string")) continue; + if (claimed.exitCode === -1) continue; + + // Skip entries with empty or generic commands + if (!claimed.command || claimed.command.length < 3) continue; + + // Find matching bash call by command substring match + const match = findBestMatch(claimed.command, bashCalls); + + if (!match) { + mismatches.push({ + severity: "warning", + claimed, + actual: null, + reason: `No bash tool call found matching "${claimed.command.slice(0, 80)}"`, + }); + continue; + } + + // Exit code mismatch: LLM claims success but actual command failed + if (claimed.exitCode === 0 && match.exitCode !== 0) { + mismatches.push({ + severity: "error", + claimed, + actual: match, + reason: `Claimed exitCode=0 but actual exitCode=${match.exitCode}`, + }); + } + } + + return mismatches; +} + +// ─── Internals ────────────────────────────────────────────────────────────── + +/** + * Find the best matching bash evidence entry for a claimed command. + * Uses substring matching — the claimed command may be a shortened version + * of the actual command, or vice versa. + */ +function findBestMatch( + claimedCommand: string, + bashCalls: readonly BashEvidence[], +): BashEvidence | null { + const normalized = claimedCommand.trim(); + + // Exact match first + const exact = bashCalls.find(b => b.command.trim() === normalized); + if (exact) return exact; + + // Substring match: claimed is contained in actual or actual in claimed + const substring = bashCalls.find( + b => b.command.includes(normalized) || normalized.includes(b.command), + ); + if (substring) return substring; + + // Token match: split on whitespace and check significant overlap + const claimedTokens = normalized.split(/\s+/).filter(t => t.length > 2); + if (claimedTokens.length === 0) return null; + + let bestMatch: BashEvidence | null = null; + let bestScore = 0; + + for (const call of bashCalls) { + const callTokens = new Set(call.command.split(/\s+/)); + const matchCount = claimedTokens.filter(t => callTokens.has(t)).length; + const score = matchCount / claimedTokens.length; + if (score > bestScore && score >= 0.5) { + bestScore = score; + bestMatch = call; + } + } + + return bestMatch; +} diff --git a/src/resources/extensions/gsd/safety/file-change-validator.ts b/src/resources/extensions/gsd/safety/file-change-validator.ts new file mode 100644 index 000000000..acc0dc927 --- /dev/null +++ b/src/resources/extensions/gsd/safety/file-change-validator.ts @@ -0,0 +1,111 @@ +/** + * Post-unit file change validator for auto-mode safety harness. + * Compares actual git diff against the task plan's expected output files. + * + * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output) + * and tasks.files (from slice PLAN.md - Files: subline) as the expected set. + * Compares against git diff HEAD~1 --name-only after auto-commit. + * + * Copyright (c) 2026 Jeremy McSpadden + */ + +import { execFileSync } from "node:child_process"; +import { normalizePlannedFileReference } from "../files.js"; +import { logWarning } from "../workflow-logger.js"; + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface FileViolation { + severity: "info" | "warning"; + file: string; + reason: string; +} + +export interface FileChangeAudit { + expectedFiles: string[]; + actualFiles: string[]; + unexpectedFiles: string[]; + missingFiles: string[]; + violations: FileViolation[]; +} + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Validate file changes after auto-commit for an execute-task unit. + * Returns null if task data is unavailable or DB is not loaded. + * + * @param basePath - Working directory (worktree or project root) + * @param expectedOutput - JSON array from tasks.expected_output DB column + * @param plannedFiles - JSON array from tasks.files DB column + */ +export function validateFileChanges( + basePath: string, + expectedOutput: string[], + plannedFiles: string[], +): FileChangeAudit | null { + const allExpected = new Set([...expectedOutput, ...plannedFiles]); + + // If no expected files were planned, skip validation + if (allExpected.size === 0) return null; + + // Get actual changed files from last commit + const actualFiles = getChangedFilesFromLastCommit(basePath); + if (!actualFiles) return null; + + // Filter out .gsd/ internal files — only validate project source files + const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\")); + + // Normalize expected paths (strip leading ./ or /) + const normalizedExpected = new Set( + [...allExpected].map((f) => + normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, ""), + ), + ); + + // Compute symmetric difference + const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f)); + const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f)); + + const violations: FileViolation[] = []; + + for (const f of unexpectedFiles) { + violations.push({ + severity: "warning", + file: f, + reason: "Modified but not in task plan's expected output", + }); + } + + for (const f of missingFiles) { + violations.push({ + severity: "info", + file: f, + reason: "Listed in task plan but not modified", + }); + } + + return { + expectedFiles: [...normalizedExpected], + actualFiles: projectFiles, + unexpectedFiles, + missingFiles, + violations, + }; +} + +// ─── Internals ────────────────────────────────────────────────────────────── + +function getChangedFilesFromLastCommit(basePath: string): string[] | null { + try { + const result = execFileSync( + "git", + ["diff", "--name-only", "HEAD~1", "HEAD"], + { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }, + ).trim(); + return result ? result.split("\n").filter(Boolean) : []; + } catch (e) { + logWarning("safety", `git diff failed in file-change-validator: ${(e as Error).message}`); + return null; + } +} diff --git a/src/resources/extensions/gsd/safety/git-checkpoint.ts b/src/resources/extensions/gsd/safety/git-checkpoint.ts new file mode 100644 index 000000000..4f66b6dbb --- /dev/null +++ b/src/resources/extensions/gsd/safety/git-checkpoint.ts @@ -0,0 +1,106 @@ +/** + * Pre-unit git checkpoint and rollback for auto-mode safety harness. + * Uses the existing refs/gsd/ namespace (already pruned by doctor). + * + * Creates a lightweight ref at HEAD before unit execution. On failure, + * the ref can be used to rollback the branch to the pre-unit state. + * + * Copyright (c) 2026 Jeremy McSpadden + */ + +import { execFileSync } from "node:child_process"; +import { logWarning } from "../workflow-logger.js"; + +// ─── Constants ────────────────────────────────────────────────────────────── + +const CHECKPOINT_PREFIX = "refs/gsd/checkpoints/"; + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Create a checkpoint ref at the current HEAD for the given unit. + * Returns the SHA of HEAD, or null if the operation fails. + */ +export function createCheckpoint(basePath: string, unitId: string): string | null { + try { + const sha = execFileSync("git", ["rev-parse", "HEAD"], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); + + if (!sha || sha.length < 7) return null; + + // Sanitize unitId for use in ref path (replace / with -) + const safeUnitId = unitId.replace(/\//g, "-"); + + execFileSync("git", ["update-ref", `${CHECKPOINT_PREFIX}${safeUnitId}`, sha], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + }); + + return sha; + } catch (e) { + logWarning("safety", `checkpoint creation failed: ${(e as Error).message}`); + return null; + } +} + +/** + * Rollback the current branch to a checkpoint SHA. + * Returns true on success, false on failure. + * + * WARNING: This is a destructive operation — it discards all changes + * since the checkpoint. Only call when the user has opted in via + * safety_harness.auto_rollback or an explicit manual trigger. + */ +export function rollbackToCheckpoint( + basePath: string, + unitId: string, + sha: string, +): boolean { + try { + // Get current branch name + const branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); + + if (!branch || branch === "HEAD") { + logWarning("safety", "rollback: detached HEAD state, cannot rollback"); + return false; + } + + // Reset branch pointer and working tree to checkpoint SHA in one step. + // Using `git reset --hard ` works on the currently checked-out branch + // (unlike `git branch -f` which is rejected for checked-out branches). + execFileSync("git", ["reset", "--hard", sha], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + }); + + // Cleanup checkpoint ref + cleanupCheckpoint(basePath, unitId); + + return true; + } catch (e) { + logWarning("safety", `rollback failed: ${(e as Error).message}`); + return false; + } +} + +/** + * Remove a checkpoint ref after successful unit completion. + */ +export function cleanupCheckpoint(basePath: string, unitId: string): void { + try { + const safeUnitId = unitId.replace(/\//g, "-"); + execFileSync("git", ["update-ref", "-d", `${CHECKPOINT_PREFIX}${safeUnitId}`], { + cwd: basePath, + stdio: ["ignore", "pipe", "pipe"], + }); + } catch { + // Non-fatal — ref may already have been cleaned up + } +} diff --git a/src/resources/extensions/gsd/safety/safety-harness.ts b/src/resources/extensions/gsd/safety/safety-harness.ts new file mode 100644 index 000000000..f4e9e83d1 --- /dev/null +++ b/src/resources/extensions/gsd/safety/safety-harness.ts @@ -0,0 +1,105 @@ +/** + * Safety Harness — central module for LLM damage control during auto-mode. + * Provides types, preference resolution, and orchestration for all safety components. + * + * Components: + * - evidence-collector.ts: Real-time tool call tracking + * - destructive-guard.ts: Bash command classification + * - file-change-validator.ts: Post-unit git diff vs plan + * - evidence-cross-ref.ts: Claimed vs actual verification evidence + * - git-checkpoint.ts: Pre-unit checkpoints + rollback + * - content-validator.ts: Output quality validation + * + * Copyright (c) 2026 Jeremy McSpadden + */ + +// ─── Types ────────────────────────────────────────────────────────────────── + +export interface SafetyHarnessConfig { + enabled: boolean; + evidence_collection: boolean; + file_change_validation: boolean; + evidence_cross_reference: boolean; + destructive_command_warnings: boolean; + content_validation: boolean; + checkpoints: boolean; + auto_rollback: boolean; + timeout_scale_cap: number; +} + +// ─── Defaults ─────────────────────────────────────────────────────────────── + +const DEFAULTS: SafetyHarnessConfig = { + enabled: true, + evidence_collection: true, + file_change_validation: true, + evidence_cross_reference: true, + destructive_command_warnings: true, + content_validation: true, + checkpoints: true, + auto_rollback: false, + timeout_scale_cap: 6, +}; + +// ─── Public API ───────────────────────────────────────────────────────────── + +/** + * Resolve safety harness configuration from raw preferences. + * Missing fields fall back to defaults. + */ +export function resolveSafetyHarnessConfig( + raw: Record | undefined, +): SafetyHarnessConfig { + if (!raw) return { ...DEFAULTS }; + + return { + enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULTS.enabled, + evidence_collection: typeof raw.evidence_collection === "boolean" ? raw.evidence_collection : DEFAULTS.evidence_collection, + file_change_validation: typeof raw.file_change_validation === "boolean" ? raw.file_change_validation : DEFAULTS.file_change_validation, + evidence_cross_reference: typeof raw.evidence_cross_reference === "boolean" ? raw.evidence_cross_reference : DEFAULTS.evidence_cross_reference, + destructive_command_warnings: typeof raw.destructive_command_warnings === "boolean" ? raw.destructive_command_warnings : DEFAULTS.destructive_command_warnings, + content_validation: typeof raw.content_validation === "boolean" ? raw.content_validation : DEFAULTS.content_validation, + checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints, + auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback, + timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap, + }; +} + +/** + * Check if the safety harness is enabled. + * Used as a fast gate at hook registration and phase integration points. + */ +export function isHarnessEnabled( + raw: Record | undefined, +): boolean { + if (!raw) return DEFAULTS.enabled; + if (typeof raw.enabled === "boolean") return raw.enabled; + return DEFAULTS.enabled; +} + +// ─── Re-exports ───────────────────────────────────────────────────────────── + +export { + resetEvidence, + getEvidence, + getBashEvidence, + getFilePaths, + recordToolCall, + recordToolResult, +} from "./evidence-collector.js"; + +export type { EvidenceEntry, BashEvidence, FileWriteEvidence, FileEditEvidence } from "./evidence-collector.js"; + +export { classifyCommand } from "./destructive-guard.js"; +export type { CommandClassification } from "./destructive-guard.js"; + +export { validateFileChanges } from "./file-change-validator.js"; +export type { FileChangeAudit, FileViolation } from "./file-change-validator.js"; + +export { crossReferenceEvidence } from "./evidence-cross-ref.js"; +export type { ClaimedEvidence, EvidenceMismatch } from "./evidence-cross-ref.js"; + +export { createCheckpoint, rollbackToCheckpoint, cleanupCheckpoint } from "./git-checkpoint.js"; + +export { validateContent } from "./content-validator.js"; +export type { ContentViolation } from "./content-validator.js"; diff --git a/src/resources/extensions/gsd/session-lock.ts b/src/resources/extensions/gsd/session-lock.ts index 1d5a4e7a3..e3bbe7c49 100644 --- a/src/resources/extensions/gsd/session-lock.ts +++ b/src/resources/extensions/gsd/session-lock.ts @@ -288,6 +288,20 @@ export function acquireSessionLock(basePath: string): SessionLockResult { const gsdDir = gsdRoot(basePath); const lockTarget = effectiveLockTarget(gsdDir); + // #3218: Pre-flight stale lock cleanup — if the .lock/ directory exists but + // no auto.lock metadata is present (or the PID is dead), remove the lock + // directory before attempting acquisition. This prevents the 30-min stale + // window from blocking /gsd after crashes, SIGKILL, or laptop sleep. + const lockDir = lockTarget + ".lock"; + if (existsSync(lockDir)) { + const existingData = readExistingLockData(lp); + const isOrphan = !existingData || (existingData.pid && !isPidAlive(existingData.pid)); + if (isOrphan) { + try { rmSync(lockDir, { recursive: true, force: true }); } catch { /* best-effort */ } + try { if (existsSync(lp)) unlinkSync(lp); } catch { /* best-effort */ } + } + } + try { // Try to acquire an exclusive OS-level lock on the lock target. // We lock a directory since proper-lockfile works best on directories, @@ -344,9 +358,11 @@ export function acquireSessionLock(basePath: string): SessionLockResult { } } + // #3218: Provide actionable workaround when lock recovery fails + const lockDirPath = lockTarget + ".lock"; const reason = existingPid ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.` - : `Another auto-mode session is already running on this project.`; + : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`; return { acquired: false, reason, existingPid }; } diff --git a/src/resources/extensions/gsd/skill-catalog.ts b/src/resources/extensions/gsd/skill-catalog.ts index 8f1c5d760..7a061b067 100644 --- a/src/resources/extensions/gsd/skill-catalog.ts +++ b/src/resources/extensions/gsd/skill-catalog.ts @@ -935,13 +935,16 @@ export async function installPacksBatched( /** * Check if any skills from a pack are already installed. + * Searches both the skills.sh ecosystem directory and Claude Code's official directory. */ export function isPackInstalled(pack: SkillPack): boolean { - const skillsDir = join(homedir(), ".agents", "skills"); - if (!existsSync(skillsDir)) return false; + const skillsDirs = [ + join(homedir(), ".agents", "skills"), + join(homedir(), ".claude", "skills"), + ]; return pack.skills.every((name) => - existsSync(join(skillsDir, name, "SKILL.md")), + skillsDirs.some((dir) => existsSync(join(dir, name, "SKILL.md"))), ); } diff --git a/src/resources/extensions/gsd/skill-discovery.ts b/src/resources/extensions/gsd/skill-discovery.ts index e8c224ea4..459236635 100644 --- a/src/resources/extensions/gsd/skill-discovery.ts +++ b/src/resources/extensions/gsd/skill-discovery.ts @@ -12,8 +12,9 @@ import { existsSync, readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { homedir } from "node:os"; -/** Industry-standard skills.sh global skills directory */ +/** Skills directories — skills.sh ecosystem + Claude Code official */ const SKILLS_DIR = join(homedir(), ".agents", "skills"); +const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills"); export interface DiscoveredSkill { name: string; @@ -58,8 +59,9 @@ export function detectNewSkills(): DiscoveredSkill[] { for (const dir of current) { if (baselineSkills.has(dir)) continue; - const skillMdPath = join(SKILLS_DIR, dir, "SKILL.md"); - if (!existsSync(skillMdPath)) continue; + // Check both skill directories for the SKILL.md file + const skillMdPath = resolveSkillMdPath(dir); + if (!skillMdPath) continue; const meta = parseSkillFrontmatter(skillMdPath); if (meta) { @@ -97,10 +99,10 @@ ${entries} // ─── Internals ──────────────────────────────────────────────────────────────── -function listSkillDirs(): string[] { - if (!existsSync(SKILLS_DIR)) return []; +function listSkillDirsFrom(dir: string): string[] { + if (!existsSync(dir)) return []; try { - return readdirSync(SKILLS_DIR, { withFileTypes: true }) + return readdirSync(dir, { withFileTypes: true }) .filter(d => d.isDirectory()) .map(d => d.name); } catch { @@ -108,6 +110,13 @@ function listSkillDirs(): string[] { } } +function listSkillDirs(): string[] { + const names = new Set(); + for (const name of listSkillDirsFrom(SKILLS_DIR)) names.add(name); + for (const name of listSkillDirsFrom(CLAUDE_SKILLS_DIR)) names.add(name); + return [...names]; +} + function parseSkillFrontmatter(path: string): { name?: string; description?: string } | null { try { const content = readFileSync(path, "utf-8"); @@ -131,6 +140,14 @@ function parseSkillFrontmatter(path: string): { name?: string; description?: str } } +function resolveSkillMdPath(skillName: string): string | null { + for (const dir of [SKILLS_DIR, CLAUDE_SKILLS_DIR]) { + const candidate = join(dir, skillName, "SKILL.md"); + if (existsSync(candidate)) return candidate; + } + return null; +} + function escapeXml(text: string): string { return text .replace(/&/g, "&") diff --git a/src/resources/extensions/gsd/skill-health.ts b/src/resources/extensions/gsd/skill-health.ts index 75217a5b6..6caca9464 100644 --- a/src/resources/extensions/gsd/skill-health.ts +++ b/src/resources/extensions/gsd/skill-health.ts @@ -207,9 +207,13 @@ export function formatSkillDetail(basePath: string, skillName: string): string { lines.push(` ${date} ${u.id.padEnd(20)} ${formatTokenCount(u.tokens.total).padStart(8)} tokens ${formatCost(u.cost)}`); } - // Check for SKILL.md existence - const skillPath = join(homedir(), ".agents", "skills", skillName, "SKILL.md"); - if (existsSync(skillPath)) { + // Check for SKILL.md existence — search both ecosystem and Claude Code directories + const candidatePaths = [ + join(homedir(), ".agents", "skills", skillName, "SKILL.md"), + join(homedir(), ".claude", "skills", skillName, "SKILL.md"), + ]; + const skillPath = candidatePaths.find(p => existsSync(p)); + if (skillPath) { const stat = statSync(skillPath); lines.push(""); lines.push(`SKILL.md: ${skillPath}`); diff --git a/src/resources/extensions/gsd/skill-telemetry.ts b/src/resources/extensions/gsd/skill-telemetry.ts index f1bddfd21..e5ec9c82c 100644 --- a/src/resources/extensions/gsd/skill-telemetry.ts +++ b/src/resources/extensions/gsd/skill-telemetry.ts @@ -31,12 +31,14 @@ const activelyLoadedSkills = new Set(); */ export function captureAvailableSkills(): void { const skillsDir = join(homedir(), ".agents", "skills"); + const claudeSkillsDir = join(homedir(), ".claude", "skills"); const legacyDir = join(homedir(), ".gsd", "agent", "skills"); const names = listSkillNames(skillsDir); + const claudeNames = listSkillNames(claudeSkillsDir); // Include skills still in the legacy directory only if migration hasn't completed const legacyMigrated = existsSync(join(legacyDir, ".migrated-to-agents")); const legacyNames = legacyMigrated ? [] : listSkillNames(legacyDir); - const all = new Set([...names, ...legacyNames]); + const all = new Set([...names, ...claudeNames, ...legacyNames]); availableSkills = [...all]; activelyLoadedSkills.clear(); } @@ -106,10 +108,11 @@ export function detectStaleSkills( // Check all installed skills, not just those with usage data const skillsDir = join(homedir(), ".agents", "skills"); + const claudeSkillsDir = join(homedir(), ".claude", "skills"); const legacyDir = join(homedir(), ".gsd", "agent", "skills"); const legacyMigrated = existsSync(join(legacyDir, ".migrated-to-agents")); const legacyNames = legacyMigrated ? [] : listSkillNames(legacyDir); - const installedSet = new Set([...listSkillNames(skillsDir), ...legacyNames]); + const installedSet = new Set([...listSkillNames(skillsDir), ...listSkillNames(claudeSkillsDir), ...legacyNames]); const installed = [...installedSet]; for (const skill of installed) { diff --git a/src/resources/extensions/gsd/slice-parallel-conflict.ts b/src/resources/extensions/gsd/slice-parallel-conflict.ts new file mode 100644 index 000000000..dd540a627 --- /dev/null +++ b/src/resources/extensions/gsd/slice-parallel-conflict.ts @@ -0,0 +1,86 @@ +/** + * GSD Slice Parallel Conflict Detection — File overlap analysis between slices. + * + * Reads PLAN.md for each slice and extracts file paths mentioned in task + * descriptions. If two slices share more than 5 file paths, they are considered + * conflicting and should not run in parallel. + * + * Conservative by default: missing PLAN = block parallel execution. + */ + +import { existsSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +// ─── File Path Extraction ───────────────────────────────────────────────────── + +/** + * Extract file paths from a PLAN.md content string. + * Matches common patterns like `src/...`, `lib/...`, paths with extensions. + */ +function extractFilePaths(content: string): Set { + const paths = new Set(); + + // Match file-like patterns: word/word paths with extensions, or src/lib/etc prefixed paths + const patterns = [ + // Paths like src/foo/bar.ts, lib/utils.js, etc. + /(?:src|lib|test|tests|app|pkg|cmd|internal|components|pages|api|utils|config|scripts|dist|build)\/[\w./-]+\.\w+/g, + // Generic path with at least one slash and extension + /(?5 shared files or missing plan). + */ +export function hasFileConflict( + basePath: string, + mid: string, + sliceA: string, + sliceB: string, +): boolean { + const planPathA = join(basePath, ".gsd", "milestones", mid, sliceA, "PLAN.md"); + const planPathB = join(basePath, ".gsd", "milestones", mid, sliceB, "PLAN.md"); + + // Conservative: missing PLAN = block + if (!existsSync(planPathA) || !existsSync(planPathB)) { + return true; + } + + const contentA = readFileSync(planPathA, "utf-8"); + const contentB = readFileSync(planPathB, "utf-8"); + + const filesA = extractFilePaths(contentA); + const filesB = extractFilePaths(contentB); + + // If either has no files extracted, no conflict detectable → allow + if (filesA.size === 0 || filesB.size === 0) { + return false; + } + + // Count shared files + let sharedCount = 0; + for (const file of filesA) { + if (filesB.has(file)) { + sharedCount++; + } + } + + return sharedCount > 5; +} diff --git a/src/resources/extensions/gsd/slice-parallel-eligibility.ts b/src/resources/extensions/gsd/slice-parallel-eligibility.ts new file mode 100644 index 000000000..f00fa0f43 --- /dev/null +++ b/src/resources/extensions/gsd/slice-parallel-eligibility.ts @@ -0,0 +1,73 @@ +/** + * GSD Slice Parallel Eligibility — Pure function to determine which slices + * within a milestone can run in parallel based on dependency satisfaction. + * + * This is the slice-level equivalent of parallel-eligibility.ts (which operates + * at milestone scope). The key difference is the positional fallback: slices + * without explicit dependencies use sequential ordering as an implicit constraint. + */ + +// ─── Types ──────────────────────────────────────────────────────────────────── + +export interface SliceInput { + id: string; + done: boolean; + depends: string[]; +} + +export interface EligibleSlice { + id: string; +} + +// ─── Core Logic ─────────────────────────────────────────────────────────────── + +/** + * Determine which slices are eligible for parallel execution. + * + * Rules: + * 1. Done slices are never eligible (nothing to do). + * 2. A slice with explicit `depends` entries is eligible when ALL deps + * appear in `completedSliceIds`. + * 3. A slice with NO `depends` entries uses positional fallback: it is + * eligible only when every positionally-earlier slice is done. + * This preserves backward compatibility with roadmaps that don't + * declare inter-slice dependencies. + * + * @param slices All slices in the milestone (ordered by position). + * @param completedSliceIds Set of slice IDs that are already complete. + * @returns Array of eligible slice descriptors. + */ +export function getEligibleSlices( + slices: SliceInput[], + completedSliceIds: Set, +): EligibleSlice[] { + const eligible: EligibleSlice[] = []; + + for (let i = 0; i < slices.length; i++) { + const slice = slices[i]; + + // Rule 1: skip done slices + if (slice.done) continue; + + const hasExplicitDeps = slice.depends.length > 0; + + if (hasExplicitDeps) { + // Rule 2: explicit dependencies — all must be satisfied + const allDepsSatisfied = slice.depends.every(dep => completedSliceIds.has(dep)); + if (allDepsSatisfied) { + eligible.push({ id: slice.id }); + } + } else { + // Rule 3: no deps declared — positional fallback + // Eligible only if all positionally-earlier slices are done + const allEarlierDone = slices.slice(0, i).every( + earlier => earlier.done || completedSliceIds.has(earlier.id), + ); + if (allEarlierDone) { + eligible.push({ id: slice.id }); + } + } + } + + return eligible; +} diff --git a/src/resources/extensions/gsd/slice-parallel-orchestrator.ts b/src/resources/extensions/gsd/slice-parallel-orchestrator.ts new file mode 100644 index 000000000..346237651 --- /dev/null +++ b/src/resources/extensions/gsd/slice-parallel-orchestrator.ts @@ -0,0 +1,477 @@ +/** + * GSD Slice Parallel Orchestrator — Engine for parallel slice execution + * within a single milestone. + * + * Mirrors the existing parallel-orchestrator.ts pattern at slice scope + * instead of milestone scope. Workers are separate processes spawned via + * child_process, each running in its own git worktree with GSD_SLICE_LOCK + * + GSD_MILESTONE_LOCK env vars set. + * + * Key differences from milestone-level parallelism: + * - Scope: slices within one milestone, not milestones within a project + * - Lock env: GSD_SLICE_LOCK (in addition to GSD_MILESTONE_LOCK) + * - Conflict check: file overlap between slice plans (slice-parallel-conflict.ts) + */ + +import { spawn, type ChildProcess } from "node:child_process"; +import { + appendFileSync, + existsSync, + writeFileSync, + readFileSync, + mkdirSync, +} from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; +import { gsdRoot } from "./paths.js"; +import { createWorktree, worktreePath, removeWorktree } from "./worktree-manager.js"; +import { autoWorktreeBranch, runWorktreePostCreateHook } from "./auto-worktree.js"; +import { + writeSessionStatus, + removeSessionStatus, +} from "./session-status-io.js"; +import { hasFileConflict } from "./slice-parallel-conflict.js"; +import { getErrorMessage } from "./error-utils.js"; + +// ─── Types ───────────────────────────────────────────────────────────────── + +export interface SliceWorkerInfo { + milestoneId: string; + sliceId: string; + pid: number; + process: ChildProcess | null; + worktreePath: string; + startedAt: number; + state: "running" | "stopped" | "error"; + completedUnits: number; + cost: number; + cleanup?: () => void; +} + +export interface SliceOrchestratorState { + active: boolean; + workers: Map; + totalCost: number; + budgetCeiling?: number; + maxWorkers: number; + startedAt: number; + basePath: string; +} + +export interface StartSliceParallelOpts { + maxWorkers?: number; + budgetCeiling?: number; +} + +// ─── Module State ────────────────────────────────────────────────────────── + +let sliceState: SliceOrchestratorState | null = null; + +// ─── Public API ──────────────────────────────────────────────────────────── + +/** + * Check whether slice-level parallel is currently active. + */ +export function isSliceParallelActive(): boolean { + return sliceState?.active === true; +} + +/** + * Get current slice orchestrator state (read-only snapshot). + */ +export function getSliceOrchestratorState(): SliceOrchestratorState | null { + return sliceState; +} + +/** + * Start parallel execution for eligible slices within a milestone. + * + * For each eligible slice: create a worktree, spawn `gsd --mode json --print "/gsd auto"` + * with env GSD_SLICE_LOCK= + GSD_MILESTONE_LOCK= + GSD_PARALLEL_WORKER=1. + */ +export async function startSliceParallel( + basePath: string, + milestoneId: string, + eligibleSlices: Array<{ id: string }>, + opts: StartSliceParallelOpts = {}, +): Promise<{ started: string[]; errors: Array<{ sid: string; error: string }> }> { + // Prevent nesting: if already a parallel worker, refuse + if (process.env.GSD_PARALLEL_WORKER) { + return { started: [], errors: [{ sid: "all", error: "Cannot start slice-parallel from within a parallel worker" }] }; + } + + const maxWorkers = opts.maxWorkers ?? 2; + const budgetCeiling = opts.budgetCeiling; + + // Initialize orchestrator state + sliceState = { + active: true, + workers: new Map(), + totalCost: 0, + budgetCeiling, + maxWorkers, + startedAt: Date.now(), + basePath, + }; + + const started: string[] = []; + const errors: Array<{ sid: string; error: string }> = []; + + // Filter out conflicting slices (conservative: check all pairs) + const safeSlices = filterConflictingSlices(basePath, milestoneId, eligibleSlices); + + // Limit to maxWorkers + const toSpawn = safeSlices.slice(0, maxWorkers); + + for (const slice of toSpawn) { + try { + // Create worktree for this slice + const wtBranch = `slice/${milestoneId}/${slice.id}`; + const wtName = `${milestoneId}-${slice.id}`; + const wtPath = worktreePath(basePath, wtName); + + if (!existsSync(wtPath)) { + createWorktree(basePath, wtName, { branch: wtBranch }); + } + + // Create worker info + const worker: SliceWorkerInfo = { + milestoneId, + sliceId: slice.id, + pid: 0, + process: null, + worktreePath: wtPath, + startedAt: Date.now(), + state: "running", + completedUnits: 0, + cost: 0, + }; + + sliceState.workers.set(slice.id, worker); + + // Spawn worker + const spawned = spawnSliceWorker(basePath, milestoneId, slice.id); + if (spawned) { + started.push(slice.id); + } else { + errors.push({ sid: slice.id, error: "Failed to spawn worker process" }); + worker.state = "error"; + } + } catch (err) { + errors.push({ sid: slice.id, error: getErrorMessage(err) }); + // Best-effort cleanup of partially created worktree + const wtName = `${milestoneId}-${slice.id}`; + try { + removeWorktree(basePath, wtName, { deleteBranch: true, force: true }); + } catch { /* ignore cleanup failures */ } + } + } + + // If nothing started, deactivate + if (started.length === 0) { + sliceState.active = false; + } + + return { started, errors }; +} + +/** + * Stop all slice-parallel workers and deactivate. + */ +export function stopSliceParallel(): void { + if (!sliceState) return; + + for (const worker of sliceState.workers.values()) { + if (worker.process) { + try { + worker.process.kill("SIGTERM"); + } catch { /* already dead */ } + } + worker.cleanup?.(); + worker.cleanup = undefined; + worker.process = null; + worker.state = "stopped"; + + // Clean up worktree created for this worker + const wtName = `${worker.milestoneId}-${worker.sliceId}`; + try { + removeWorktree(sliceState.basePath, wtName, { deleteBranch: true, force: true }); + } catch { /* best-effort cleanup */ } + } + + sliceState.active = false; +} + +/** + * Get aggregate cost across all slice workers. + */ +export function getSliceAggregateCost(): number { + if (!sliceState) return 0; + let total = 0; + for (const w of sliceState.workers.values()) { + total += w.cost; + } + return total; +} + +/** + * Check if budget ceiling has been exceeded. + */ +export function isSliceBudgetExceeded(): boolean { + if (!sliceState?.budgetCeiling) return false; + return getSliceAggregateCost() >= sliceState.budgetCeiling; +} + +/** + * Reset module state (for testing). + */ +export function resetSliceOrchestrator(): void { + if (sliceState) { + for (const w of sliceState.workers.values()) { + w.cleanup?.(); + } + } + sliceState = null; +} + +// ─── Internal: Conflict Filtering ────────────────────────────────────────── + +/** + * Remove slices that have file conflicts with each other. + * Greedy: add slices to the safe set in order; skip any that conflict + * with an already-included slice. + */ +function filterConflictingSlices( + basePath: string, + milestoneId: string, + slices: Array<{ id: string }>, +): Array<{ id: string }> { + const safe: Array<{ id: string }> = []; + + for (const candidate of slices) { + let conflictsWithSafe = false; + for (const existing of safe) { + if (hasFileConflict(basePath, milestoneId, candidate.id, existing.id)) { + conflictsWithSafe = true; + break; + } + } + if (!conflictsWithSafe) { + safe.push(candidate); + } + } + + return safe; +} + +// ─── Internal: Worker Spawning ───────────────────────────────────────────── + +/** + * Resolve the GSD CLI binary path. + * Same logic as parallel-orchestrator.ts resolveGsdBin(). + */ +function resolveGsdBin(): string | null { + if (process.env.GSD_BIN_PATH && existsSync(process.env.GSD_BIN_PATH)) { + return process.env.GSD_BIN_PATH; + } + + let thisDir: string; + try { + thisDir = dirname(fileURLToPath(import.meta.url)); + } catch { + thisDir = process.cwd(); + } + const candidates = [ + join(thisDir, "..", "..", "..", "loader.js"), + join(thisDir, "..", "..", "..", "..", "dist", "loader.js"), + ]; + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + return null; +} + +/** + * Spawn a worker process for a slice. + * The worker runs `gsd --mode json --print "/gsd auto"` in the slice's worktree + * with GSD_SLICE_LOCK, GSD_MILESTONE_LOCK, and GSD_PARALLEL_WORKER set. + */ +function spawnSliceWorker( + basePath: string, + milestoneId: string, + sliceId: string, +): boolean { + if (!sliceState) return false; + const worker = sliceState.workers.get(sliceId); + if (!worker) return false; + if (worker.process) return true; + + const binPath = resolveGsdBin(); + if (!binPath) return false; + + let child: ChildProcess; + try { + child = spawn(process.execPath, [binPath, "--mode", "json", "--print", "/gsd auto"], { + cwd: worker.worktreePath, + env: { + ...process.env, + GSD_SLICE_LOCK: sliceId, + GSD_MILESTONE_LOCK: milestoneId, + GSD_PROJECT_ROOT: basePath, + GSD_PARALLEL_WORKER: "1", + }, + stdio: ["ignore", "pipe", "pipe"], + detached: false, + }); + } catch { + return false; + } + + child.on("error", () => { + if (!sliceState) return; + const w = sliceState.workers.get(sliceId); + if (w) { + w.process = null; + } + }); + + worker.process = child; + worker.pid = child.pid ?? 0; + + if (!child.pid) { + worker.process = null; + return false; + } + + // ── NDJSON stdout monitoring ──────────────────────────────────────── + if (child.stdout) { + let stdoutBuffer = ""; + child.stdout.on("data", (data: Buffer) => { + stdoutBuffer += data.toString(); + const lines = stdoutBuffer.split("\n"); + stdoutBuffer = lines.pop() || ""; + for (const line of lines) { + processSliceWorkerLine(basePath, milestoneId, sliceId, line); + } + }); + child.stdout.on("close", () => { + if (stdoutBuffer.trim()) { + processSliceWorkerLine(basePath, milestoneId, sliceId, stdoutBuffer); + } + }); + } + + if (child.stderr) { + child.stderr.on("data", (data: Buffer) => { + appendSliceWorkerLog(basePath, milestoneId, sliceId, data.toString()); + }); + } + + // Update session status + writeSessionStatus(basePath, { + milestoneId: `${milestoneId}/${sliceId}`, + pid: worker.pid, + state: "running", + currentUnit: null, + completedUnits: worker.completedUnits, + cost: worker.cost, + lastHeartbeat: Date.now(), + startedAt: worker.startedAt, + worktreePath: worker.worktreePath, + }); + + // Store cleanup function + worker.cleanup = () => { + child.stdout?.removeAllListeners(); + child.stderr?.removeAllListeners(); + child.removeAllListeners(); + }; + + // Handle worker exit + child.on("exit", (code) => { + if (!sliceState) return; + const w = sliceState.workers.get(sliceId); + if (!w) return; + + w.cleanup?.(); + w.cleanup = undefined; + w.process = null; + + if (w.state === "stopped") return; + + if (code === 0) { + w.state = "stopped"; + } else { + w.state = "error"; + appendSliceWorkerLog(basePath, milestoneId, sliceId, + `\n[slice-orchestrator] worker exited with code ${code ?? "null"}\n`); + } + + writeSessionStatus(basePath, { + milestoneId: `${milestoneId}/${sliceId}`, + pid: w.pid, + state: w.state, + currentUnit: null, + completedUnits: w.completedUnits, + cost: w.cost, + lastHeartbeat: Date.now(), + startedAt: w.startedAt, + worktreePath: w.worktreePath, + }); + }); + + return true; +} + +// ─── NDJSON Processing ────────────────────────────────────────────────────── + +/** + * Process a single NDJSON line from a slice worker's stdout. + * Extracts cost from message_end events. + */ +function processSliceWorkerLine( + _basePath: string, + _milestoneId: string, + sliceId: string, + line: string, +): void { + if (!line.trim() || !sliceState) return; + + let event: Record; + try { + event = JSON.parse(line); + } catch { + return; + } + + const type = String(event.type ?? ""); + if (type === "message_end") { + const worker = sliceState.workers.get(sliceId); + if (worker) { + const usage = event.usage as Record | undefined; + if (usage?.cost && typeof usage.cost === "number") { + worker.cost += usage.cost; + sliceState.totalCost += usage.cost; + } + worker.completedUnits++; + } + } +} + +// ─── Logging ──────────────────────────────────────────────────────────────── + +function sliceLogDir(basePath: string): string { + return join(gsdRoot(basePath), "parallel", "slice-logs"); +} + +function appendSliceWorkerLog( + basePath: string, + milestoneId: string, + sliceId: string, + text: string, +): void { + const dir = sliceLogDir(basePath); + mkdirSync(dir, { recursive: true }); + appendFileSync(join(dir, `${milestoneId}-${sliceId}.log`), text); +} diff --git a/src/resources/extensions/gsd/state.ts b/src/resources/extensions/gsd/state.ts index e6ff91895..1275feca3 100644 --- a/src/resources/extensions/gsd/state.ts +++ b/src/resources/extensions/gsd/state.ts @@ -36,22 +36,27 @@ import { import { findMilestoneIds } from './milestone-ids.js'; import { loadQueueOrder, sortByQueueOrder } from './queue-order.js'; -import { isClosedStatus } from './status-guards.js'; +import { isClosedStatus, isDeferredStatus } from './status-guards.js'; import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js'; import { join, resolve } from 'path'; -import { existsSync, readdirSync } from 'node:fs'; +import { existsSync, readdirSync, readFileSync } from 'node:fs'; import { debugCount, debugTime } from './debug-logger.js'; +import { logWarning, logError } from './workflow-logger.js'; import { extractVerdict } from './verdict-parser.js'; import { isDbAvailable, + wasDbOpenAttempted, getAllMilestones, + getMilestone, getMilestoneSlices, getSliceTasks, getReplanHistory, getSlice, insertMilestone, + insertSlice, + insertTask, updateTaskStatus, getPendingSliceGateCount, type MilestoneRow, @@ -64,8 +69,39 @@ import { * files like CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY). These appear when * a milestone is created but never initialised. Treating them as active causes * auto-mode to stall or falsely declare completion. + * + * However, a milestone is NOT a ghost if: + * - It has a DB row with a meaningful status (queued, active, etc.) — the DB + * knows about it even if content files haven't been created yet. + * - It has a worktree directory — a worktree proves the milestone was + * legitimately created and is expected to be populated. + * + * Fixes #2921: queued milestones with worktrees were incorrectly classified + * as ghosts, causing auto-mode to skip them entirely. */ export function isGhostMilestone(basePath: string, mid: string): boolean { + // If the milestone has a DB row, it's usually a known milestone — not a ghost. + // Exception: a "queued" row with no disk artifacts is a phantom from + // gsd_milestone_generate_id that was never planned (#3645). + if (isDbAvailable()) { + const dbRow = getMilestone(mid); + if (dbRow) { + if (dbRow.status === 'queued') { + const hasContent = resolveMilestoneFile(basePath, mid, "CONTEXT") + || resolveMilestoneFile(basePath, mid, "ROADMAP") + || resolveMilestoneFile(basePath, mid, "SUMMARY"); + return !hasContent; + } + return false; + } + } + + // If a worktree exists for this milestone, it was legitimately created. + const root = gsdRoot(basePath); + const wtPath = join(root, 'worktrees', mid); + if (existsSync(wtPath)) return false; + + // Fall back to content-file check: no substantive files means ghost. const context = resolveMilestoneFile(basePath, mid, "CONTEXT"); const draft = resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"); const roadmap = resolveMilestoneFile(basePath, mid, "ROADMAP"); @@ -154,7 +190,7 @@ export async function getActiveMilestoneId(basePath: string): Promise [m.id, m])); for (const id of sortedIds) { const m = byId.get(id)!; - if (m.status === "complete" || m.status === "done" || m.status === "parked") continue; + if (isClosedStatus(m.status) || m.status === "parked") continue; return m.id; } return null; @@ -209,10 +245,10 @@ export async function deriveState(basePath: string): Promise { if (isDbAvailable()) { let dbMilestones = getAllMilestones(); - // Disk→DB reconciliation (#2631): when the milestones table is empty - // (e.g. failed initial migration per #2529), the reconciliation code - // inside deriveStateFromDb is unreachable. Populate from disk here so - // the DB path activates correctly. + // Disk→DB reconciliation when DB is empty but disk has milestones (#2631). + // deriveStateFromDb() does its own reconciliation, but deriveState() skips + // it entirely when the DB is empty. Sync here so the DB path is used when + // disk milestones exist but haven't been migrated yet. if (dbMilestones.length === 0) { const diskIds = findMilestoneIds(basePath); let synced = false; @@ -231,11 +267,17 @@ export async function deriveState(basePath: string): Promise { stopDbTimer({ phase: result.phase, milestone: result.activeMilestone?.id }); _telemetry.dbDeriveCount++; } else { - // DB open but empty hierarchy tables — pre-migration project, use filesystem + // DB open but no milestones on disk either — use filesystem path result = await _deriveStateImpl(basePath); _telemetry.markdownDeriveCount++; } } else { + // Only warn when DB initialization was attempted and failed — not when + // the DB simply hasn't been opened yet (e.g. during before_agent_start + // context injection which runs before any tool invocation opens the DB). + if (wasDbOpenAttempted()) { + logWarning("state", "DB unavailable — using filesystem state derivation (degraded mode)"); + } result = await _deriveStateImpl(basePath); _telemetry.markdownDeriveCount++; } @@ -268,6 +310,10 @@ function extractContextTitle(content: string | null, fallback: string): string { // ─── DB-backed State Derivation ──────────────────────────────────────────── +// isStatusDone replaced by isClosedStatus from status-guards.ts (single source of truth). +// Alias kept for backward compatibility within this file. +const isStatusDone = isClosedStatus; + /** * Derive GSD state from the milestones/slices/tasks DB tables. * Flag files (PARKED, VALIDATION, CONTINUE, REPLAN, REPLAN-TRIGGER, CONTEXT-DRAFT) @@ -276,17 +322,8 @@ function extractContextTitle(content: string | null, fallback: string): string { * * Must produce field-identical GSDState to _deriveStateImpl() for the same project. */ -export async function deriveStateFromDb(basePath: string): Promise { - const requirements = parseRequirementCounts(await loadFile(resolveGsdRootFile(basePath, "REQUIREMENTS"))); - +function reconcileDiskToDb(basePath: string): MilestoneRow[] { let allMilestones = getAllMilestones(); - - // Incremental disk→DB sync: milestone directories created outside the DB - // write path (via /gsd queue, manual mkdir, or complete-milestone writing the - // next CONTEXT.md) are never inserted by the initial migration guard in - // auto-start.ts because that guard only runs when gsd.db doesn't exist yet. - // Reconcile here so deriveStateFromDb never silently misses queued milestones. - // insertMilestone uses INSERT OR IGNORE, so this is safe to call every time. const dbIdSet = new Set(allMilestones.map(m => m.id)); const diskIds = findMilestoneIds(basePath); let synced = false; @@ -298,92 +335,68 @@ export async function deriveStateFromDb(basePath: string): Promise { } if (synced) allMilestones = getAllMilestones(); - // Reconcile: discover milestones that exist on disk but are missing from - // the DB. This happens when milestones were created before the DB migration - // or were manually added to the filesystem. Without this, disk-only - // milestones are invisible after migration (#2416). - const dbMilestoneIds = new Set(allMilestones.map(m => m.id)); - const diskMilestoneIds = findMilestoneIds(basePath); - for (const diskId of diskMilestoneIds) { - if (!dbMilestoneIds.has(diskId)) { - // Synthesize a minimal MilestoneRow for the disk-only milestone. - // Title and status will be resolved from disk files in the loop below. - allMilestones.push({ - id: diskId, - title: diskId, - status: 'active', - depends_on: [] as string[], - created_at: new Date().toISOString(), - } as MilestoneRow); + for (const mid of diskIds) { + if (isGhostMilestone(basePath, mid)) continue; + const roadmapPath = resolveMilestoneFile(basePath, mid, "ROADMAP"); + if (!roadmapPath) continue; + + const dbSlices = getMilestoneSlices(mid); + const dbSliceIds = new Set(dbSlices.map(s => s.id)); + + let roadmapContent: string; + try { roadmapContent = readFileSync(roadmapPath, "utf-8"); } + catch { continue; } + + const parsed = parseRoadmap(roadmapContent); + for (const s of parsed.slices) { + if (dbSliceIds.has(s.id)) continue; + const summaryPath = resolveSliceFile(basePath, mid, s.id, "SUMMARY"); + const sliceStatus = (s.done || summaryPath) ? "complete" : "pending"; + insertSlice({ + id: s.id, milestoneId: mid, title: s.title, + status: sliceStatus, risk: s.risk, + depends: s.depends, demo: s.demo, + }); } } - // Re-sort so milestones follow queue order (same as dispatch guard) (#2556) - const customOrder = loadQueueOrder(basePath); - const sortedIds = sortByQueueOrder(allMilestones.map(m => m.id), customOrder); - const byId = new Map(allMilestones.map(m => [m.id, m])); - allMilestones.length = 0; - for (const id of sortedIds) allMilestones.push(byId.get(id)!); + return allMilestones; +} - // Parallel worker isolation: when locked, filter to just the locked milestone - const milestoneLock = process.env.GSD_MILESTONE_LOCK; - const milestones = milestoneLock - ? allMilestones.filter(m => m.id === milestoneLock) - : allMilestones; - - if (milestones.length === 0) { - return { - activeMilestone: null, - activeSlice: null, - activeTask: null, - phase: 'pre-planning', - recentDecisions: [], - blockers: [], - nextAction: 'No milestones found. Run /gsd to create one.', - registry: [], - requirements, - progress: { milestones: { done: 0, total: 0 } }, - }; - } - - // Phase 1: Build completeness set (which milestones count as "done" for dep resolution) +function buildCompletenessSet(basePath: string, milestones: MilestoneRow[]) { const completeMilestoneIds = new Set(); const parkedMilestoneIds = new Set(); for (const m of milestones) { - // Check disk for PARKED flag (not stored in DB status reliably — disk is truth for flag files) const parkedFile = resolveMilestoneFile(basePath, m.id, "PARKED"); if (parkedFile || m.status === 'parked') { parkedMilestoneIds.add(m.id); continue; } - - if (isClosedStatus(m.status)) { + if (isStatusDone(m.status)) { completeMilestoneIds.add(m.id); continue; } - - // Check if milestone has a summary on disk (terminal artifact per #864) const summaryFile = resolveMilestoneFile(basePath, m.id, "SUMMARY"); if (summaryFile) { completeMilestoneIds.add(m.id); continue; } - - // Check roadmap: all slices done means milestone is complete - const slices = getMilestoneSlices(m.id); - if (slices.length > 0 && slices.every(s => isClosedStatus(s.status))) { - // All slices done but no summary — still counts as complete for dep resolution - // if a summary file exists - // Note: without summary file, the milestone is in validating/completing state, not complete - } } + return { completeMilestoneIds, parkedMilestoneIds }; +} - // Phase 2: Build registry and find active milestone +async function buildRegistryAndFindActive( + basePath: string, + milestones: MilestoneRow[], + completeMilestoneIds: Set, + parkedMilestoneIds: Set +) { const registry: MilestoneRegistryEntry[] = []; let activeMilestone: ActiveRef | null = null; let activeMilestoneSlices: SliceRow[] = []; let activeMilestoneFound = false; let activeMilestoneHasDraft = false; + let firstDeferredQueuedShell: { id: string; title: string; deps: string[] } | null = null; for (const m of milestones) { if (parkedMilestoneIds.has(m.id)) { @@ -391,18 +404,14 @@ export async function deriveStateFromDb(basePath: string): Promise { continue; } - // Ghost milestone check: no slices in DB AND no substantive files on disk const slices = getMilestoneSlices(m.id); - if (slices.length === 0 && !isClosedStatus(m.status)) { - // Check disk for ghost detection + if (slices.length === 0 && !isStatusDone(m.status) && m.status !== 'queued') { if (isGhostMilestone(basePath, m.id)) continue; } const summaryFile = resolveMilestoneFile(basePath, m.id, "SUMMARY"); - // Determine if this milestone is complete if (completeMilestoneIds.has(m.id) || (summaryFile !== null)) { - // Get title from DB or summary let title = stripMilestonePrefix(m.title) || m.id; if (summaryFile && !m.title) { const summaryContent = await loadFile(summaryFile); @@ -411,14 +420,12 @@ export async function deriveStateFromDb(basePath: string): Promise { } } registry.push({ id: m.id, title, status: 'complete' }); - completeMilestoneIds.add(m.id); // ensure it's in the set + completeMilestoneIds.add(m.id); continue; } - // Not complete — determine if it should be active - const allSlicesDone = slices.length > 0 && slices.every(s => isClosedStatus(s.status)); + const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status)); - // Get title — prefer DB, fall back to context file extraction let title = stripMilestonePrefix(m.title) || m.id; if (title === m.id) { const contextFile = resolveMilestoneFile(basePath, m.id, "CONTEXT"); @@ -429,7 +436,6 @@ export async function deriveStateFromDb(basePath: string): Promise { } if (!activeMilestoneFound) { - // Check milestone-level dependencies const deps = m.depends_on; const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep)); @@ -438,14 +444,24 @@ export async function deriveStateFromDb(basePath: string): Promise { continue; } - // Handle all-slices-done case (validating/completing) + if (m.status === 'queued' && slices.length === 0) { + const contextFile = resolveMilestoneFile(basePath, m.id, "CONTEXT"); + const draftFile = resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT"); + if (!contextFile && !draftFile) { + if (!firstDeferredQueuedShell) { + firstDeferredQueuedShell = { id: m.id, title, deps }; + } + registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) }); + continue; + } + } + if (allSlicesDone) { const validationFile = resolveMilestoneFile(basePath, m.id, "VALIDATION"); const validationContent = validationFile ? await loadFile(validationFile) : null; const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false; if (!validationTerminal || (validationTerminal && !summaryFile)) { - // Validating or completing — still active activeMilestone = { id: m.id, title }; activeMilestoneSlices = slices; activeMilestoneFound = true; @@ -454,7 +470,6 @@ export async function deriveStateFromDb(basePath: string): Promise { } } - // Check for context draft (needs-discussion phase) const contextFile = resolveMilestoneFile(basePath, m.id, "CONTEXT"); const draftFile = resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT"); if (!contextFile && draftFile) activeMilestoneHasDraft = true; @@ -464,79 +479,278 @@ export async function deriveStateFromDb(basePath: string): Promise { activeMilestoneFound = true; registry.push({ id: m.id, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) }); } else { - // After active milestone found — rest are pending const deps = m.depends_on; registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) }); } } - const milestoneProgress = { - done: registry.filter(e => e.status === 'complete').length, - total: registry.length, - }; + if (!activeMilestoneFound && firstDeferredQueuedShell) { + const shell = firstDeferredQueuedShell; + activeMilestone = { id: shell.id, title: shell.title }; + activeMilestoneSlices = []; + activeMilestoneFound = true; + const entry = registry.find(e => e.id === shell.id); + if (entry) entry.status = 'active'; + } - // ── No active milestone ────────────────────────────────────────────── - if (!activeMilestone) { - const pendingEntries = registry.filter(e => e.status === 'pending'); - const parkedEntries = registry.filter(e => e.status === 'parked'); + return { registry, activeMilestone, activeMilestoneSlices, activeMilestoneHasDraft }; +} - if (pendingEntries.length > 0) { - const blockerDetails = pendingEntries - .filter(e => e.dependsOn && e.dependsOn.length > 0) - .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn!.join(', ')}`); - return { - activeMilestone: null, activeSlice: null, activeTask: null, - phase: 'blocked', - recentDecisions: [], blockers: blockerDetails.length > 0 - ? blockerDetails - : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'], - nextAction: 'Resolve milestone dependencies before proceeding.', - registry, requirements, - progress: { milestones: milestoneProgress }, - }; - } +function handleNoActiveMilestone( + registry: MilestoneRegistryEntry[], + requirements: any, + milestoneProgress: { done: number, total: number } +): GSDState { + const pendingEntries = registry.filter(e => e.status === 'pending'); + const parkedEntries = registry.filter(e => e.status === 'parked'); - if (parkedEntries.length > 0) { - const parkedIds = parkedEntries.map(e => e.id).join(', '); - return { - activeMilestone: null, activeSlice: null, activeTask: null, - phase: 'pre-planning', - recentDecisions: [], blockers: [], - nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark or create a new milestone.`, - registry, requirements, - progress: { milestones: milestoneProgress }, - }; - } - - if (registry.length === 0) { - return { - activeMilestone: null, activeSlice: null, activeTask: null, - phase: 'pre-planning', - recentDecisions: [], blockers: [], - nextAction: 'No milestones found. Run /gsd to create one.', - registry: [], requirements, - progress: { milestones: { done: 0, total: 0 } }, - }; - } - - // All milestones complete - const lastEntry = registry[registry.length - 1]; - const activeReqs = requirements.active ?? 0; - const completionNote = activeReqs > 0 - ? `All milestones complete. ${activeReqs} active requirement${activeReqs === 1 ? '' : 's'} in REQUIREMENTS.md ${activeReqs === 1 ? 'has' : 'have'} not been mapped to a milestone.` - : 'All milestones complete.'; + if (pendingEntries.length > 0) { + const blockerDetails = pendingEntries + .filter(e => e.dependsOn && e.dependsOn.length > 0) + .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn!.join(', ')}`); return { - activeMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null, - activeSlice: null, activeTask: null, - phase: 'complete', - recentDecisions: [], blockers: [], - nextAction: completionNote, + activeMilestone: null, activeSlice: null, activeTask: null, + phase: 'blocked', + recentDecisions: [], blockers: blockerDetails.length > 0 + ? blockerDetails + : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'], + nextAction: 'Resolve milestone dependencies before proceeding.', registry, requirements, progress: { milestones: milestoneProgress }, }; } - // ── Active milestone has no slices or no roadmap ──────────────────── + if (parkedEntries.length > 0) { + const parkedIds = parkedEntries.map(e => e.id).join(', '); + return { + activeMilestone: null, activeSlice: null, activeTask: null, + phase: 'pre-planning', + recentDecisions: [], blockers: [], + nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark or create a new milestone.`, + registry, requirements, + progress: { milestones: milestoneProgress }, + }; + } + + if (registry.length === 0) { + return { + activeMilestone: null, activeSlice: null, activeTask: null, + phase: 'pre-planning', + recentDecisions: [], blockers: [], + nextAction: 'No milestones found. Run /gsd to create one.', + registry: [], requirements, + progress: { milestones: { done: 0, total: 0 } }, + }; + } + + const lastEntry = registry[registry.length - 1]; + const activeReqs = requirements.active ?? 0; + const completionNote = activeReqs > 0 + ? `All milestones complete. ${activeReqs} active requirement${activeReqs === 1 ? '' : 's'} in REQUIREMENTS.md ${activeReqs === 1 ? 'has' : 'have'} not been mapped to a milestone.` + : 'All milestones complete.'; + return { + activeMilestone: null, + lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null, + activeSlice: null, activeTask: null, + phase: 'complete', + recentDecisions: [], blockers: [], + nextAction: completionNote, + registry, requirements, + progress: { milestones: milestoneProgress }, + }; +} + +async function handleAllSlicesDone( + basePath: string, + activeMilestone: ActiveRef, + registry: MilestoneRegistryEntry[], + requirements: any, + milestoneProgress: { done: number, total: number }, + sliceProgress: { done: number, total: number } +): Promise { + const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION"); + const validationContent = validationFile ? await loadFile(validationFile) : null; + const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false; + const verdict = validationContent ? extractVerdict(validationContent) : undefined; + + if (!validationTerminal || verdict === 'needs-remediation') { + return { + activeMilestone, activeSlice: null, activeTask: null, + phase: 'validating-milestone', + recentDecisions: [], blockers: [], + nextAction: `Validate milestone ${activeMilestone.id} before completion.`, + registry, requirements, + progress: { milestones: milestoneProgress, slices: sliceProgress }, + }; + } + + return { + activeMilestone, activeSlice: null, activeTask: null, + phase: 'completing-milestone', + recentDecisions: [], blockers: [], + nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`, + registry, requirements, + progress: { milestones: milestoneProgress, slices: sliceProgress }, + }; +} + +function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSlice: ActiveRef | null, activeSliceRow: SliceRow | null } { + const doneSliceIds = new Set( + activeMilestoneSlices.filter(s => isStatusDone(s.status)).map(s => s.id) + ); + + const sliceLock = process.env.GSD_SLICE_LOCK; + if (sliceLock) { + const lockedSlice = activeMilestoneSlices.find(s => s.id === sliceLock); + if (lockedSlice) { + return { activeSlice: { id: lockedSlice.id, title: lockedSlice.title }, activeSliceRow: lockedSlice }; + } else { + logWarning("state", `GSD_SLICE_LOCK=${sliceLock} not found in active slices — worker has no assigned work`); + return { activeSlice: null, activeSliceRow: null }; + } + } + + for (const s of activeMilestoneSlices) { + if (isStatusDone(s.status)) continue; + if (isDeferredStatus(s.status)) continue; + if (s.depends.every(dep => doneSliceIds.has(dep))) { + return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s }; + } + } + return { activeSlice: null, activeSliceRow: null }; +} + +async function reconcileSliceTasks( + basePath: string, + milestoneId: string, + sliceId: string, + planFile: string +): Promise { + let tasks = getSliceTasks(milestoneId, sliceId); + + if (tasks.length === 0 && planFile) { + try { + const planContent = await loadFile(planFile); + if (planContent) { + const diskPlan = parsePlan(planContent); + if (diskPlan.tasks.length > 0) { + for (let i = 0; i < diskPlan.tasks.length; i++) { + const t = diskPlan.tasks[i]; + try { + insertTask({ + id: t.id, + sliceId, + milestoneId, + title: t.title, + status: t.done ? 'complete' : 'pending', + sequence: i + 1, + }); + } catch (insertErr) { + logWarning("reconcile", `failed to insert task ${t.id} from plan file: ${insertErr instanceof Error ? insertErr.message : String(insertErr)}`); + } + } + tasks = getSliceTasks(milestoneId, sliceId); + logWarning("reconcile", `imported ${tasks.length} tasks from plan file for ${milestoneId}/${sliceId} — DB was empty (#3600)`, { mid: milestoneId, sid: sliceId }); + } + } + } catch (err) { + logError("reconcile", `plan-file task import failed for ${milestoneId}/${sliceId}: ${err instanceof Error ? err.message : String(err)}`); + } + } + + let reconciled = false; + for (const t of tasks) { + if (isStatusDone(t.status)) continue; + const summaryPath = resolveTaskFile(basePath, milestoneId, sliceId, t.id, "SUMMARY"); + if (summaryPath && existsSync(summaryPath)) { + try { + updateTaskStatus(milestoneId, sliceId, t.id, "complete"); + logWarning("reconcile", `task ${milestoneId}/${sliceId}/${t.id} status reconciled from "${t.status}" to "complete" (#2514)`, { mid: milestoneId, sid: sliceId, tid: t.id }); + reconciled = true; + } catch (e) { + logError("reconcile", `failed to update task ${t.id}`, { tid: t.id, error: (e as Error).message }); + } + } + } + if (reconciled) { + tasks = getSliceTasks(milestoneId, sliceId); + } + return tasks; +} + +async function detectBlockers(basePath: string, milestoneId: string, sliceId: string, tasks: TaskRow[]): Promise { + const completedTasks = tasks.filter(t => isStatusDone(t.status)); + for (const ct of completedTasks) { + if (ct.blocker_discovered) { + return ct.id; + } + const summaryFile = resolveTaskFile(basePath, milestoneId, sliceId, ct.id, "SUMMARY"); + if (!summaryFile) continue; + const summaryContent = await loadFile(summaryFile); + if (!summaryContent) continue; + const summary = parseSummary(summaryContent); + if (summary.frontmatter.blocker_discovered) { + return ct.id; + } + } + return null; +} + +function checkReplanTrigger(basePath: string, milestoneId: string, sliceId: string): boolean { + const sliceRow = getSlice(milestoneId, sliceId); + const dbTriggered = !!sliceRow?.replan_triggered_at; + const diskTriggered = !dbTriggered && + !!resolveSliceFile(basePath, milestoneId, sliceId, "REPLAN-TRIGGER"); + return dbTriggered || diskTriggered; +} + +async function checkInterruptedWork(basePath: string, milestoneId: string, sliceId: string): Promise { + const sDir = resolveSlicePath(basePath, milestoneId, sliceId); + const continueFile = sDir ? resolveSliceFile(basePath, milestoneId, sliceId, "CONTINUE") : null; + return !!(continueFile && await loadFile(continueFile)) || + !!(sDir && await loadFile(join(sDir, "continue.md"))); +} + +export async function deriveStateFromDb(basePath: string): Promise { + const requirements = parseRequirementCounts(await loadFile(resolveGsdRootFile(basePath, "REQUIREMENTS"))); + + let allMilestones = reconcileDiskToDb(basePath); + + const customOrder = loadQueueOrder(basePath); + const sortedIds = sortByQueueOrder(allMilestones.map(m => m.id), customOrder); + const byId = new Map(allMilestones.map(m => [m.id, m])); + allMilestones.length = 0; + for (const id of sortedIds) allMilestones.push(byId.get(id)!); + + const milestoneLock = process.env.GSD_MILESTONE_LOCK; + const milestones = milestoneLock + ? allMilestones.filter(m => m.id === milestoneLock) + : allMilestones; + + if (milestones.length === 0) { + return { + activeMilestone: null, activeSlice: null, activeTask: null, + phase: 'pre-planning', recentDecisions: [], blockers: [], + nextAction: 'No milestones found. Run /gsd to create one.', + registry: [], requirements, + progress: { milestones: { done: 0, total: 0 } }, + }; + } + + const { completeMilestoneIds, parkedMilestoneIds } = buildCompletenessSet(basePath, milestones); + + const registryContext = await buildRegistryAndFindActive(basePath, milestones, completeMilestoneIds, parkedMilestoneIds); + const { registry, activeMilestone, activeMilestoneSlices, activeMilestoneHasDraft } = registryContext; + + const milestoneProgress = { + done: registry.filter(e => e.status === 'complete').length, + total: registry.length, + }; + + if (!activeMilestone) { + return handleNoActiveMilestone(registry, requirements, milestoneProgress); + } + const hasRoadmap = resolveMilestoneFile(basePath, activeMilestone.id, "ROADMAP") !== null; if (activeMilestoneSlices.length === 0) { @@ -553,159 +767,81 @@ export async function deriveStateFromDb(basePath: string): Promise { }; } - // Has roadmap file but zero slices in DB — pre-planning (zero-slice roadmap guard) return { activeMilestone, activeSlice: null, activeTask: null, - phase: 'pre-planning', - recentDecisions: [], blockers: [], + phase: 'pre-planning', recentDecisions: [], blockers: [], nextAction: `Milestone ${activeMilestone.id} has a roadmap but no slices defined. Add slices to the roadmap.`, registry, requirements, - progress: { - milestones: milestoneProgress, - slices: { done: 0, total: 0 }, - }, + progress: { milestones: milestoneProgress, slices: { done: 0, total: 0 } }, }; } - // ── All slices done → validating/completing ───────────────────────── - // Guard: [].every() === true (vacuous truth). Without the length check, - // an empty slice array causes a premature phase transition to - // validating-milestone. See: https://github.com/gsd-build/gsd-2/issues/2667 - const allSlicesDone = activeMilestoneSlices.length > 0 && activeMilestoneSlices.every(s => isClosedStatus(s.status)); - if (allSlicesDone) { - const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION"); - const validationContent = validationFile ? await loadFile(validationFile) : null; - const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false; - const sliceProgress = { - done: activeMilestoneSlices.length, - total: activeMilestoneSlices.length, - }; + const allSlicesDone = activeMilestoneSlices.every(s => isStatusDone(s.status)); + const sliceProgress = { + done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length, + total: activeMilestoneSlices.length, + }; - if (!validationTerminal) { + if (allSlicesDone) { + return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress); + } + + const activeSliceContext = resolveSliceDependencies(activeMilestoneSlices); + if (!activeSliceContext.activeSlice) { + // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked' + if (process.env.GSD_SLICE_LOCK) { return { activeMilestone, activeSlice: null, activeTask: null, - phase: 'validating-milestone', - recentDecisions: [], blockers: [], - nextAction: `Validate milestone ${activeMilestone.id} before completion.`, + phase: 'blocked', recentDecisions: [], blockers: [`GSD_SLICE_LOCK=${process.env.GSD_SLICE_LOCK} not found in active milestone slices`], + nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.', registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress }, }; } - return { activeMilestone, activeSlice: null, activeTask: null, - phase: 'completing-milestone', - recentDecisions: [], blockers: [], - nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`, - registry, requirements, - progress: { milestones: milestoneProgress, slices: sliceProgress }, - }; - } - - // ── Find active slice (first incomplete with deps satisfied) ───────── - const sliceProgress = { - done: activeMilestoneSlices.filter(s => isClosedStatus(s.status)).length, - total: activeMilestoneSlices.length, - }; - - const doneSliceIds = new Set( - activeMilestoneSlices.filter(s => isClosedStatus(s.status)).map(s => s.id) - ); - - let activeSlice: ActiveRef | null = null; - let activeSliceRow: SliceRow | null = null; - - for (const s of activeMilestoneSlices) { - if (isClosedStatus(s.status)) continue; - if (s.depends.every(dep => doneSliceIds.has(dep))) { - activeSlice = { id: s.id, title: s.title }; - activeSliceRow = s; - break; - } - } - - if (!activeSlice) { - return { - activeMilestone, activeSlice: null, activeTask: null, - phase: 'blocked', - recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'], + phase: 'blocked', recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'], nextAction: 'Resolve dependency blockers or plan next slice.', registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress }, }; } + const { activeSlice } = activeSliceContext; - // ── Check for slice plan file on disk ──────────────────────────────── const planFile = resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "PLAN"); if (!planFile) { return { activeMilestone, activeSlice, activeTask: null, - phase: 'planning', - recentDecisions: [], blockers: [], + phase: 'planning', recentDecisions: [], blockers: [], nextAction: `Plan slice ${activeSlice.id} (${activeSlice.title}).`, registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress }, }; } - // ── Get tasks from DB ──────────────────────────────────────────────── - let tasks = getSliceTasks(activeMilestone.id, activeSlice.id); - - // ── Reconcile stale task status (#2514) ────────────────────────────── - // When a session disconnects after the agent writes SUMMARY + VERIFY - // artifacts but before postUnitPostVerification updates the DB, tasks - // remain "pending" in the DB despite being complete on disk. Without - // reconciliation, deriveState keeps returning the stale task as active, - // causing the dispatcher to re-dispatch the same completed task forever. - let reconciled = false; - for (const t of tasks) { - if (isClosedStatus(t.status)) continue; - const summaryPath = resolveTaskFile(basePath, activeMilestone.id, activeSlice.id, t.id, "SUMMARY"); - if (summaryPath && existsSync(summaryPath)) { - try { - updateTaskStatus(activeMilestone.id, activeSlice.id, t.id, "complete"); - process.stderr.write( - `gsd-reconcile: task ${activeMilestone.id}/${activeSlice.id}/${t.id} had SUMMARY on disk but DB status was "${t.status}" — updated to "complete" (#2514)\n`, - ); - reconciled = true; - } catch (e) { - // DB write failed — continue with stale status rather than crash - process.stderr.write( - `gsd-reconcile: failed to update task ${t.id}: ${(e as Error).message}\n`, - ); - } - } - } - // Re-fetch tasks if any were reconciled so downstream logic sees fresh status - if (reconciled) { - tasks = getSliceTasks(activeMilestone.id, activeSlice.id); - } - + const tasks = await reconcileSliceTasks(basePath, activeMilestone.id, activeSlice.id, planFile); + const taskProgress = { - done: tasks.filter(t => isClosedStatus(t.status)).length, + done: tasks.filter(t => isStatusDone(t.status)).length, total: tasks.length, }; - const activeTaskRow = tasks.find(t => !isClosedStatus(t.status)); + const activeTaskRow = tasks.find(t => !isStatusDone(t.status)); if (!activeTaskRow && tasks.length > 0) { - // All tasks done but slice not marked complete → summarizing return { activeMilestone, activeSlice, activeTask: null, - phase: 'summarizing', - recentDecisions: [], blockers: [], + phase: 'summarizing', recentDecisions: [], blockers: [], nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`, registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress }, }; } - // Empty plan — no tasks defined yet if (!activeTaskRow) { return { activeMilestone, activeSlice, activeTask: null, - phase: 'planning', - recentDecisions: [], blockers: [], + phase: 'planning', recentDecisions: [], blockers: [], nextAction: `Slice ${activeSlice.id} has a plan file but no tasks. Add tasks to the plan.`, registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress }, @@ -714,15 +850,13 @@ export async function deriveStateFromDb(basePath: string): Promise { const activeTask: ActiveRef = { id: activeTaskRow.id, title: activeTaskRow.title }; - // ── Task plan file check (#909) ───────────────────────────────────── const tasksDir = resolveTasksDir(basePath, activeMilestone.id, activeSlice.id); if (tasksDir && existsSync(tasksDir) && tasks.length > 0) { const allFiles = readdirSync(tasksDir).filter(f => f.endsWith(".md")); if (allFiles.length === 0) { return { activeMilestone, activeSlice, activeTask: null, - phase: 'planning', - recentDecisions: [], blockers: [], + phase: 'planning', recentDecisions: [], blockers: [], nextAction: `Task plan files missing for ${activeSlice.id}. Run plan-slice to generate task plans.`, registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress }, @@ -730,51 +864,24 @@ export async function deriveStateFromDb(basePath: string): Promise { } } - // ── Quality gate evaluation check ────────────────────────────────── - // If slice-scoped gates (Q3/Q4) are still pending, pause before execution - // so the gate-evaluate dispatch rule can run parallel sub-agents. - // Slices with zero gate rows (pre-feature or simple) skip straight through. const pendingGateCount = getPendingSliceGateCount(activeMilestone.id, activeSlice.id); if (pendingGateCount > 0) { return { activeMilestone, activeSlice, activeTask: null, - phase: 'evaluating-gates', - recentDecisions: [], blockers: [], + phase: 'evaluating-gates', recentDecisions: [], blockers: [], nextAction: `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`, registry, requirements, progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress }, }; } - // ── Blocker detection: check completed tasks for blocker_discovered ── - const completedTasks = tasks.filter(t => isClosedStatus(t.status)); - let blockerTaskId: string | null = null; - for (const ct of completedTasks) { - if (ct.blocker_discovered) { - blockerTaskId = ct.id; - break; - } - // Also check disk summary in case DB doesn't have the flag - const summaryFile = resolveTaskFile(basePath, activeMilestone.id, activeSlice.id, ct.id, "SUMMARY"); - if (!summaryFile) continue; - const summaryContent = await loadFile(summaryFile); - if (!summaryContent) continue; - const summary = parseSummary(summaryContent); - if (summary.frontmatter.blocker_discovered) { - blockerTaskId = ct.id; - break; - } - } - + const blockerTaskId = await detectBlockers(basePath, activeMilestone.id, activeSlice.id, tasks); if (blockerTaskId) { - // Loop protection: if replan_history has entries for this slice, a replan - // was already performed — don't re-enter replanning phase. const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id); if (replanHistory.length === 0) { return { activeMilestone, activeSlice, activeTask, - phase: 'replanning-slice', - recentDecisions: [], + phase: 'replanning-slice', recentDecisions: [], blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`], nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`, activeWorkspace: undefined, @@ -784,17 +891,14 @@ export async function deriveStateFromDb(basePath: string): Promise { } } - // ── REPLAN-TRIGGER detection ───────────────────────────────────────── if (!blockerTaskId) { - const sliceRow = getSlice(activeMilestone.id, activeSlice.id); - if (sliceRow?.replan_triggered_at) { - // Loop protection: if replan_history has entries, replan was already done + const isTriggered = checkReplanTrigger(basePath, activeMilestone.id, activeSlice.id); + if (isTriggered) { const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id); if (replanHistory.length === 0) { return { activeMilestone, activeSlice, activeTask, - phase: 'replanning-slice', - recentDecisions: [], + phase: 'replanning-slice', recentDecisions: [], blockers: ['Triage replan trigger detected — slice replan required'], nextAction: `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`, activeWorkspace: undefined, @@ -805,16 +909,11 @@ export async function deriveStateFromDb(basePath: string): Promise { } } - // ── Check for interrupted work ─────────────────────────────────────── - const sDir = resolveSlicePath(basePath, activeMilestone.id, activeSlice.id); - const continueFile = sDir ? resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "CONTINUE") : null; - const hasInterrupted = !!(continueFile && await loadFile(continueFile)) || - !!(sDir && await loadFile(join(sDir, "continue.md"))); + const hasInterrupted = await checkInterruptedWork(basePath, activeMilestone.id, activeSlice.id); return { activeMilestone, activeSlice, activeTask, - phase: 'executing', - recentDecisions: [], blockers: [], + phase: 'executing', recentDecisions: [], blockers: [], nextAction: hasInterrupted ? `Resume interrupted work on ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}. Read continue.md first.` : `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`, @@ -823,11 +922,14 @@ export async function deriveStateFromDb(basePath: string): Promise { }; } + // LEGACY: Filesystem-based state derivation for unmigrated projects. // DB-backed projects use deriveStateFromDb() above. Target: extract to // state-legacy.ts when all projects are DB-backed. export async function _deriveStateImpl(basePath: string): Promise { - const milestoneIds = findMilestoneIds(basePath); + const diskIds = findMilestoneIds(basePath); + const customOrder = loadQueueOrder(basePath); + const milestoneIds = sortByQueueOrder(diskIds, customOrder); // ── Parallel worker isolation ────────────────────────────────────────── // When GSD_MILESTONE_LOCK is set, this process is a parallel worker @@ -1016,22 +1118,25 @@ export async function _deriveStateImpl(basePath: string): Promise { const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION"); const validationContent = validationFile ? await cachedLoadFile(validationFile) : null; const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false; + const verdict = validationContent ? extractVerdict(validationContent) : undefined; + // needs-remediation is terminal but requires re-validation (#3596) + const needsRevalidation = !validationTerminal || verdict === 'needs-remediation'; if (summaryFile) { // Summary exists → milestone is complete regardless of validation state. // The summary is the terminal artifact (#864). registry.push({ id: mid, title, status: 'complete' }); - } else if (!validationTerminal && !activeMilestoneFound) { - // No summary and no terminal validation → validating-milestone + } else if (needsRevalidation && !activeMilestoneFound) { + // No summary and needs (re-)validation → validating-milestone activeMilestone = { id: mid, title }; activeRoadmap = roadmap; activeMilestoneFound = true; registry.push({ id: mid, title, status: 'active' }); - } else if (!validationTerminal && activeMilestoneFound) { - // No summary and no terminal validation, but another milestone is already active + } else if (needsRevalidation && activeMilestoneFound) { + // Needs (re-)validation, but another milestone is already active registry.push({ id: mid, title, status: 'pending' }); } else if (!activeMilestoneFound) { - // Terminal validation but no summary → completing-milestone + // Terminal validation (pass/needs-attention) but no summary → completing-milestone activeMilestone = { id: mid, title }; activeRoadmap = roadmap; activeMilestoneFound = true; @@ -1148,7 +1253,8 @@ export async function _deriveStateImpl(basePath: string): Promise { ? `All milestones complete. ${activeReqs} active requirement${activeReqs === 1 ? '' : 's'} in REQUIREMENTS.md ${activeReqs === 1 ? 'has' : 'have'} not been mapped to a milestone.` : 'All milestones complete.'; return { - activeMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null, + activeMilestone: null, + lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null, activeSlice: null, activeTask: null, phase: 'complete', @@ -1216,12 +1322,15 @@ export async function _deriveStateImpl(basePath: string): Promise { const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION"); const validationContent = validationFile ? await cachedLoadFile(validationFile) : null; const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false; + const verdict = validationContent ? extractVerdict(validationContent) : undefined; const sliceProgress = { done: activeRoadmap.slices.length, total: activeRoadmap.slices.length, }; - if (!validationTerminal) { + // Force re-validation when verdict is needs-remediation — remediation slices + // may have completed since the stale validation was written (#3596). + if (!validationTerminal || verdict === 'needs-remediation') { return { activeMilestone, activeSlice: null, @@ -1265,11 +1374,38 @@ export async function _deriveStateImpl(basePath: string): Promise { const doneSliceIds = new Set(activeRoadmap.slices.filter(s => s.done).map(s => s.id)); let activeSlice: ActiveRef | null = null; - for (const s of activeRoadmap.slices) { - if (s.done) continue; - if (s.depends.every(dep => doneSliceIds.has(dep))) { - activeSlice = { id: s.id, title: s.title }; - break; + // ── Slice-level parallel worker isolation ───────────────────────────── + // When GSD_SLICE_LOCK is set, override activeSlice to only the locked slice. + const sliceLockLegacy = process.env.GSD_SLICE_LOCK; + if (sliceLockLegacy) { + const lockedSlice = activeRoadmap.slices.find(s => s.id === sliceLockLegacy); + if (lockedSlice) { + activeSlice = { id: lockedSlice.id, title: lockedSlice.title }; + } else { + logWarning("state", `GSD_SLICE_LOCK=${sliceLockLegacy} not found in active slices — worker has no assigned work`); + return { + activeMilestone, + activeSlice: null, + activeTask: null, + phase: 'blocked', + recentDecisions: [], + blockers: [`GSD_SLICE_LOCK=${sliceLockLegacy} not found in active milestone slices`], + nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.', + registry, + requirements, + progress: { + milestones: milestoneProgress, + slices: sliceProgress, + }, + }; + } + } else { + for (const s of activeRoadmap.slices) { + if (s.done) continue; + if (s.depends.every(dep => doneSliceIds.has(dep))) { + activeSlice = { id: s.id, title: s.title }; + break; + } } } @@ -1327,9 +1463,7 @@ export async function _deriveStateImpl(basePath: string): Promise { const summaryPath = resolveTaskFile(basePath, activeMilestone.id, activeSlice.id, t.id, "SUMMARY"); if (summaryPath && existsSync(summaryPath)) { t.done = true; - process.stderr.write( - `gsd-reconcile: task ${activeMilestone.id}/${activeSlice.id}/${t.id} has SUMMARY on disk but plan shows incomplete — marking done (#2514)\n`, - ); + logWarning("reconcile", `task ${activeMilestone.id}/${activeSlice.id}/${t.id} reconciled via SUMMARY on disk (#2514)`, { mid: activeMilestone.id, sid: activeSlice.id, tid: t.id }); } } diff --git a/src/resources/extensions/gsd/status-guards.ts b/src/resources/extensions/gsd/status-guards.ts index 650aefc6c..ffd54dfc4 100644 --- a/src/resources/extensions/gsd/status-guards.ts +++ b/src/resources/extensions/gsd/status-guards.ts @@ -1,13 +1,27 @@ /** * Status predicates for GSD state-machine guards. * - * The DB stores status as free-form strings. Two values indicate - * "closed": "complete" (canonical) and "done" (legacy / alias). + * The DB stores status as free-form strings. Three values indicate + * "closed": "complete" (canonical), "done" (legacy / alias), and + * "skipped" (user-directed skip via rethink or backtrack). * Every inline `status === "complete" || status === "done"` should * use isClosedStatus() instead. */ /** Returns true when a milestone, slice, or task status indicates closure. */ export function isClosedStatus(status: string): boolean { - return status === "complete" || status === "done"; + return status === "complete" || status === "done" || status === "skipped"; +} + +/** Returns true when a slice status indicates it was deferred by a decision. */ +export function isDeferredStatus(status: string): boolean { + return status === "deferred"; +} + +/** + * Returns true when a slice should be skipped during active-slice selection. + * This includes both closed (complete/done) and deferred slices. + */ +export function isInactiveStatus(status: string): boolean { + return isClosedStatus(status) || isDeferredStatus(status); } diff --git a/src/resources/extensions/gsd/templates/context.md b/src/resources/extensions/gsd/templates/context.md index 3e19bb788..0111e7c83 100644 --- a/src/resources/extensions/gsd/templates/context.md +++ b/src/resources/extensions/gsd/templates/context.md @@ -38,6 +38,28 @@ To call this milestone complete, we must prove: - {{one real end-to-end scenario}} - {{what cannot be simulated if this milestone is to be considered truly done}} +## Architectural Decisions + +### {{decisionTitle}} + +**Decision:** {{decisionStatement}} + +**Rationale:** {{rationale}} + +**Alternatives Considered:** +- {{alternative}} — {{whyNotChosen}} + +--- + +> Add additional decisions as separate `### Decision Title` blocks following the same structure above. +> See `.gsd/DECISIONS.md` for the full append-only register of all project decisions. + +## Error Handling Strategy + +{{errorHandlingStrategy}} + +> Describe the approach for handling failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant. + ## Risks and Unknowns - {{riskOrUnknown}} — {{whyItMatters}} @@ -47,8 +69,6 @@ To call this milestone complete, we must prove: - `{{fileOrModule}}` — {{howItRelates}} - `{{fileOrModule}}` — {{howItRelates}} -> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution. - ## Relevant Requirements - {{requirementId}} — {{howThisMilestoneAdvancesIt}} @@ -71,6 +91,18 @@ To call this milestone complete, we must prove: - {{systemOrService}} — {{howThisMilestoneInteractsWithIt}} +## Testing Requirements + +{{testingRequirements}} + +> Specify test types (unit, integration, e2e), coverage expectations, and specific test scenarios that must pass. + +## Acceptance Criteria + +{{acceptanceCriteria}} + +> Per-slice acceptance criteria gathered during discussion. Each slice should have clear, testable criteria. + ## Open Questions - {{question}} — {{currentThinking}} diff --git a/src/resources/extensions/gsd/tests/artifact-corruption-2630.test.ts b/src/resources/extensions/gsd/tests/artifact-corruption-2630.test.ts new file mode 100644 index 000000000..a35691602 --- /dev/null +++ b/src/resources/extensions/gsd/tests/artifact-corruption-2630.test.ts @@ -0,0 +1,288 @@ +// GSD — regression tests for issue #2630 +// Milestone/slice artifact rendering must not corrupt existing markdown. +// Three bugs: (A) milestone title double-prefix, (B) full_uat_md demo fallback, +// (C) STATE.md title double-prefix. + +import test from 'node:test'; +import assert from 'node:assert/strict'; + +import { + renderPlanContent, + renderRoadmapContent, + renderStateContent, +} from '../workflow-projections.ts'; +import type { SliceRow, TaskRow, MilestoneRow } from '../gsd-db.ts'; +import type { GSDState } from '../types.ts'; + +// ─── Helpers ───────────────────────────────────────────────────────────── + +function makeSliceRow(overrides?: Partial): SliceRow { + return { + milestone_id: 'M001', + id: 'S04', + title: 'Dependency-driven scene pipeline and state truth', + status: 'complete', + risk: 'high', + depends: ['S03'], + demo: '', + created_at: '2026-01-01T00:00:00Z', + completed_at: '2026-01-15T00:00:00Z', + full_summary_md: '', + full_uat_md: `# S04: Dependency-driven scene pipeline and state truth — UAT + +**Milestone:** M001 +**Written:** 2026-01-15 + +## UAT Type: Functional + +### Scenario 1: Pipeline processes dependencies +**Given** a scene with dependencies +**When** the pipeline runs +**Then** dependencies are resolved in order`, + goal: 'Build dependency-driven scene pipeline', + success_criteria: '', + proof_level: '', + integration_closure: '', + observability_impact: '', + sequence: 4, + replan_triggered_at: null, + ...overrides, + }; +} + +function makeTaskRow(overrides?: Partial): TaskRow { + return { + milestone_id: 'M001', + slice_id: 'S04', + id: 'T01', + title: 'Test Task', + status: 'done', + one_liner: '', + narrative: '', + verification_result: '', + duration: '', + completed_at: null, + blocker_discovered: false, + deviations: '', + known_issues: '', + key_files: [], + key_decisions: [], + full_summary_md: '', + full_plan_md: '', + description: 'Test description', + estimate: '30m', + files: [], + verify: 'npm test', + inputs: [], + expected_output: [], + observability_impact: '', + sequence: 0, + ...overrides, + }; +} + +function makeMilestoneRow(overrides?: Partial): MilestoneRow { + return { + id: 'M001', + title: 'Topic-to-pipeline foundation', + status: 'active', + depends_on: [], + created_at: '2026-01-01T00:00:00Z', + completed_at: null, + vision: 'Build the topic-to-pipeline foundation', + success_criteria: [], + key_risks: [], + proof_strategy: [], + verification_contract: '', + verification_integration: '', + verification_operational: '', + verification_uat: '', + definition_of_done: [], + requirement_coverage: '', + boundary_map_markdown: '', + ...overrides, + }; +} + +function makeGSDState(overrides?: Partial): GSDState { + return { + activeMilestone: { id: 'M001', title: 'Topic-to-pipeline foundation' }, + activeSlice: { id: 'S01', title: 'Auth Layer' }, + activeTask: null, + phase: 'executing', + recentDecisions: [], + blockers: [], + nextAction: 'Continue execution', + registry: [], + requirements: undefined, + ...overrides, + }; +} + +// ─── Bug A: milestone title double-prefix ──────────────────────────────── +// When params.title already contains "M001: ", the H1 should NOT become +// "# M001: M001: Topic-to-pipeline foundation" + +test('#2630 renderRoadmapContent: milestone title with pre-existing ID prefix renders without duplication', () => { + const milestone = makeMilestoneRow({ title: 'M001: Topic-to-pipeline foundation' }); + const content = renderRoadmapContent(milestone, []); + + // The H1 must be exactly "# M001: Topic-to-pipeline foundation", not "# M001: M001: ..." + assert.ok( + content.includes('# M001: Topic-to-pipeline foundation'), + `expected single prefix in H1, got: ${content.split('\n')[0]}`, + ); + assert.ok( + !content.includes('M001: M001:'), + `found double prefix in roadmap H1: ${content.split('\n')[0]}`, + ); +}); + +test('#2630 renderStateContent: active milestone title with pre-existing ID prefix renders without duplication', () => { + const state = makeGSDState({ + activeMilestone: { id: 'M001', title: 'M001: Topic-to-pipeline foundation' }, + }); + const content = renderStateContent(state); + + assert.ok( + !content.includes('M001: M001:'), + `found double prefix in STATE.md: ${content}`, + ); + assert.ok( + content.includes('**Active Milestone:** M001: Topic-to-pipeline foundation'), + `expected single prefix, got: ${content}`, + ); +}); + +test('#2630 renderStateContent: registry entry with pre-existing ID prefix renders without duplication', () => { + const state = makeGSDState({ + registry: [ + { id: 'M001', title: 'M001: Topic-to-pipeline foundation', status: 'active' }, + ], + }); + const content = renderStateContent(state); + + assert.ok( + !content.includes('M001: M001:'), + `found double prefix in registry: ${content}`, + ); +}); + +// ─── Bug D: PLAN.md slice title double-prefix ────────────────────────────── +// When sliceRow.title already contains "S04: ", the H1 should NOT become +// "# S04: S04: Dependency-driven scene pipeline and state truth" + +test('#2630 renderPlanContent: slice title with pre-existing ID prefix renders without duplication', () => { + const slice = makeSliceRow({ title: 'S04: Dependency-driven scene pipeline and state truth' }); + const content = renderPlanContent(slice, []); + + // The H1 must be exactly "# S04: Dependency-driven scene pipeline and state truth" + assert.ok( + content.includes('# S04: Dependency-driven scene pipeline and state truth'), + `expected single prefix in H1, got: ${content.split('\n')[0]}`, + ); + assert.ok( + !content.includes('S04: S04:'), + `found double prefix in PLAN.md H1: ${content.split('\n')[0]}`, + ); +}); + +test('#2630 renderPlanContent: slice title without prefix still renders correctly', () => { + const slice = makeSliceRow({ title: 'Dependency-driven scene pipeline and state truth' }); + const content = renderPlanContent(slice, []); + + assert.ok( + content.startsWith('# S04: Dependency-driven scene pipeline and state truth'), + `expected prefixed H1, got: ${content.split('\n')[0]}`, + ); +}); + +// ─── Bug B: full_uat_md as demo fallback ───────────────────────────────── +// When slice.demo is empty and full_uat_md is a multi-line UAT document, +// the renderers must NOT inject the entire UAT body. + +test('#2630 renderPlanContent: empty demo must not inject full_uat_md body into plan', () => { + const slice = makeSliceRow({ demo: '' }); + const content = renderPlanContent(slice, []); + + // The **Demo:** line must be a single line, not multi-line UAT content + const demoLine = content.split('\n').find(l => l.startsWith('**Demo:**')); + assert.ok(demoLine, 'should have a Demo line'); + + // Must not contain UAT headings or body + assert.ok( + !content.includes('## UAT Type'), + `plan contains UAT body content: ${content}`, + ); + assert.ok( + !content.includes('**Milestone:** M001'), + `plan contains UAT metadata: ${content}`, + ); + + // The Demo line must not contain newlines (single line only) + assert.ok( + !demoLine!.includes('\n'), + `Demo line must be single line, got: ${demoLine}`, + ); +}); + +test('#2630 renderPlanContent: null demo must not inject full_uat_md body into plan', () => { + const slice = makeSliceRow({ demo: null as unknown as string }); + const content = renderPlanContent(slice, []); + + assert.ok( + !content.includes('## UAT Type'), + `plan contains UAT body content when demo is null`, + ); +}); + +test('#2630 renderRoadmapContent: empty demo must not inject full_uat_md into roadmap table', () => { + const milestone = makeMilestoneRow(); + const slices = [makeSliceRow({ demo: '' })]; + + const content = renderRoadmapContent(milestone, slices); + + // Roadmap table cell for "After this" must be single-line + assert.ok( + !content.includes('## UAT Type'), + `roadmap contains UAT body content: ${content}`, + ); + assert.ok( + !content.includes('**Milestone:** M001'), + `roadmap contains UAT metadata: ${content}`, + ); + + // The table row containing S04 must be a single line + const s04Line = content.split('\n').find(l => l.includes('| S04 |')); + assert.ok(s04Line, 'should have S04 table row'); + assert.ok( + !s04Line!.includes('# S04:'), + `roadmap table cell contains UAT heading: ${s04Line}`, + ); +}); + +test('#2630 renderRoadmapContent: null demo must not inject full_uat_md into roadmap table', () => { + const milestone = makeMilestoneRow(); + const slices = [makeSliceRow({ demo: null as unknown as string })]; + + const content = renderRoadmapContent(milestone, slices); + + assert.ok( + !content.includes('## UAT Type'), + `roadmap contains UAT body content when demo is null`, + ); +}); + +test('#2630 renderPlanContent: with valid demo string does not use full_uat_md', () => { + const slice = makeSliceRow({ demo: 'Login flow works end-to-end' }); + const content = renderPlanContent(slice, []); + + assert.ok( + content.includes('**Demo:** After this: Login flow works end-to-end'), + `expected demo text, got: ${content}`, + ); + assert.ok( + !content.includes('UAT'), + `should not contain UAT when demo is provided`, + ); +}); diff --git a/src/resources/extensions/gsd/tests/ask-user-questions-dedup.test.ts b/src/resources/extensions/gsd/tests/ask-user-questions-dedup.test.ts new file mode 100644 index 000000000..40276f33c --- /dev/null +++ b/src/resources/extensions/gsd/tests/ask-user-questions-dedup.test.ts @@ -0,0 +1,120 @@ +// ask-user-questions-dedup — Regression tests for per-turn deduplication +// +// Verifies that duplicate ask_user_questions calls within a single turn +// return cached results instead of re-dispatching (especially to remote +// channels like Discord). Also verifies the strict loop guard threshold +// for interactive tools. +// +// Regression: duplicate questions were sent to Discord when the LLM called +// ask_user_questions multiple times with the same question set in one turn, +// causing user confusion and tool failure cascading to plain text fallback. + +import { describe, test, beforeEach } from "node:test"; +import assert from "node:assert/strict"; +import { + checkToolCallLoop, + resetToolCallLoopGuard, +} from "../bootstrap/tool-call-loop-guard.ts"; +import { + resetAskUserQuestionsCache, + questionSignature, +} from "../../ask-user-questions.ts"; + +// ═══════════════════════════════════════════════════════════════════════════ +// Strict loop guard: ask_user_questions blocks on 2nd identical call +// ═══════════════════════════════════════════════════════════════════════════ + +describe("ask_user_questions dedup", () => { + beforeEach(() => { + resetToolCallLoopGuard(); + resetAskUserQuestionsCache(); + }); + + test("loop guard blocks 2nd identical ask_user_questions call", () => { + const args = { questions: [{ id: "app_coverage", question: "Which apps?" }] }; + + const first = checkToolCallLoop("ask_user_questions", args); + assert.equal(first.block, false, "First call should be allowed"); + + const second = checkToolCallLoop("ask_user_questions", args); + assert.equal(second.block, true, "2nd identical call should be blocked"); + assert.ok(second.reason!.includes("ask_user_questions"), "Reason should name the tool"); + }); + + test("loop guard allows different ask_user_questions calls", () => { + const args1 = { questions: [{ id: "app_coverage", question: "Which apps?" }] }; + const args2 = { questions: [{ id: "testing_focus", question: "What priority?" }] }; + + const first = checkToolCallLoop("ask_user_questions", args1); + assert.equal(first.block, false, "First call allowed"); + + const second = checkToolCallLoop("ask_user_questions", args2); + assert.equal(second.block, false, "Different question set should be allowed"); + }); + + test("non-interactive tools still use normal threshold of 4", () => { + const args = { query: "same query" }; + + for (let i = 1; i <= 4; i++) { + const result = checkToolCallLoop("web_search", args); + assert.equal(result.block, false, `web_search call ${i} should be allowed`); + } + + const fifth = checkToolCallLoop("web_search", args); + assert.equal(fifth.block, true, "5th identical web_search should be blocked"); + }); + + test("cache resets independently from loop guard", () => { + // Verify the reset function exists and is callable + resetAskUserQuestionsCache(); + // No error means the cache module is properly exported and functional + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // questionSignature: full-payload hashing prevents stale cache hits + // ═══════════════════════════════════════════════════════════════════════════ + + test("same IDs with different question text produce different signatures", () => { + const q1 = [{ id: "scope", header: "Scope", question: "Which apps to cover?", + options: [{ label: "All", description: "Everything" }] }]; + const q2 = [{ id: "scope", header: "Scope", question: "Which services to test?", + options: [{ label: "All", description: "Everything" }] }]; + + assert.notEqual(questionSignature(q1), questionSignature(q2), + "Different question text with same ID must produce different signatures"); + }); + + test("same IDs with different options produce different signatures", () => { + const q1 = [{ id: "scope", header: "Scope", question: "Pick one", + options: [{ label: "A", description: "Option A" }] }]; + const q2 = [{ id: "scope", header: "Scope", question: "Pick one", + options: [{ label: "B", description: "Option B" }] }]; + + assert.notEqual(questionSignature(q1), questionSignature(q2), + "Different options with same ID must produce different signatures"); + }); + + test("identical payloads in different order produce same signature", () => { + const q1 = [ + { id: "b", header: "B", question: "Q2", options: [{ label: "X", description: "x" }] }, + { id: "a", header: "A", question: "Q1", options: [{ label: "Y", description: "y" }] }, + ]; + const q2 = [ + { id: "a", header: "A", question: "Q1", options: [{ label: "Y", description: "y" }] }, + { id: "b", header: "B", question: "Q2", options: [{ label: "X", description: "x" }] }, + ]; + + assert.equal(questionSignature(q1), questionSignature(q2), + "Same questions in different order must produce the same signature"); + }); + + test("allowMultiple difference produces different signature", () => { + const q1 = [{ id: "scope", header: "Scope", question: "Pick", + options: [{ label: "A", description: "a" }], allowMultiple: false }]; + const q2 = [{ id: "scope", header: "Scope", question: "Pick", + options: [{ label: "A", description: "a" }], allowMultiple: true }]; + + assert.notEqual(questionSignature(q1), questionSignature(q2), + "allowMultiple difference must produce different signatures"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/auto-dashboard.test.ts b/src/resources/extensions/gsd/tests/auto-dashboard.test.ts index b772b1e48..13ef53a6c 100644 --- a/src/resources/extensions/gsd/tests/auto-dashboard.test.ts +++ b/src/resources/extensions/gsd/tests/auto-dashboard.test.ts @@ -1,7 +1,8 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { readFileSync } from "node:fs"; +import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; +import { tmpdir } from "node:os"; import { unitVerb, @@ -11,11 +12,29 @@ import { formatWidgetTokens, estimateTimeRemaining, extractUatSliceId, + getWidgetMode, + cycleWidgetMode, + _resetWidgetModeForTests, } from "../auto-dashboard.ts"; const autoSource = readFileSync(join(process.cwd(), "src", "resources", "extensions", "gsd", "auto.ts"), "utf-8"); const dashboardSource = readFileSync(join(process.cwd(), "src", "resources", "extensions", "gsd", "auto-dashboard.ts"), "utf-8"); +function makeTempDir(prefix: string): string { + return join( + tmpdir(), + `gsd-auto-dashboard-test-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, + ); +} + +function cleanup(dir: string): void { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // best-effort + } +} + // ─── unitVerb ───────────────────────────────────────────────────────────── test("unitVerb maps known unit types to verbs", () => { @@ -209,3 +228,35 @@ test("extractUatSliceId returns null for invalid formats", () => { assert.equal(extractUatSliceId(""), null); assert.equal(extractUatSliceId("M001/T01"), null); }); + +test("widget mode respects project preference precedence and persists there", (t) => { + const homeDir = makeTempDir("home"); + const projectDir = makeTempDir("project"); + const globalPrefsPath = join(homeDir, ".gsd", "preferences.md"); + const projectPrefsPath = join(projectDir, ".gsd", "preferences.md"); + + mkdirSync(join(homeDir, ".gsd"), { recursive: true }); + mkdirSync(join(projectDir, ".gsd"), { recursive: true }); + writeFileSync(globalPrefsPath, "---\nversion: 1\nwidget_mode: off\n---\n", "utf-8"); + writeFileSync(projectPrefsPath, "---\nversion: 1\nwidget_mode: small\n---\n", "utf-8"); + + t.after(() => { + cleanup(homeDir); + cleanup(projectDir); + _resetWidgetModeForTests(); + }); + + _resetWidgetModeForTests(); + + assert.equal(getWidgetMode(projectPrefsPath, globalPrefsPath), "small", "project widget_mode overrides global"); + assert.equal( + cycleWidgetMode(projectPrefsPath, globalPrefsPath), + "min", + "cycling advances from the project-owned mode", + ); + + const projectPrefs = readFileSync(projectPrefsPath, "utf-8"); + const globalPrefs = readFileSync(globalPrefsPath, "utf-8"); + assert.match(projectPrefs, /widget_mode:\s*min/); + assert.match(globalPrefs, /widget_mode:\s*off/); +}); diff --git a/src/resources/extensions/gsd/tests/auto-loop.test.ts b/src/resources/extensions/gsd/tests/auto-loop.test.ts index c472780cc..6fd5eb0e6 100644 --- a/src/resources/extensions/gsd/tests/auto-loop.test.ts +++ b/src/resources/extensions/gsd/tests/auto-loop.test.ts @@ -1,4 +1,4 @@ -import test from "node:test"; +import test, { mock } from "node:test"; import assert from "node:assert/strict"; import { readFileSync } from "node:fs"; import { resolve } from "node:path"; @@ -191,6 +191,54 @@ test("runUnit returns cancelled when session creation times out", async () => { assert.equal(pi.calls.length, 0); }); +test("runUnit keeps the session-switch guard across a late newSession settlement", async () => { + _resetPendingResolve(); + mock.timers.enable(); + + try { + const ctx = makeMockCtx(); + const pi = makeMockPi(); + // Use delays longer than NEW_SESSION_TIMEOUT_MS (120s) so the timeout fires + const firstSession = makeMockSession({ newSessionDelayMs: 200_000 }); + const secondSession = makeMockSession({ newSessionDelayMs: 200_000 }); + + const firstRun = runUnit(ctx, pi, firstSession, "task", "T01", "prompt"); + + // Tick past the 120s session timeout + mock.timers.tick(121_000); + await Promise.resolve(); + + const firstResult = await firstRun; + assert.equal(firstResult.status, "cancelled"); + assert.equal(isSessionSwitchInFlight(), true, "guard should remain set after the timed-out session"); + + mock.timers.tick(1); + const secondRun = runUnit(ctx, pi, secondSession, "task", "T02", "prompt"); + + mock.timers.tick(100_000); + await Promise.resolve(); + assert.equal( + isSessionSwitchInFlight(), + true, + "late settlement from the first session must not clear the newer session guard", + ); + + // Tick past the second session's timeout (121s total > 120s NEW_SESSION_TIMEOUT_MS) + mock.timers.tick(21_001); + await Promise.resolve(); + + const secondResult = await secondRun; + assert.equal(secondResult.status, "cancelled"); + + // Tick past the second session's delayed promise (200s) so .finally() fires + mock.timers.tick(80_000); + await Promise.resolve(); + assert.equal(isSessionSwitchInFlight(), false, "guard should clear after the newer session settles"); + } finally { + mock.timers.reset(); + } +}); + test("runUnit returns cancelled when s.active is false before sendMessage", async () => { _resetPendingResolve(); @@ -317,6 +365,35 @@ test("auto/resolve.ts one-shot pattern: _currentResolve is nulled before calling ); }); +test("auto/phases.ts: selectAndApplyModel called exactly once and before updateProgressWidget (#2907)", () => { + const src = readFileSync( + resolve(import.meta.dirname, "..", "auto", "phases.ts"), + "utf-8", + ); + // Extract the runUnitPhase function body + const fnStart = src.indexOf("export async function runUnitPhase"); + assert.ok(fnStart > 0, "runUnitPhase should exist in phases.ts"); + const fnBody = src.slice(fnStart, fnStart + 12000); + + // selectAndApplyModel must appear exactly once + const allOccurrences = [...fnBody.matchAll(/selectAndApplyModel\(/g)]; + assert.equal( + allOccurrences.length, + 1, + `selectAndApplyModel should be called exactly once in runUnitPhase, found ${allOccurrences.length} calls`, + ); + + // selectAndApplyModel must appear BEFORE updateProgressWidget + const modelIdx = fnBody.indexOf("selectAndApplyModel("); + const widgetIdx = fnBody.indexOf("updateProgressWidget("); + assert.ok(modelIdx > 0, "selectAndApplyModel should exist in runUnitPhase"); + assert.ok(widgetIdx > 0, "updateProgressWidget should exist in runUnitPhase"); + assert.ok( + modelIdx < widgetIdx, + "selectAndApplyModel must be called BEFORE updateProgressWidget (#2899/#2907)", + ); +}); + // ─── autoLoop tests (T02) ───────────────────────────────────────────────── /** @@ -383,7 +460,7 @@ function makeMockDeps( getCurrentBranch: () => "main", autoWorktreeBranch: () => "auto/M001", resolveMilestoneFile: () => null, - reconcileMergeState: () => false, + reconcileMergeState: () => "clean", getLedger: () => null, getProjectTotals: () => ({ cost: 0 }), formatCost: (c: number) => `$${c.toFixed(2)}`, @@ -2078,11 +2155,11 @@ test("autoLoop rejects execute-task with 0 tool calls as hallucinated (#1833)", // The task should NOT have been added to completedUnits on the first iteration // (0 tool calls), but SHOULD be added on the second iteration (5 tool calls) const warningNotification = notifications.find( - (n) => n.includes("0 tool calls") && n.includes("hallucinated"), + (n) => n.includes("0 tool calls") && n.includes("context exhaustion"), ); assert.ok( warningNotification, - "should notify about 0 tool calls hallucination", + "should notify about 0 tool calls context exhaustion", ); // Verify deriveState was called at least twice (two iterations) @@ -2093,7 +2170,7 @@ test("autoLoop rejects execute-task with 0 tool calls as hallucinated (#1833)", ); }); -test("autoLoop does NOT reject non-execute-task units with 0 tool calls (#1833)", async () => { +test("autoLoop rejects complete-slice with 0 tool calls as context-exhausted (#2653)", async () => { _resetPendingResolve(); const ctx = makeMockCtx(); @@ -2101,6 +2178,7 @@ test("autoLoop does NOT reject non-execute-task units with 0 tool calls (#1833)" ctx.sessionManager = { getSessionFile: () => "/tmp/session.json" }; const pi = makeMockPi(); + let iterationCount = 0; const notifications: string[] = []; ctx.ui.notify = (msg: string) => { notifications.push(msg); }; @@ -2134,7 +2212,7 @@ test("autoLoop does NOT reject non-execute-task units with 0 tool calls (#1833)" }; }, closeoutUnit: async () => { - // complete-slice with 0 tool calls is fine (e.g. it may just update status) + // complete-slice with 0 tool calls — context exhausted, no progress mockLedger.units.push({ type: "complete-slice", id: "M001/S01", @@ -2148,31 +2226,51 @@ test("autoLoop does NOT reject non-execute-task units with 0 tool calls (#1833)" getLedger: () => mockLedger, postUnitPostVerification: async () => { deps.callLog.push("postUnitPostVerification"); - s.active = false; + iterationCount++; + // Deactivate after 2nd iteration + s.active = iterationCount < 2; return "continue" as const; }, }); const loopPromise = autoLoop(ctx, pi, s, deps); + // First iteration: complete-slice with 0 tool calls → rejected await new Promise((r) => setTimeout(r, 50)); resolveAgentEnd(makeEvent()); + // Second iteration: re-dispatched, this time with tool calls + await new Promise((r) => setTimeout(r, 50)); + mockLedger.units.length = 0; + (deps as any).closeoutUnit = async () => { + mockLedger.units.push({ + type: "complete-slice", + id: "M001/S01", + startedAt: s.currentUnit?.startedAt ?? Date.now(), + toolCalls: 3, + assistantMessages: 2, + tokens: { input: 200, output: 400, total: 600, cacheRead: 0, cacheWrite: 0 }, + cost: 0.30, + }); + }; + resolveAgentEnd(makeEvent()); + await loopPromise; - // Should NOT have a hallucination warning for non-execute-task units + // Should have a warning about 0 tool calls for complete-slice const warningNotification = notifications.find( - (n) => n.includes("0 tool calls") && n.includes("hallucinated"), + (n) => n.includes("0 tool calls"), ); assert.ok( - !warningNotification, - "should NOT flag non-execute-task units with 0 tool calls", + warningNotification, + "should flag complete-slice with 0 tool calls as failed (#2653)", ); - // Verify the loop ran to completion (postUnitPostVerification was called) + // Verify deriveState was called at least twice (two iterations: rejected + retry) + const deriveCount = deps.callLog.filter((c) => c === "deriveState").length; assert.ok( - deps.callLog.includes("postUnitPostVerification"), - "complete-slice with 0 tool calls should still complete the post-unit pipeline", + deriveCount >= 2, + `deriveState should be called at least 2 times for retry (got ${deriveCount})`, ); }); diff --git a/src/resources/extensions/gsd/tests/auto-mode-interactive-guard.test.ts b/src/resources/extensions/gsd/tests/auto-mode-interactive-guard.test.ts new file mode 100644 index 000000000..ee830e081 --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-mode-interactive-guard.test.ts @@ -0,0 +1,71 @@ +/** + * Test: auto-mode prompts must prohibit ask_user_questions / secure_env_collect + * + * Bug #2936: When the LLM calls ask_user_questions during auto-mode units + * (plan-slice, execute-task, complete-slice), the interactive tool queues a + * user response which causes the subsequent gsd_plan_slice / gsd_complete_task + * call to fail with "Skipped due to queued user message." The canonical GSD + * tool call is never recorded, verifyExpectedArtifact finds no artifact, and + * the dispatch loop re-dispatches the same unit 2-4x. + * + * Fix: Each auto-mode prompt must contain an "Autonomous execution" guard + * that explicitly prohibits ask_user_questions and secure_env_collect. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const promptsDir = join(__dirname, "..", "prompts"); + +function loadPromptRaw(name: string): string { + return readFileSync(join(promptsDir, `${name}.md`), "utf-8"); +} + +const AUTO_MODE_PROMPTS = ["plan-slice", "execute-task", "complete-slice"]; + +for (const promptName of AUTO_MODE_PROMPTS) { + test(`${promptName} prompt prohibits ask_user_questions in auto-mode`, () => { + const content = loadPromptRaw(promptName); + + assert.ok( + content.includes("ask_user_questions"), + `${promptName}.md must mention ask_user_questions (to prohibit it)`, + ); + + assert.ok( + content.includes("secure_env_collect"), + `${promptName}.md must mention secure_env_collect (to prohibit it)`, + ); + + // The guard must clearly state this is autonomous / auto-mode + assert.ok( + content.toLowerCase().includes("auto-mode") || content.toLowerCase().includes("autonomous"), + `${promptName}.md must reference auto-mode or autonomous execution`, + ); + + // The guard must indicate no human is available + assert.ok( + content.includes("no human") || content.includes("no user"), + `${promptName}.md must state that no human/user is available to answer`, + ); + }); +} + +test("auto-mode prompts contain autonomous guard before final tool call reminder", () => { + for (const promptName of AUTO_MODE_PROMPTS) { + const content = loadPromptRaw(promptName); + + // The guard should appear before the final "MUST call" line + const guardIndex = content.indexOf("ask_user_questions"); + const mustCallIndex = content.lastIndexOf("MUST call"); + + assert.ok( + guardIndex !== -1 && mustCallIndex !== -1 && guardIndex < mustCallIndex, + `${promptName}.md: autonomous guard (ask_user_questions prohibition) must appear before the final MUST call reminder`, + ); + } +}); diff --git a/src/resources/extensions/gsd/tests/auto-model-selection.test.ts b/src/resources/extensions/gsd/tests/auto-model-selection.test.ts index 2bc41fa9e..1551888d4 100644 --- a/src/resources/extensions/gsd/tests/auto-model-selection.test.ts +++ b/src/resources/extensions/gsd/tests/auto-model-selection.test.ts @@ -1,10 +1,13 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; -import { join } from "node:path"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; -import { resolvePreferredModelConfig } from "../auto-model-selection.js"; +const __dirname = dirname(fileURLToPath(import.meta.url)); + +import { resolvePreferredModelConfig, resolveModelId } from "../auto-model-selection.js"; function makeTempDir(prefix: string): string { return mkdtempSync(join(tmpdir(), prefix)); @@ -137,3 +140,115 @@ test("resolvePreferredModelConfig keeps explicit phase models as the ceiling", ( rmSync(tempGsdHome, { recursive: true, force: true }); } }); + +// ─── resolveModelId tests ───────────────────────────────────────────────── + +test("resolveModelId: bare ID resolves to claude-code when session is claude-code (#3772)", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "anthropic" }, + { id: "claude-sonnet-4-6", provider: "claude-code" }, + ]; + + // When currentProvider is "claude-code" (set by startup migration for subscription + // users), bare IDs must resolve to claude-code to avoid the third-party block (#3772). + const result = resolveModelId("claude-sonnet-4-6", availableModels, "claude-code"); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "claude-code", "bare ID must resolve to claude-code when session provider is claude-code"); +}); + +test("resolveModelId: bare ID still prefers current provider when it is a first-class API provider", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "anthropic" }, + { id: "claude-sonnet-4-6", provider: "bedrock" }, + ]; + + const result = resolveModelId("claude-sonnet-4-6", availableModels, "bedrock"); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "bedrock", "bare ID should prefer current provider when it is a real API provider"); +}); + +test("resolveModelId: explicit provider/model format still resolves to claude-code when specified", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "anthropic" }, + { id: "claude-sonnet-4-6", provider: "claude-code" }, + ]; + + const result = resolveModelId("claude-code/claude-sonnet-4-6", availableModels, "anthropic"); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "claude-code", "explicit provider prefix must be respected"); +}); + +test("resolveModelId: bare ID with only one provider works normally", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "anthropic" }, + ]; + + const result = resolveModelId("claude-sonnet-4-6", availableModels, "anthropic"); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "anthropic"); +}); + +test("resolveModelId: bare ID with claude-code as only provider still resolves", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "claude-code" }, + ]; + + // If claude-code is the ONLY provider for this model, it should still resolve + const result = resolveModelId("claude-sonnet-4-6", availableModels, "claude-code"); + assert.ok(result, "should resolve even when only available via claude-code"); + assert.equal(result.provider, "claude-code"); +}); + +// ─── selectAndApplyModel verbose-gating tests ────────────────────────── + +test("model change notify in selectAndApplyModel is gated behind verbose flag", () => { + // The Model [phase] [tier] notification should only fire when verbose=true. + // The dashboard header already shows the active model, so the notification + // is redundant noise during auto-mode (#3719). + const gsdDir = join(__dirname, ".."); + const src = readFileSync(join(gsdDir, "auto-model-selection.ts"), "utf-8"); + + // Find the block where setModel succeeds (appliedModel = model) and + // verify notify is inside an `if (verbose)` guard. + const setModelBlock = src.match( + /const ok = await pi\.setModel\(model[\s\S]*?appliedModel = model;([\s\S]*?)break;/, + ); + assert.ok(setModelBlock, "should find the setModel success block"); + + const blockBody = setModelBlock![1]; + // The notify call must be inside an if (verbose) block + assert.ok( + blockBody.includes("if (verbose)"), + "Model change ctx.ui.notify must be gated behind if (verbose) to avoid auto-mode notification noise", + ); + assert.ok( + blockBody.includes("ctx.ui.notify"), + "notify call should still exist (just verbose-gated)", + ); +}); + +test("resolveModelId: anthropic wins over claude-code when session provider is not claude-code", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "claude-code" }, + { id: "claude-sonnet-4-6", provider: "anthropic" }, + ]; + + // When the session is NOT on claude-code, bare IDs should resolve to + // the canonical anthropic provider (original #2905 behavior preserved). + const result = resolveModelId("claude-sonnet-4-6", availableModels, undefined); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "anthropic", "anthropic must win when session is not claude-code"); +}); + +test("resolveModelId: claude-code wins when session is claude-code regardless of list order", () => { + const availableModels = [ + { id: "claude-sonnet-4-6", provider: "claude-code" }, + { id: "claude-sonnet-4-6", provider: "anthropic" }, + ]; + + // When session provider is claude-code (subscription user migration), it must + // win regardless of candidate ordering to avoid the third-party block (#3772). + const result = resolveModelId("claude-sonnet-4-6", availableModels, "claude-code"); + assert.ok(result, "should resolve a model"); + assert.equal(result.provider, "claude-code", "claude-code must win when it is the session provider"); +}); diff --git a/src/resources/extensions/gsd/tests/auto-project-root-env.test.ts b/src/resources/extensions/gsd/tests/auto-project-root-env.test.ts new file mode 100644 index 000000000..98f6a11e2 --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-project-root-env.test.ts @@ -0,0 +1,29 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const sourcePath = join(import.meta.dirname, "..", "auto.ts"); +const source = readFileSync(sourcePath, "utf-8"); + +test("auto-mode captures GSD_PROJECT_ROOT before entering the dispatch loop", () => { + const captureDeclIdx = source.indexOf("function captureProjectRootEnv(projectRoot: string): void {"); + assert.ok(captureDeclIdx > -1, "auto.ts should define captureProjectRootEnv()"); + + const resumeCallIdx = source.indexOf("captureProjectRootEnv(s.originalBasePath || s.basePath);"); + assert.ok(resumeCallIdx > -1, "auto.ts should capture GSD_PROJECT_ROOT before resume autoLoop"); + + const firstAutoLoopIdx = source.indexOf("await autoLoop(ctx, pi, s, buildLoopDeps());"); + assert.ok(firstAutoLoopIdx > -1, "auto.ts should invoke autoLoop()"); + assert.ok( + resumeCallIdx < firstAutoLoopIdx, + "auto.ts must set GSD_PROJECT_ROOT before the first autoLoop() call", + ); +}); + +test("auto-mode restores GSD_PROJECT_ROOT when execution stops or pauses", () => { + assert.match(source, /function restoreProjectRootEnv\(\): void \{/); + assert.match(source, /cleanupAfterLoopExit\(ctx: ExtensionContext\): void \{[\s\S]*restoreProjectRootEnv\(\);/); + assert.match(source, /export async function pauseAuto\([\s\S]*restoreProjectRootEnv\(\);/); + assert.match(source, /\} finally \{[\s\S]*restoreProjectRootEnv\(\);[\s\S]*s\.reset\(\);/); +}); diff --git a/src/resources/extensions/gsd/tests/auto-recovery.test.ts b/src/resources/extensions/gsd/tests/auto-recovery.test.ts new file mode 100644 index 000000000..37092d3df --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-recovery.test.ts @@ -0,0 +1,714 @@ +import test, { afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { verifyExpectedArtifact, hasImplementationArtifacts, resolveExpectedArtifactPath, diagnoseExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.ts"; +import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertGateRow } from "../gsd-db.ts"; +import { clearParseCache } from "../files.ts"; +import { parseRoadmap } from "../parsers-legacy.ts"; +import { invalidateAllCaches } from "../cache.ts"; +import { deriveState, invalidateStateCache } from "../state.ts"; + +const tmpDirs: string[] = []; + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-test-${randomUUID()}`); + // Create .gsd/milestones/M001/slices/S01/tasks/ structure + mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* */ } +} + +function makeTmpProject(): string { + const dir = mkdtempSync(join(tmpdir(), "auto-recovery-")); + mkdirSync(join(dir, ".gsd"), { recursive: true }); + openDatabase(join(dir, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Test Milestone", status: "active" }); + insertSlice({ + milestoneId: "M001", + id: "S01", + title: "Test Slice", + status: "pending", + risk: "low", + depends: [], + }); + insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" }); + tmpDirs.push(dir); + return dir; +} + +afterEach(() => { + closeDatabase(); + for (const dir of tmpDirs) { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Best-effort cleanup only. + } + } + tmpDirs.length = 0; +}); + +test("resolveExpectedArtifactPath returns correct path for execute-task", () => { + const base = makeTmpBase(); + try { + const result = resolveExpectedArtifactPath("execute-task", "M001/S01/T01", base); + assert.ok(result); + assert.ok(result!.includes("tasks")); + assert.ok(result!.includes("SUMMARY")); + } finally { + cleanup(base); + } +}); + +test("resolveExpectedArtifactPath returns correct path for complete-slice", () => { + const base = makeTmpBase(); + try { + const result = resolveExpectedArtifactPath("complete-slice", "M001/S01", base); + assert.ok(result); + assert.ok(result!.includes("SUMMARY")); + } finally { + cleanup(base); + } +}); + +test("resolveExpectedArtifactPath returns correct path for plan-slice", () => { + const base = makeTmpBase(); + try { + const result = resolveExpectedArtifactPath("plan-slice", "M001/S01", base); + assert.ok(result); + assert.ok(result!.includes("PLAN")); + } finally { + cleanup(base); + } +}); + +test("resolveExpectedArtifactPath returns null for unknown type", () => { + const base = makeTmpBase(); + try { + const result = resolveExpectedArtifactPath("unknown-type", "M001", base); + assert.equal(result, null); + } finally { + cleanup(base); + } +}); + +test("resolveExpectedArtifactPath returns correct path for all milestone-level types", () => { + const base = makeTmpBase(); + try { + const planResult = resolveExpectedArtifactPath("plan-milestone", "M001", base); + assert.ok(planResult); + assert.ok(planResult!.includes("ROADMAP")); + + const completeResult = resolveExpectedArtifactPath("complete-milestone", "M001", base); + assert.ok(completeResult); + assert.ok(completeResult!.includes("SUMMARY")); + } finally { + cleanup(base); + } +}); + +test("resolveExpectedArtifactPath returns correct path for all slice-level types", () => { + const base = makeTmpBase(); + try { + const researchResult = resolveExpectedArtifactPath("research-slice", "M001/S01", base); + assert.ok(researchResult); + assert.ok(researchResult!.includes("RESEARCH")); + + const assessResult = resolveExpectedArtifactPath("reassess-roadmap", "M001/S01", base); + assert.ok(assessResult); + assert.ok(assessResult!.includes("ASSESSMENT")); + + const uatResult = resolveExpectedArtifactPath("run-uat", "M001/S01", base); + assert.ok(uatResult); + assert.ok(uatResult!.includes("ASSESSMENT")); + } finally { + cleanup(base); + } +}); + +// ─── diagnoseExpectedArtifact ───────────────────────────────────────────── + +test("diagnoseExpectedArtifact returns description for known types", () => { + const base = makeTmpBase(); + try { + const research = diagnoseExpectedArtifact("research-milestone", "M001", base); + assert.ok(research); + assert.ok(research!.includes("research")); + + const plan = diagnoseExpectedArtifact("plan-slice", "M001/S01", base); + assert.ok(plan); + assert.ok(plan!.includes("plan")); + + const task = diagnoseExpectedArtifact("execute-task", "M001/S01/T01", base); + assert.ok(task); + assert.ok(task!.includes("T01")); + } finally { + cleanup(base); + } +}); + +test("diagnoseExpectedArtifact returns null for unknown type", () => { + const base = makeTmpBase(); + try { + assert.equal(diagnoseExpectedArtifact("unknown", "M001", base), null); + } finally { + cleanup(base); + } +}); + +// ─── buildLoopRemediationSteps ──────────────────────────────────────────── + +test("buildLoopRemediationSteps returns steps for execute-task", () => { + const base = makeTmpBase(); + try { + const steps = buildLoopRemediationSteps("execute-task", "M001/S01/T01", base); + assert.ok(steps); + assert.ok(steps!.includes("T01")); + assert.ok(steps!.includes("gsd undo-task")); + } finally { + cleanup(base); + } +}); + +test("buildLoopRemediationSteps returns steps for plan-slice", () => { + const base = makeTmpBase(); + try { + const steps = buildLoopRemediationSteps("plan-slice", "M001/S01", base); + assert.ok(steps); + assert.ok(steps!.includes("PLAN")); + assert.ok(steps!.includes("gsd recover")); + } finally { + cleanup(base); + } +}); + +test("buildLoopRemediationSteps returns steps for complete-slice", () => { + const base = makeTmpBase(); + try { + const steps = buildLoopRemediationSteps("complete-slice", "M001/S01", base); + assert.ok(steps); + assert.ok(steps!.includes("S01")); + assert.ok(steps!.includes("gsd reset-slice")); + } finally { + cleanup(base); + } +}); + +test("buildLoopRemediationSteps returns null for unknown type", () => { + const base = makeTmpBase(); + try { + assert.equal(buildLoopRemediationSteps("unknown", "M001", base), null); + } finally { + cleanup(base); + } +}); + +// ─── verifyExpectedArtifact: parse cache collision regression ───────────── + +test("verifyExpectedArtifact detects roadmap [x] change despite parse cache", () => { + // Regression test: cacheKey collision when [ ] → [x] doesn't change + // file length or first/last 100 chars. Without the fix, parseRoadmap + // returns stale cached data with done=false even though the file has [x]. + const base = makeTmpBase(); + try { + // Build a roadmap long enough that the [x] change is outside the first/last 100 chars + const padding = "A".repeat(200); + const roadmapBefore = [ + `# M001: Test Milestone ${padding}`, + "", + "## Slices", + "", + "- [ ] **S01: First slice** `risk:low`", + "", + `## Footer ${padding}`, + ].join("\n"); + const roadmapAfter = roadmapBefore.replace("- [ ] **S01:", "- [x] **S01:"); + + // Verify lengths are identical (the key collision condition) + assert.equal(roadmapBefore.length, roadmapAfter.length); + + // Populate parse cache with the pre-edit roadmap + const before = parseRoadmap(roadmapBefore); + const sliceBefore = before.slices.find(s => s.id === "S01"); + assert.ok(sliceBefore); + assert.equal(sliceBefore!.done, false); + + // Now write the post-edit roadmap to disk and create required artifacts + const roadmapPath = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"); + writeFileSync(roadmapPath, roadmapAfter); + const summaryPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"); + writeFileSync(summaryPath, "# Summary\nDone."); + const uatPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-UAT.md"); + writeFileSync(uatPath, "# UAT\nPassed."); + + // verifyExpectedArtifact should see the [x] despite the parse cache + // having the [ ] version. The fix clears the parse cache inside verify. + const verified = verifyExpectedArtifact("complete-slice", "M001/S01", base); + assert.equal(verified, true, "verifyExpectedArtifact should return true when roadmap has [x]"); + } finally { + clearParseCache(); + cleanup(base); + } +}); + +// ─── verifyExpectedArtifact: plan-slice empty scaffold regression (#699) ── + +test("verifyExpectedArtifact rejects plan-slice with empty scaffold", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(sliceDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01: Test Slice\n\n## Tasks\n\n"); + assert.strictEqual( + verifyExpectedArtifact("plan-slice", "M001/S01", base), + false, + "Empty scaffold should not be treated as completed artifact", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact accepts plan-slice with actual tasks", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(sliceDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "- [ ] **T01: Implement feature** `est:2h`", + "- [ ] **T02: Write tests** `est:1h`", + ].join("\n")); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan"); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan"); + assert.strictEqual( + verifyExpectedArtifact("plan-slice", "M001/S01", base), + true, + "Plan with task entries should be treated as completed artifact", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact accepts plan-slice with completed tasks", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(sliceDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "- [x] **T01: Implement feature** `est:2h`", + "- [ ] **T02: Write tests** `est:1h`", + ].join("\n")); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan"); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan"); + assert.strictEqual( + verifyExpectedArtifact("plan-slice", "M001/S01", base), + true, + "Plan with completed task entries should be treated as completed artifact", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact treats complete-slice as satisfied when summary, UAT, and roadmap checkbox exist", () => { + const base = makeTmpBase(); + try { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + const sliceDir = join(milestoneDir, "slices", "S01"); + mkdirSync(sliceDir, { recursive: true }); + writeFileSync(join(milestoneDir, "M001-ROADMAP.md"), [ + "# M001: Test Milestone", + "", + "## Slices", + "", + "- [x] **S01: First slice** `risk:low`", + "", + "## Boundary Map", + "", + "- S01 → terminal", + " - Produces: done", + " - Consumes: nothing", + ].join("\n")); + writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n"); + writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n"); + + assert.equal( + verifyExpectedArtifact("complete-slice", "M001/S01", base), + true, + "complete-slice should verify when expected artifact and state mutation are already satisfied", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact rejects complete-slice when roadmap checkbox is still unchecked", () => { + const base = makeTmpBase(); + try { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + const sliceDir = join(milestoneDir, "slices", "S01"); + mkdirSync(sliceDir, { recursive: true }); + writeFileSync(join(milestoneDir, "M001-ROADMAP.md"), [ + "# M001: Test Milestone", + "", + "## Slices", + "", + "- [ ] **S01: First slice** `risk:low`", + "", + "## Boundary Map", + "", + "- S01 → terminal", + " - Produces: done", + " - Consumes: nothing", + ].join("\n")); + writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n"); + writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n"); + + assert.equal( + verifyExpectedArtifact("complete-slice", "M001/S01", base), + false, + "complete-slice should remain unsatisfied when roadmap state still requires the unit to run", + ); + } finally { + cleanup(base); + } +}); + + +// ─── verifyExpectedArtifact: plan-slice task plan check (#739) ──────────── + +test("verifyExpectedArtifact plan-slice passes when all task plan files exist", () => { + const base = makeTmpBase(); + try { + const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"); + const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"); + const planContent = [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "- [ ] **T01: First task** `est:1h`", + "- [ ] **T02: Second task** `est:2h`", + ].join("\n"); + writeFileSync(planPath, planContent); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing."); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan\n\nDo the other thing."); + + const result = verifyExpectedArtifact("plan-slice", "M001/S01", base); + assert.equal(result, true, "should pass when all task plan files exist"); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact plan-slice fails when a task plan file is missing (#739)", () => { + const base = makeTmpBase(); + try { + const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"); + const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"); + const planContent = [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "- [ ] **T01: First task** `est:1h`", + "- [ ] **T02: Second task** `est:2h`", + ].join("\n"); + writeFileSync(planPath, planContent); + // Only write T01-PLAN.md — T02 is missing + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n\nDo the thing."); + + const result = verifyExpectedArtifact("plan-slice", "M001/S01", base); + assert.equal(result, false, "should fail when T02-PLAN.md is missing"); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact plan-slice fails for plan with no tasks (#699)", () => { + const base = makeTmpBase(); + try { + const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"); + const planContent = [ + "# S01: Test Slice", + "", + "## Goal", + "", + "Just some documentation updates, no tasks.", + ].join("\n"); + writeFileSync(planPath, planContent); + + const result = verifyExpectedArtifact("plan-slice", "M001/S01", base); + assert.equal(result, false, "should fail when plan has no task entries (empty scaffold, #699)"); + } finally { + cleanup(base); + } +}); + +// ─── verifyExpectedArtifact: heading-style plan tasks (#1691) ───────────── + +test("verifyExpectedArtifact accepts plan-slice with heading-style tasks (### T01 --)", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(sliceDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "### T01 -- Implement feature", + "", + "Feature description.", + "", + "### T02 -- Write tests", + "", + "Test description.", + ].join("\n")); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan"); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan"); + assert.strictEqual( + verifyExpectedArtifact("plan-slice", "M001/S01", base), + true, + "Heading-style plan with task entries should be treated as completed artifact", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact accepts plan-slice with colon-style heading tasks (### T01:)", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(sliceDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "### T01: Implement feature", + "", + "Feature description.", + ].join("\n")); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan"); + assert.strictEqual( + verifyExpectedArtifact("plan-slice", "M001/S01", base), + true, + "Colon heading-style plan should be treated as completed artifact", + ); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact execute-task requires checked checkbox or DB status for heading-style plan entry (#1691, #3607)", () => { + const base = makeTmpBase(); + try { + const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(sliceDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-PLAN.md"), [ + "# S01: Test Slice", + "", + "## Tasks", + "", + "### T01 -- Implement feature", + "", + "Feature description.", + ].join("\n")); + writeFileSync(join(tasksDir, "T01-SUMMARY.md"), "# T01 Summary\n\nDone."); + // Without DB or checked checkbox, heading-style plans cannot verify + // execute-task completion (summary file alone is insufficient, #3607) + assert.strictEqual( + verifyExpectedArtifact("execute-task", "M001/S01/T01", base), + false, + "execute-task requires DB status or checked checkbox, not just heading + summary (#3607)", + ); + } finally { + cleanup(base); + } +}); + +// ─── #793: invalidateAllCaches unblocks skip-loop ───────────────────────── +// When the skip-loop breaker fires, it must call invalidateAllCaches() (not +// just invalidateStateCache()) to clear path/parse caches that deriveState +// depends on. Without this, even after cache invalidation, deriveState reads +// stale directory listings and returns the same unit, looping forever. +test("#793: invalidateAllCaches clears all caches so deriveState sees fresh disk state", async () => { + const base = makeTmpBase(); + try { + const mid = "M001"; + const sid = "S01"; + const planDir = join(base, ".gsd", "milestones", mid, "slices", sid); + const tasksDir = join(planDir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + mkdirSync(join(base, ".gsd", "milestones", mid), { recursive: true }); + + writeFileSync( + join(base, ".gsd", "milestones", mid, `${mid}-ROADMAP.md`), + `# M001: Test Milestone\n\n**Vision:** test.\n\n## Slices\n\n- [ ] **${sid}: Slice One** \`risk:low\` \`depends:[]\`\n > After this: done.\n`, + ); + const planUnchecked = `# ${sid}: Slice One\n\n**Goal:** test.\n\n## Tasks\n\n- [ ] **T01: Task One** \`est:10m\`\n- [ ] **T02: Task Two** \`est:10m\`\n`; + writeFileSync(join(planDir, `${sid}-PLAN.md`), planUnchecked); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01: Task One\n\n**Goal:** t\n\n## Steps\n- step\n\n## Verification\n- v\n"); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02: Task Two\n\n**Goal:** t\n\n## Steps\n- step\n\n## Verification\n- v\n"); + + // Warm all caches + const state1 = await deriveState(base); + assert.equal(state1.activeTask?.id, "T01", "initial: T01 is active"); + + // Simulate task completion on disk (what the LLM does) + const planChecked = `# ${sid}: Slice One\n\n**Goal:** test.\n\n## Tasks\n\n- [x] **T01: Task One** \`est:10m\`\n- [ ] **T02: Task Two** \`est:10m\`\n`; + writeFileSync(join(planDir, `${sid}-PLAN.md`), planChecked); + writeFileSync(join(tasksDir, "T01-SUMMARY.md"), "---\nid: T01\n---\n# Summary\n"); + + // invalidateStateCache alone: _stateCache cleared but path/parse caches warm + invalidateStateCache(); + + // invalidateAllCaches: all caches cleared — deriveState must re-read disk + invalidateAllCaches(); + const state2 = await deriveState(base); + + // After full invalidation, T01 should be complete and T02 should be next + assert.notEqual(state2.activeTask?.id, "T01", "#793: T01 not re-dispatched after full invalidation"); + + // Verify the caches are truly cleared by calling clearParseCache and clearPathCache + // do not throw (they should be no-ops after invalidateAllCaches already cleared them) + clearParseCache(); // no-op, but should not throw + assert.ok(true, "clearParseCache after invalidateAllCaches is safe"); + } finally { + cleanup(base); + } +}); + +// ─── hasImplementationArtifacts (#1703) ─────────────────────────────────── + +import { execFileSync } from "node:child_process"; + +function makeGitBase(): string { + const base = join(tmpdir(), `gsd-test-git-${randomUUID()}`); + mkdirSync(base, { recursive: true }); + execFileSync("git", ["init", "--initial-branch=main"], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["config", "user.email", "test@test.com"], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["config", "user.name", "Test"], { cwd: base, stdio: "ignore" }); + // Create initial commit so HEAD exists + writeFileSync(join(base, ".gitkeep"), ""); + execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["commit", "-m", "initial"], { cwd: base, stdio: "ignore" }); + return base; +} + +test("hasImplementationArtifacts returns false when only .gsd/ files committed (#1703)", () => { + const base = makeGitBase(); + try { + // Create a feature branch and commit only .gsd/ files + execFileSync("git", ["checkout", "-b", "feat/test-milestone"], { cwd: base, stdio: "ignore" }); + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), "# Roadmap"); + writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Summary"); + execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["commit", "-m", "chore: add plan files"], { cwd: base, stdio: "ignore" }); + + const result = hasImplementationArtifacts(base); + assert.equal(result, "absent", "should return absent when only .gsd/ files were committed"); + } finally { + cleanup(base); + } +}); + +test("hasImplementationArtifacts returns true when implementation files committed (#1703)", () => { + const base = makeGitBase(); + try { + // Create a feature branch with both .gsd/ and implementation files + execFileSync("git", ["checkout", "-b", "feat/test-impl"], { cwd: base, stdio: "ignore" }); + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), "# Roadmap"); + mkdirSync(join(base, "src"), { recursive: true }); + writeFileSync(join(base, "src", "feature.ts"), "export function feature() {}"); + execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["commit", "-m", "feat: add feature"], { cwd: base, stdio: "ignore" }); + + const result = hasImplementationArtifacts(base); + assert.equal(result, "present", "should return present when implementation files are present"); + } finally { + cleanup(base); + } +}); + +test("hasImplementationArtifacts returns true on non-git directory (fail-open)", () => { + const base = join(tmpdir(), `gsd-test-nogit-${randomUUID()}`); + mkdirSync(base, { recursive: true }); + try { + const result = hasImplementationArtifacts(base); + assert.equal(result, "unknown", "should return unknown (fail-open) in non-git directory"); + } finally { + cleanup(base); + } +}); + +// ─── verifyExpectedArtifact: complete-milestone requires impl artifacts (#1703) ── + +test("verifyExpectedArtifact complete-milestone fails with only .gsd/ files (#1703)", () => { + const base = makeGitBase(); + try { + // Create feature branch with only .gsd/ files + execFileSync("git", ["checkout", "-b", "feat/ms-only-gsd"], { cwd: base, stdio: "ignore" }); + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nDone."); + execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["commit", "-m", "chore: milestone plan files"], { cwd: base, stdio: "ignore" }); + + const result = verifyExpectedArtifact("complete-milestone", "M001", base); + assert.equal(result, false, "complete-milestone should fail verification when only .gsd/ files present"); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact complete-milestone passes with impl files (#1703)", () => { + const base = makeGitBase(); + try { + // Create feature branch with implementation files AND milestone summary + execFileSync("git", ["checkout", "-b", "feat/ms-with-impl"], { cwd: base, stdio: "ignore" }); + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), "# Milestone Summary\nDone."); + mkdirSync(join(base, "src"), { recursive: true }); + writeFileSync(join(base, "src", "app.ts"), "console.log('hello');"); + execFileSync("git", ["add", "."], { cwd: base, stdio: "ignore" }); + execFileSync("git", ["commit", "-m", "feat: implementation"], { cwd: base, stdio: "ignore" }); + + const result = verifyExpectedArtifact("complete-milestone", "M001", base); + assert.equal(result, true, "complete-milestone should pass verification with implementation files"); + } finally { + cleanup(base); + } +}); + +test("verifyExpectedArtifact checks pending gate-evaluate artifacts without ESM require failures", () => { + const base = makeTmpProject(); + + const verified = verifyExpectedArtifact("gate-evaluate", "M001/S01/gates+Q3", base); + + assert.equal(verified, false, "pending gates should keep gate-evaluate unverified"); +}); diff --git a/src/resources/extensions/gsd/tests/auto-remediate-slice-status.test.ts b/src/resources/extensions/gsd/tests/auto-remediate-slice-status.test.ts new file mode 100644 index 000000000..552096d00 --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-remediate-slice-status.test.ts @@ -0,0 +1,56 @@ +/** + * Regression test for #3673 — auto-remediate stale slice DB status + * + * When complete-slice fails after writing SUMMARY.md but before calling + * updateSliceStatus(), the DB stays stale and the post-unit check + * previously reported this as a "rogue" artifact, causing infinite + * re-dispatch. The fix calls updateSliceStatus() to sync the DB. + * + * This structural test verifies updateSliceStatus is imported and called + * in the complete-slice branch of auto-post-unit.ts. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'auto-post-unit.ts'), 'utf-8'); + +describe('auto-remediate stale slice status (#3673)', () => { + test('updateSliceStatus is imported from gsd-db', () => { + assert.match(source, /import\s*\{[^}]*updateSliceStatus[^}]*\}\s*from\s*["']\.\/gsd-db/, + 'updateSliceStatus should be imported from gsd-db'); + }); + + test('updateSliceStatus is called with "complete" status', () => { + assert.match(source, /updateSliceStatus\(mid,\s*sid,\s*["']complete["']/, + 'updateSliceStatus should be called with "complete" status'); + }); + + test('remediation is wrapped in try-catch for fallback to rogue detection', () => { + // The updateSliceStatus call should be in a try block with a catch + // that falls back to rogues.push + const updateIdx = source.indexOf('updateSliceStatus(mid, sid'); + assert.ok(updateIdx > 0, 'updateSliceStatus call should exist'); + + // Find surrounding try-catch + const before = source.slice(Math.max(0, updateIdx - 200), updateIdx); + assert.match(before, /try\s*\{/, + 'updateSliceStatus should be inside a try block'); + + const after = source.slice(updateIdx, updateIdx + 300); + assert.match(after, /catch/, + 'try block should have a catch for fallback'); + }); + + test('rogue detection still exists as fallback', () => { + // rogues.push should appear in the catch block + assert.match(source, /rogues\.push\(\{.*path:\s*summaryPath/, + 'rogues.push fallback should still exist'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts b/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts index 3daa00f3f..2ffb5bf96 100644 --- a/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts +++ b/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts @@ -7,8 +7,10 @@ const sourcePath = join(import.meta.dirname, "..", "auto-start.ts"); const source = readFileSync(sourcePath, "utf-8"); test("bootstrapAutoSession snapshots ctx.model before guided-flow entry (#2829)", () => { - const snapshotIdx = source.indexOf("const startModelSnapshot = ctx.model"); - assert.ok(snapshotIdx > -1, "auto-start.ts should snapshot ctx.model at bootstrap start"); + // #3517 changed the snapshot to prefer GSD preferences, but the ordering + // guarantee still holds: the snapshot must be built before guided-flow. + const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel"); + assert.ok(snapshotIdx > -1, "auto-start.ts should snapshot model at bootstrap start"); const firstDiscussIdx = source.indexOf('await showSmartEntry(ctx, pi, base, { step: requestedStepMode });'); assert.ok(firstDiscussIdx > -1, "auto-start.ts should route through showSmartEntry during guided flow"); @@ -26,3 +28,21 @@ test("bootstrapAutoSession restores autoModeStartModel from the early snapshot ( const snapshotRefIdx = source.indexOf("provider: startModelSnapshot.provider", assignmentIdx); assert.ok(snapshotRefIdx > -1, "autoModeStartModel should be restored from startModelSnapshot"); }); + +test("bootstrapAutoSession prefers GSD PREFERENCES.md over settings.json for start model (#3517)", () => { + // resolveDefaultSessionModel() should be called before the snapshot is built + const preferredIdx = source.indexOf("const preferredModel = resolveDefaultSessionModel("); + assert.ok(preferredIdx > -1, "auto-start.ts should call resolveDefaultSessionModel()"); + + // Session provider should be passed for bare model ID resolution + const withProviderIdx = source.indexOf("resolveDefaultSessionModel(ctx.model?.provider)"); + assert.ok(withProviderIdx > -1, "auto-start.ts should pass ctx.model?.provider for bare ID resolution"); + + const snapshotIdx = source.indexOf("const startModelSnapshot = preferredModel"); + assert.ok(snapshotIdx > -1, "startModelSnapshot should use preferredModel when available"); + + assert.ok( + preferredIdx < snapshotIdx, + "resolveDefaultSessionModel() must be called before building startModelSnapshot", + ); +}); diff --git a/src/resources/extensions/gsd/tests/auto-start-time-persistence.test.ts b/src/resources/extensions/gsd/tests/auto-start-time-persistence.test.ts new file mode 100644 index 000000000..174a9b651 --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-start-time-persistence.test.ts @@ -0,0 +1,50 @@ +// GSD2 — Verify autoStartTime is persisted in paused-session.json and restored on resume +// Copyright (c) 2026 Jeremy McSpadden + +/** + * auto-start-time-persistence.test.ts — Ensures autoStartTime survives + * cross-session resume via paused-session.json (#3585). + * + * Source-code regression guards: verify auto.ts saves and restores + * autoStartTime so the elapsed timer doesn't vanish after /exit + resume. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const AUTO_TS_PATH = join(__dirname, "..", "auto.ts"); + +const source = readFileSync(AUTO_TS_PATH, "utf-8"); + +test("pauseAuto persists autoStartTime in paused-session.json (#3585)", () => { + assert.ok( + source.includes("autoStartTime: s.autoStartTime"), + "pausedMeta must include autoStartTime so the timer survives /exit", + ); +}); + +test("cross-session resume restores autoStartTime from paused-session.json (#3585)", () => { + const matches = source.match(/s\.autoStartTime\s*=\s*meta\.autoStartTime/g); + assert.ok( + matches && matches.length >= 2, + "both resume paths (custom workflow + milestone) must restore autoStartTime from meta", + ); +}); + +test("resume path falls back to Date.now() when autoStartTime is missing (#3585)", () => { + assert.ok( + source.includes("meta.autoStartTime || Date.now()"), + "restore should fall back to Date.now() for old paused-session files without autoStartTime", + ); +}); + +test("resume path guards against zero autoStartTime (#3585)", () => { + assert.ok( + source.includes("if (!s.autoStartTime || s.autoStartTime <= 0) s.autoStartTime = Date.now()"), + "resume path must set autoStartTime to Date.now() if still zero after restore", + ); +}); diff --git a/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts b/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts new file mode 100644 index 000000000..f32bf41fb --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-start-worktree-db-path.test.ts @@ -0,0 +1,28 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +import { createTestContext } from "./test-helpers.ts"; + +const { assertTrue, report } = createTestContext(); + +const srcPath = join(import.meta.dirname, "..", "auto-start.ts"); +const src = readFileSync(srcPath, "utf-8"); + +console.log("\n=== #3822: worktree bootstrap uses project DB path ==="); + +const dbLifecycleIdx = src.indexOf("// ── DB lifecycle ──"); +assertTrue(dbLifecycleIdx > 0, "auto-start.ts has a DB lifecycle section"); + +const dbLifecycleRegion = dbLifecycleIdx > 0 ? src.slice(dbLifecycleIdx, dbLifecycleIdx + 600) : ""; + +assertTrue( + dbLifecycleRegion.includes("const gsdDbPath = resolveProjectRootDbPath(s.basePath);"), + "DB lifecycle resolves the project-root DB path after worktree entry (#3822)", +); + +assertTrue( + !dbLifecycleRegion.includes('join(s.basePath, ".gsd", "gsd.db")'), + "DB lifecycle no longer derives gsd.db directly from the worktree path (#3822)", +); + +report(); diff --git a/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts b/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts new file mode 100644 index 000000000..5ad5311b2 --- /dev/null +++ b/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts @@ -0,0 +1,107 @@ +// GSD-2 — Regression tests for #3512: gsd-auto-wrapup mid-turn interruption +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const autoTimersPath = join(import.meta.dirname, "..", "auto-timers.ts"); +const autoTimersSrc = readFileSync(autoTimersPath, "utf-8"); + +const autoPath = join(import.meta.dirname, "..", "auto.ts"); +const autoSrc = readFileSync(autoPath, "utf-8"); + +const runUnitPath = join(import.meta.dirname, "..", "auto", "run-unit.ts"); +const runUnitSrc = readFileSync(runUnitPath, "utf-8"); + +describe("#3512: gsd-auto-wrapup must not interrupt in-flight tool calls", () => { + test("soft timeout wrapup gates triggerTurn on getInFlightToolCount() === 0", () => { + // The soft timeout sendMessage must NOT use a hardcoded `triggerTurn: true`. + // It must check getInFlightToolCount() before deciding whether to trigger. + // Use the section marker comment to isolate the soft timeout block. + const startMarker = "── 1. Soft timeout warning"; + const endMarker = "── 2. Idle watchdog"; + const softTimeoutSection = autoTimersSrc.slice( + autoTimersSrc.indexOf(startMarker), + autoTimersSrc.indexOf(endMarker), + ); + assert.ok( + softTimeoutSection.length > 0, + "Could not locate soft timeout section", + ); + + // Must reference getInFlightToolCount to gate the trigger + assert.ok( + softTimeoutSection.includes("getInFlightToolCount"), + "Soft timeout wrapup must gate triggerTurn behind getInFlightToolCount() check", + ); + + // Must NOT have a hardcoded triggerTurn: true + assert.ok( + !softTimeoutSection.includes("triggerTurn: true"), + "Soft timeout wrapup must not use hardcoded triggerTurn: true", + ); + }); + + test("context-pressure wrapup gates triggerTurn on getInFlightToolCount() === 0", () => { + // The context budget sendMessage must NOT use a hardcoded `triggerTurn: true`. + // Use the section marker to isolate the context-pressure block. + const startMarker = "── 4. Context-pressure continue-here monitor"; + const contextSection = autoTimersSrc.slice( + autoTimersSrc.indexOf(startMarker), + ); + assert.ok( + contextSection.length > 0, + "Could not locate context budget section", + ); + + // Must reference getInFlightToolCount to gate the trigger + assert.ok( + contextSection.includes("getInFlightToolCount"), + "Context budget wrapup must gate triggerTurn behind getInFlightToolCount() check", + ); + + // Must NOT have a hardcoded triggerTurn: true + assert.ok( + !contextSection.includes("triggerTurn: true"), + "Context budget wrapup must not use hardcoded triggerTurn: true", + ); + }); +}); + +describe("#3512: pauseAuto and stopAuto must flush queued follow-up messages", () => { + test("stopAuto calls clearQueue()", () => { + // stopAuto must flush queued messages to prevent late async_job_result + // notifications from triggering extra LLM turns after stop. + const stopAutoSection = autoSrc.slice( + autoSrc.indexOf("export async function stopAuto("), + autoSrc.indexOf("export async function pauseAuto("), + ); + assert.ok(stopAutoSection, "Could not locate stopAuto function"); + assert.ok( + stopAutoSection.includes("clearQueue"), + "stopAuto must call clearQueue() to flush queued follow-up messages", + ); + }); + + test("pauseAuto calls clearQueue()", () => { + // pauseAuto must also flush queued messages — same issue as stopAuto. + const pauseAutoSection = autoSrc.slice( + autoSrc.indexOf("export async function pauseAuto("), + ); + assert.ok(pauseAutoSection, "Could not locate pauseAuto function"); + assert.ok( + pauseAutoSection.includes("clearQueue"), + "pauseAuto must call clearQueue() to flush queued follow-up messages", + ); + }); + + test("run-unit.ts still has its existing clearQueue() call (baseline)", () => { + // Verify the original clearQueue pattern in run-unit.ts hasn't been removed. + assert.ok( + runUnitSrc.includes("clearQueue"), + "run-unit.ts must retain its clearQueue() call after unit completion", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts b/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts new file mode 100644 index 000000000..5c2d18cfc --- /dev/null +++ b/src/resources/extensions/gsd/tests/bootstrap-derive-state-db-open.test.ts @@ -0,0 +1,39 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const systemContextSrc = readFileSync( + join(import.meta.dirname, "..", "bootstrap", "system-context.ts"), + "utf-8", +); +const registerHooksSrc = readFileSync( + join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts"), + "utf-8", +); + +describe("bootstrap deriveState DB guards (#3844)", () => { + test("system-context opens DB before deriveState in resume flows", () => { + const helperIdx = systemContextSrc.indexOf("const ensureStateDbOpen = async () => {"); + const firstDeriveIdx = systemContextSrc.indexOf("const state = await deriveState(basePath);"); + assert.ok(helperIdx > -1, "system-context should define a DB-open helper for deriveState callers"); + assert.ok(firstDeriveIdx > -1, "system-context should still derive state for resume flows"); + assert.ok(helperIdx < firstDeriveIdx, "system-context should prepare DB opening before deriveState resume calls"); + assert.match( + systemContextSrc, + /await ensureStateDbOpen\(\);\s*\n\s*const state = await deriveState\(basePath\);/g, + "system-context resume flows should open DB before deriveState", + ); + }); + + test("register-hooks opens DB before deriveState in session_before_compact", () => { + const compactIdx = registerHooksSrc.indexOf('pi.on("session_before_compact"'); + assert.ok(compactIdx > -1, "register-hooks should define session_before_compact"); + const compactSection = registerHooksSrc.slice(compactIdx, compactIdx + 1600); + const ensureIdx = compactSection.indexOf("ensureDbOpen()"); + const deriveIdx = compactSection.indexOf("deriveState(basePath)"); + assert.ok(ensureIdx > -1, "session_before_compact should call ensureDbOpen()"); + assert.ok(deriveIdx > -1, "session_before_compact should derive state"); + assert.ok(ensureIdx < deriveIdx, "session_before_compact should open DB before deriveState"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/capability-router.test.ts b/src/resources/extensions/gsd/tests/capability-router.test.ts new file mode 100644 index 000000000..8e185b508 --- /dev/null +++ b/src/resources/extensions/gsd/tests/capability-router.test.ts @@ -0,0 +1,371 @@ +// GSD Extension — Capability-Aware Router Tests +// Tests for new capability scoring functions and data tables (Plan 01-01) + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; + +import { + scoreModel, + computeTaskRequirements, + scoreEligibleModels, + getEligibleModels, + resolveModelForComplexity, + MODEL_CAPABILITY_PROFILES, + MODEL_CAPABILITY_TIER, + BASE_REQUIREMENTS, + defaultRoutingConfig, +} from "../model-router.js"; +import type { ModelCapabilities, DynamicRoutingConfig, RoutingDecision } from "../model-router.js"; + +// ─── scoreModel ────────────────────────────────────────────────────────────── + +describe("scoreModel", () => { + const sonnetProfile: ModelCapabilities = { + coding: 85, debugging: 80, research: 75, reasoning: 80, + speed: 60, longContext: 75, instruction: 85, + }; + + test("produces correct weighted average for single dimension", () => { + // Only coding weight 1.0 → result should be the coding score + const score = scoreModel(sonnetProfile, { coding: 1.0 }); + assert.equal(score, 85); + }); + + test("produces correct weighted average for two dimensions (coding 0.9, instruction 0.7)", () => { + // (0.9*85 + 0.7*85) / (0.9+0.7) = (76.5+59.5)/1.6 = 136/1.6 = 85.0 + const score = scoreModel(sonnetProfile, { coding: 0.9, instruction: 0.7 }); + assert.ok(Math.abs(score - 85.0) < 0.01, `Expected ~85.0, got ${score}`); + }); + + test("returns 50 when requirements is empty", () => { + const score = scoreModel(sonnetProfile, {}); + assert.equal(score, 50); + }); + + test("uses 50 as fallback for unknown dimension in requirements", () => { + // 'unknown' dimension not in profile → treated as 50 + const score = scoreModel(sonnetProfile, { coding: 0.5, unknown: 1.0 } as any); + // (0.5*85 + 1.0*50) / (0.5+1.0) = (42.5+50)/1.5 = 92.5/1.5 = 61.67 + assert.ok(score > 61 && score < 62, `Expected ~61.67, got ${score}`); + }); +}); + +// ─── computeTaskRequirements ───────────────────────────────────────────────── + +describe("computeTaskRequirements", () => { + test("execute-task with no metadata returns base requirements", () => { + const req = computeTaskRequirements("execute-task", undefined); + assert.deepStrictEqual(req, { coding: 0.9, instruction: 0.7, speed: 0.3 }); + }); + + test("execute-task with docs tag returns docs-adjusted requirements", () => { + const req = computeTaskRequirements("execute-task", { tags: ["docs"] }); + assert.equal(req.instruction, 0.9); + assert.equal(req.coding, 0.3); + assert.equal(req.speed, 0.7); + }); + + test("execute-task with readme tag returns docs-adjusted requirements", () => { + const req = computeTaskRequirements("execute-task", { tags: ["readme"] }); + assert.equal(req.instruction, 0.9); + }); + + test("execute-task with concurrency keyword boosts debugging and reasoning", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["concurrency"] }); + assert.equal(req.debugging, 0.9); + assert.equal(req.reasoning, 0.8); + }); + + test("execute-task with compatibility keyword boosts debugging and reasoning", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["compatibility"] }); + assert.equal(req.debugging, 0.9); + assert.equal(req.reasoning, 0.8); + }); + + test("execute-task with migration keyword boosts reasoning and coding", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["migration"] }); + assert.equal(req.reasoning, 0.9); + assert.equal(req.coding, 0.8); + }); + + test("execute-task with architecture keyword boosts reasoning and coding", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["architecture"] }); + assert.equal(req.reasoning, 0.9); + assert.equal(req.coding, 0.8); + }); + + test("execute-task with fileCount >= 6 boosts coding and reasoning", () => { + const req = computeTaskRequirements("execute-task", { fileCount: 8 }); + assert.equal(req.coding, 0.9); + assert.equal(req.reasoning, 0.7); + }); + + test("execute-task with fileCount exactly 6 triggers large-file boost", () => { + const req = computeTaskRequirements("execute-task", { fileCount: 6 }); + assert.equal(req.coding, 0.9); + assert.equal(req.reasoning, 0.7); + }); + + test("execute-task with estimatedLines >= 500 boosts coding and reasoning", () => { + const req = computeTaskRequirements("execute-task", { estimatedLines: 500 }); + assert.equal(req.coding, 0.9); + assert.equal(req.reasoning, 0.7); + }); + + test("research-milestone with no metadata returns base requirements", () => { + const req = computeTaskRequirements("research-milestone", undefined); + assert.deepStrictEqual(req, { research: 0.9, longContext: 0.7, reasoning: 0.5 }); + }); + + test("unknown unit type returns default reasoning requirement", () => { + const req = computeTaskRequirements("unknown-type", undefined); + assert.deepStrictEqual(req, { reasoning: 0.5 }); + }); +}); + +// ─── MODEL_CAPABILITY_PROFILES ─────────────────────────────────────────────── + +describe("MODEL_CAPABILITY_PROFILES", () => { + test("contains profiles for all tier-mapped models", () => { + const tierModels = Object.keys(MODEL_CAPABILITY_TIER); + for (const model of tierModels) { + assert.ok(MODEL_CAPABILITY_PROFILES[model], `Missing profile for ${model}`); + } + }); + + test("each profile has all 7 capability dimensions", () => { + const dims: Array = [ + "coding", "debugging", "research", "reasoning", + "speed", "longContext", "instruction", + ]; + for (const [modelId, profile] of Object.entries(MODEL_CAPABILITY_PROFILES)) { + for (const dim of dims) { + assert.ok(profile[dim] !== undefined, `${modelId} missing dimension ${dim}`); + assert.ok(profile[dim] >= 0 && profile[dim] <= 100, `${modelId}.${dim} out of range`); + } + } + }); + + test("claude-opus-4-6 has high reasoning and coding", () => { + const opus = MODEL_CAPABILITY_PROFILES["claude-opus-4-6"]; + assert.ok(opus.reasoning >= 90, `Expected reasoning >= 90, got ${opus.reasoning}`); + assert.ok(opus.coding >= 90, `Expected coding >= 90, got ${opus.coding}`); + }); + + test("claude-haiku-4-5 has high speed but lower reasoning", () => { + const haiku = MODEL_CAPABILITY_PROFILES["claude-haiku-4-5"]; + assert.ok(haiku.speed >= 90, `Expected speed >= 90, got ${haiku.speed}`); + assert.ok(haiku.reasoning < 70, `Expected reasoning < 70, got ${haiku.reasoning}`); + }); +}); + +// ─── BASE_REQUIREMENTS ─────────────────────────────────────────────────────── + +describe("BASE_REQUIREMENTS", () => { + test("contains all 11 unit types", () => { + const required = [ + "execute-task", "research-milestone", "research-slice", + "plan-milestone", "plan-slice", "replan-slice", + "reassess-roadmap", "complete-slice", "run-uat", + "discuss-milestone", "complete-milestone", + ]; + for (const unitType of required) { + assert.ok(BASE_REQUIREMENTS[unitType], `Missing requirements for ${unitType}`); + } + }); +}); + +// ─── scoreEligibleModels ───────────────────────────────────────────────────── + +describe("scoreEligibleModels", () => { + test("returns array sorted by score descending", () => { + const requirements = { research: 0.9, longContext: 0.7, reasoning: 0.5 }; + const results = scoreEligibleModels(["claude-sonnet-4-6", "gpt-4o"], requirements); + assert.ok(results.length === 2); + assert.ok(results[0].score >= results[1].score, "Should be sorted descending by score"); + }); + + test("returns single model when only one eligible", () => { + const requirements = { coding: 0.9 }; + const results = scoreEligibleModels(["claude-sonnet-4-6"], requirements); + assert.equal(results.length, 1); + assert.equal(results[0].modelId, "claude-sonnet-4-6"); + }); + + test("models without profiles get uniform 50s score", () => { + const requirements = { coding: 1.0 }; + const results = scoreEligibleModels(["unknown-model-xyz"], requirements); + assert.equal(results[0].score, 50); + }); + + test("when two models score within 2 points, prefers cheaper model", () => { + // gemini-2.0-flash is cheaper than gpt-4o-mini ($0.0001 vs $0.00015) + // Use a requirement that causes similar scores for both + const requirements = { speed: 1.0 }; + const results = scoreEligibleModels(["gpt-4o-mini", "gemini-2.0-flash"], requirements); + // Both are high-speed: gpt-4o-mini=90, gemini-2.0-flash=95 — scores differ by 5, not within 2 + // So top should be gemini-2.0-flash by score + assert.equal(results[0].modelId, "gemini-2.0-flash"); + }); + + test("tie-breaks by lexicographic model ID when cost and score are equal", () => { + // Use models without cost entries — both get Infinity cost + const requirements = { coding: 1.0 }; + const results = scoreEligibleModels(["model-z", "model-a"], requirements); + // Both unknown → score=50, cost=Infinity → tiebreak by ID + assert.equal(results[0].modelId, "model-a"); + }); + + test("scoreEligibleModels respects capabilityOverrides", () => { + const requirements = { coding: 1.0 }; + // Override claude-sonnet-4-6's coding to 30 (worse) + const results = scoreEligibleModels( + ["claude-sonnet-4-6", "gpt-4o"], + requirements, + { "claude-sonnet-4-6": { coding: 30 } }, + ); + // gpt-4o coding=80 should beat overridden sonnet coding=30 + assert.equal(results[0].modelId, "gpt-4o"); + }); +}); + +// ─── getEligibleModels ─────────────────────────────────────────────────────── + +describe("getEligibleModels", () => { + const MODELS = [ + "claude-opus-4-6", // heavy + "claude-sonnet-4-6", // standard + "claude-haiku-4-5", // light + "gpt-4o-mini", // light + ]; + + test("returns light-tier models sorted by cost when no explicit config", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + const result = getEligibleModels("light", MODELS, config); + assert.ok(result.length >= 1); + // All results should be light-tier + for (const id of result) { + assert.ok( + ["claude-haiku-4-5", "gpt-4o-mini"].includes(id), + `Expected light-tier model, got ${id}`, + ); + } + }); + + test("returns explicit tier_models when configured and available", () => { + const config: DynamicRoutingConfig = { + ...defaultRoutingConfig(), + tier_models: { light: "gpt-4o-mini" }, + }; + const result = getEligibleModels("light", MODELS, config); + assert.deepStrictEqual(result, ["gpt-4o-mini"]); + }); + + test("returns empty array when no eligible models for tier", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + // Only heavy model available, requesting light + const result = getEligibleModels("light", ["claude-opus-4-6"], config); + assert.equal(result.length, 0); + }); +}); + +// ─── DynamicRoutingConfig extension ───────────────────────────────────────── + +describe("DynamicRoutingConfig.capability_routing", () => { + test("defaultRoutingConfig includes capability_routing: true", () => { + const config = defaultRoutingConfig(); + assert.equal(config.capability_routing, true); + }); +}); + +// ─── RoutingDecision.selectionMethod ───────────────────────────────────────── + +describe("RoutingDecision.selectionMethod", () => { + const MODELS = ["claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5", "gpt-4o-mini"]; + + function makeClassification(tier: "light" | "standard" | "heavy") { + return { tier, reason: "test", downgraded: false }; + } + + test("returns selectionMethod: tier-only when routing is disabled", () => { + const config = { ...defaultRoutingConfig(), enabled: false }; + const result: RoutingDecision = resolveModelForComplexity( + makeClassification("light"), + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MODELS, + ); + assert.equal(result.selectionMethod, "tier-only"); + }); + + test("returns selectionMethod: tier-only for no phase config passthrough", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const result: RoutingDecision = resolveModelForComplexity( + makeClassification("light"), + undefined, + config, + MODELS, + ); + assert.equal(result.selectionMethod, "tier-only"); + }); + + test("returns selectionMethod: tier-only for unknown model passthrough", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const result: RoutingDecision = resolveModelForComplexity( + makeClassification("light"), + { primary: "custom-provider/my-model-v3", fallbacks: [] }, + config, + ["custom-provider/my-model-v3", ...MODELS], + ); + assert.equal(result.selectionMethod, "tier-only"); + }); + + test("returns selectionMethod: tier-only for no-downgrade passthrough", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const result: RoutingDecision = resolveModelForComplexity( + makeClassification("heavy"), + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MODELS, + ); + assert.equal(result.selectionMethod, "tier-only"); + }); + + test("returns selectionMethod: tier-only when downgraded", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const result: RoutingDecision = resolveModelForComplexity( + makeClassification("light"), + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MODELS, + ); + assert.equal(result.selectionMethod, "tier-only"); + }); +}); + +// ─── ADR-004: Profile Completeness Lint ───────────────────────────────────── +// Every model in MODEL_CAPABILITY_TIER must have an entry in +// MODEL_CAPABILITY_PROFILES. This prevents profile staleness as new models +// are added to the tier map without corresponding capability data. + +describe("profile completeness (ADR-004 lint)", () => { + test("every model in MODEL_CAPABILITY_TIER has a MODEL_CAPABILITY_PROFILES entry", () => { + const tierModels = Object.keys(MODEL_CAPABILITY_TIER); + const missing = tierModels.filter(id => !MODEL_CAPABILITY_PROFILES[id]); + assert.equal( + missing.length, + 0, + `Models in MODEL_CAPABILITY_TIER but missing from MODEL_CAPABILITY_PROFILES:\n ${missing.join("\n ")}\n\nAdd capability profiles for these models in model-router.ts.`, + ); + }); + + test("MODEL_CAPABILITY_PROFILES does not contain models absent from MODEL_CAPABILITY_TIER", () => { + const profileModels = Object.keys(MODEL_CAPABILITY_PROFILES); + const orphaned = profileModels.filter(id => !MODEL_CAPABILITY_TIER[id]); + assert.equal( + orphaned.length, + 0, + `Models in MODEL_CAPABILITY_PROFILES but not in MODEL_CAPABILITY_TIER:\n ${orphaned.join("\n ")}\n\nEither add these to MODEL_CAPABILITY_TIER or remove stale profiles.`, + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/captures.test.ts b/src/resources/extensions/gsd/tests/captures.test.ts index 2e6618604..e8497e6fc 100644 --- a/src/resources/extensions/gsd/tests/captures.test.ts +++ b/src/resources/extensions/gsd/tests/captures.test.ts @@ -19,8 +19,11 @@ import { appendCapture, loadAllCaptures, loadPendingCaptures, + loadActionableCaptures, hasPendingCaptures, markCaptureResolved, + markCaptureExecuted, + stampCaptureMilestone, resolveCapturesPath, parseTriageOutput, } from "../captures.ts"; @@ -419,3 +422,103 @@ test("triage: parseTriageOutput preserves affectedFiles and targetSlice", () => assert.strictEqual(results[1].targetSlice, "S04"); assert.strictEqual(results[1].affectedFiles, undefined); }); + +// ─── Stale Quick-Task Captures (#2872) ──────────────────────────────────────── + +test("captures: markCaptureResolved stores milestone ID when provided", (t) => { + const tmp = makeTempDir("cap-milestone"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + const id = appendCapture(tmp, "fix dialog width"); + markCaptureResolved(tmp, id, "quick-task", "widen the dialog", "small fix", "M003"); + + const all = loadAllCaptures(tmp); + assert.strictEqual(all.length, 1); + assert.strictEqual(all[0].resolvedInMilestone, "M003", "should store milestone ID"); +}); + +test("captures: loadActionableCaptures excludes captures resolved in prior milestones", (t) => { + const tmp = makeTempDir("cap-stale-filter"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + // Capture resolved in M003 (prior milestone) + const id1 = appendCapture(tmp, "dialog too narrow"); + markCaptureResolved(tmp, id1, "quick-task", "widen it", "small fix", "M003"); + + // Capture resolved in M004 (current milestone) + const id2 = appendCapture(tmp, "button misaligned"); + markCaptureResolved(tmp, id2, "quick-task", "fix alignment", "css fix", "M004"); + + // Capture resolved without milestone context (legacy) + const id3 = appendCapture(tmp, "typo in label"); + markCaptureResolved(tmp, id3, "quick-task", "fix typo", "trivial"); + + // When loading for M004, only M004 and no-milestone captures should be returned + const actionable = loadActionableCaptures(tmp, "M004"); + const ids = actionable.map(c => c.id); + + assert.ok(!ids.includes(id1), "should exclude capture resolved in M003"); + assert.ok(ids.includes(id2), "should include capture resolved in M004"); + assert.ok(ids.includes(id3), "should include capture with no milestone (legacy)"); +}); + +test("captures: loadActionableCaptures without milestone returns all actionable", (t) => { + const tmp = makeTempDir("cap-no-milestone-filter"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + const id1 = appendCapture(tmp, "issue one"); + markCaptureResolved(tmp, id1, "quick-task", "fix it", "small", "M003"); + + const id2 = appendCapture(tmp, "issue two"); + markCaptureResolved(tmp, id2, "inject", "inject it", "needed", "M004"); + + // Without milestone filter, all actionable captures are returned (backward compat) + const actionable = loadActionableCaptures(tmp); + assert.strictEqual(actionable.length, 2, "should return all actionable without filter"); +}); + +test("captures: loadActionableCaptures excludes already-executed captures", (t) => { + const tmp = makeTempDir("cap-executed-filter"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + const id1 = appendCapture(tmp, "already done"); + markCaptureResolved(tmp, id1, "quick-task", "fix it", "small", "M004"); + markCaptureExecuted(tmp, id1); + + const id2 = appendCapture(tmp, "still pending"); + markCaptureResolved(tmp, id2, "quick-task", "fix it too", "small", "M004"); + + const actionable = loadActionableCaptures(tmp, "M004"); + assert.strictEqual(actionable.length, 1, "should exclude executed capture"); + assert.strictEqual(actionable[0].id, id2); +}); + +test("captures: stampCaptureMilestone adds milestone to capture missing it", (t) => { + const tmp = makeTempDir("cap-stamp-milestone"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + const id = appendCapture(tmp, "fix alignment"); + markCaptureResolved(tmp, id, "quick-task", "fix it", "small"); + + // Before stamping, no milestone + let all = loadAllCaptures(tmp); + assert.strictEqual(all[0].resolvedInMilestone, undefined, "should have no milestone initially"); + + stampCaptureMilestone(tmp, id, "M004"); + + all = loadAllCaptures(tmp); + assert.strictEqual(all[0].resolvedInMilestone, "M004", "should have milestone after stamping"); +}); + +test("captures: stampCaptureMilestone is no-op if milestone already present", (t) => { + const tmp = makeTempDir("cap-stamp-noop"); + t.after(() => rmSync(tmp, { recursive: true, force: true })); + + const id = appendCapture(tmp, "fix alignment"); + markCaptureResolved(tmp, id, "quick-task", "fix it", "small", "M003"); + + stampCaptureMilestone(tmp, id, "M004"); + + const all = loadAllCaptures(tmp); + assert.strictEqual(all[0].resolvedInMilestone, "M003", "should keep original milestone"); +}); diff --git a/src/resources/extensions/gsd/tests/claude-skill-dirs.test.ts b/src/resources/extensions/gsd/tests/claude-skill-dirs.test.ts new file mode 100644 index 000000000..90e6aa5be --- /dev/null +++ b/src/resources/extensions/gsd/tests/claude-skill-dirs.test.ts @@ -0,0 +1,51 @@ +/** + * Tests for Claude Code skill directory support in getSkillSearchDirs(). + * + * Verifies that ~/.claude/skills/ and .claude/skills/ are included in + * the skill search path alongside ~/.agents/skills/ and .agents/skills/. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { join } from "node:path"; +import { homedir } from "node:os"; +import { getSkillSearchDirs } from "../preferences-skills.ts"; + +describe("getSkillSearchDirs — Claude Code directory support", () => { + const cwd = "/tmp/test-project"; + + test("includes ~/.agents/skills/ as user-skill", () => { + const dirs = getSkillSearchDirs(cwd); + const agents = dirs.find((d) => d.dir === join(homedir(), ".agents", "skills")); + assert.ok(agents, "should include ~/.agents/skills/"); + assert.equal(agents!.method, "user-skill"); + }); + + test("includes .agents/skills/ as project-skill", () => { + const dirs = getSkillSearchDirs(cwd); + const projectAgents = dirs.find((d) => d.dir === join(cwd, ".agents", "skills")); + assert.ok(projectAgents, "should include .agents/skills/"); + assert.equal(projectAgents!.method, "project-skill"); + }); + + test("includes ~/.claude/skills/ as user-skill", () => { + const dirs = getSkillSearchDirs(cwd); + const claude = dirs.find((d) => d.dir === join(homedir(), ".claude", "skills")); + assert.ok(claude, "should include ~/.claude/skills/"); + assert.equal(claude!.method, "user-skill"); + }); + + test("includes .claude/skills/ as project-skill", () => { + const dirs = getSkillSearchDirs(cwd); + const projectClaude = dirs.find((d) => d.dir === join(cwd, ".claude", "skills")); + assert.ok(projectClaude, "should include .claude/skills/"); + assert.equal(projectClaude!.method, "project-skill"); + }); + + test("~/.agents/skills/ appears before ~/.claude/skills/ (priority order)", () => { + const dirs = getSkillSearchDirs(cwd); + const agentsIdx = dirs.findIndex((d) => d.dir === join(homedir(), ".agents", "skills")); + const claudeIdx = dirs.findIndex((d) => d.dir === join(homedir(), ".claude", "skills")); + assert.ok(agentsIdx < claudeIdx, "~/.agents/skills/ should have higher priority than ~/.claude/skills/"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/clear-stale-autostart.test.ts b/src/resources/extensions/gsd/tests/clear-stale-autostart.test.ts new file mode 100644 index 000000000..c5452e6a6 --- /dev/null +++ b/src/resources/extensions/gsd/tests/clear-stale-autostart.test.ts @@ -0,0 +1,41 @@ +/** + * clear-stale-autostart.test.ts — #3667 + * + * Verify that guided-flow.ts adds a createdAt timestamp to pending auto-start + * entries and implements a staleness check (30s age guard) so that /clear + * interrupted discussions don't permanently block future /gsd invocations. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const sourceFile = join(__dirname, "..", "guided-flow.ts"); + +describe("clear stale pending auto-start (#3667)", () => { + const source = readFileSync(sourceFile, "utf-8"); + + test("PendingAutoStartEntry interface includes createdAt field", () => { + assert.match(source, /createdAt:\s*number/); + }); + + test("setPendingAutoStart defaults createdAt to Date.now()", () => { + assert.match(source, /createdAt:\s*Date\.now\(\)/); + }); + + test("staleness check uses 30_000ms threshold", () => { + assert.match(source, /30[_]?000/); + }); + + test("stale entry detection checks manifest and context files", () => { + assert.match(source, /DISCUSSION-MANIFEST\.json/); + assert.match(source, /CONTEXT\.md/); + }); + + test("stale entries are deleted from the map", () => { + assert.match(source, /pendingAutoStartMap\.delete\(basePath\)/); + }); +}); diff --git a/src/resources/extensions/gsd/tests/cli-provider-rate-limit.test.ts b/src/resources/extensions/gsd/tests/cli-provider-rate-limit.test.ts new file mode 100644 index 000000000..cd79cf9a2 --- /dev/null +++ b/src/resources/extensions/gsd/tests/cli-provider-rate-limit.test.ts @@ -0,0 +1,47 @@ +/** + * cli-provider-rate-limit.test.ts — Verify rate-limit backoff capping + * for CLI-style providers (openai-codex, google-gemini-cli). (#2922) + * + * These providers use per-user quotas with shorter windows, so the + * default 60s backoff should be capped at 30s to avoid leaving users + * stuck in an apparent permanent "rate limit" state. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const RECOVERY_PATH = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"); + +function getRecoverySource(): string { + return readFileSync(RECOVERY_PATH, "utf-8"); +} + +test("agent-end-recovery references openai-codex for rate-limit handling (#2922)", () => { + const src = getRecoverySource(); + assert.ok( + src.includes("openai-codex"), + 'agent-end-recovery.ts must reference "openai-codex" for CLI provider rate-limit handling (#2922)', + ); +}); + +test("agent-end-recovery references google-gemini-cli for rate-limit handling (#2922)", () => { + const src = getRecoverySource(); + assert.ok( + src.includes("google-gemini-cli"), + 'agent-end-recovery.ts must reference "google-gemini-cli" for CLI provider rate-limit handling (#2922)', + ); +}); + +test("agent-end-recovery caps rate-limit backoff for CLI providers (#2922)", () => { + const src = getRecoverySource(); + // Must have a Math.min capping pattern for CLI provider rate-limit backoff + const cappingRe = /Math\.min\s*\(/; + assert.ok( + cappingRe.test(src), + 'agent-end-recovery.ts must cap rate-limit backoff with Math.min for CLI providers (#2922)', + ); +}); diff --git a/src/resources/extensions/gsd/tests/cmux.test.ts b/src/resources/extensions/gsd/tests/cmux.test.ts index f25953542..305a3ef0d 100644 --- a/src/resources/extensions/gsd/tests/cmux.test.ts +++ b/src/resources/extensions/gsd/tests/cmux.test.ts @@ -1,7 +1,8 @@ -import test, { describe } from "node:test"; +import test, { describe, beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; import * as fs from "node:fs"; import * as path from "node:path"; +import { tmpdir } from "node:os"; import { fileURLToPath } from "node:url"; import { buildCmuxProgress, @@ -12,6 +13,7 @@ import { resolveCmuxConfig, shouldPromptToEnableCmux, } from "../../cmux/index.ts"; +import { autoEnableCmuxPreferences } from "../commands-cmux.ts"; import type { GSDState } from "../types.ts"; test("detectCmuxEnvironment requires workspace, surface, and socket", () => { @@ -79,6 +81,70 @@ test("shouldPromptToEnableCmux only prompts once per session", () => { resetCmuxPromptState(); }); +describe("autoEnableCmuxPreferences", () => { + let tmp: string; + let originalCwd: string; + + beforeEach(() => { + originalCwd = process.cwd(); + tmp = fs.mkdtempSync(path.join(tmpdir(), "cmux-auto-test-")); + fs.mkdirSync(path.join(tmp, ".gsd"), { recursive: true }); + process.chdir(tmp); + }); + + afterEach(() => { + process.chdir(originalCwd); + fs.rmSync(tmp, { recursive: true, force: true }); + }); + + test("writes cmux.enabled true when preferences file exists with no cmux config", () => { + const prefsPath = path.join(tmp, ".gsd", "preferences.md"); + fs.writeFileSync(prefsPath, [ + "---", + "version: 1", + "---", + "", + "# GSD Skill Preferences", + ].join("\n")); + + const result = autoEnableCmuxPreferences(); + assert.equal(result, true); + + const content = fs.readFileSync(prefsPath, "utf-8"); + assert.ok(content.includes("enabled: true"), "should write enabled: true"); + assert.ok(content.includes("notifications: true"), "should default notifications on"); + assert.ok(content.includes("sidebar: true"), "should default sidebar on"); + assert.ok(content.includes("splits: false"), "should default splits off"); + }); + + test("returns false when preferences file does not exist", () => { + const result = autoEnableCmuxPreferences(); + assert.equal(result, false); + }); + + test("preserves existing cmux sub-preferences when auto-enabling", () => { + const prefsPath = path.join(tmp, ".gsd", "preferences.md"); + fs.writeFileSync(prefsPath, [ + "---", + "version: 1", + "cmux:", + " splits: true", + " browser: true", + "---", + "", + "# GSD Skill Preferences", + ].join("\n")); + + const result = autoEnableCmuxPreferences(); + assert.equal(result, true); + + const content = fs.readFileSync(prefsPath, "utf-8"); + assert.ok(content.includes("enabled: true"), "should set enabled: true"); + assert.ok(content.includes("splits: true"), "should preserve existing splits: true"); + assert.ok(content.includes("browser: true"), "should preserve existing browser: true"); + }); +}); + test("buildCmuxStatusLabel and progress prefer deepest active unit", () => { const state: GSDState = { activeMilestone: { id: "M001", title: "Milestone" }, @@ -193,6 +259,64 @@ describe("createGridLayout", () => { }); }); +describe("CmuxClient stdio isolation", () => { + test("runSync and runAsync explicitly set stdio to prevent terminal interference", () => { + // Read the cmux index source and verify that execFileSync/spawn calls + // inside runSync/runAsync include stdio options that isolate stdin and stderr. + // This prevents the cmux CLI child process from inheriting the parent's + // stdin/stderr, which can steal keyboard input or corrupt TUI rendering (#1922). + const cmuxIndexPath = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "../../cmux/index.ts", + ); + const source = fs.readFileSync(cmuxIndexPath, "utf-8"); + + // Extract runSync method body + const runSyncMatch = source.match(/private runSync\(args: string\[\]\)[^{]*\{([\s\S]*?)\n \}/); + assert.ok(runSyncMatch, "runSync method must exist"); + const runSyncBody = runSyncMatch[1]; + assert.ok( + runSyncBody.includes('stdio:'), + "runSync must explicitly set stdio to prevent terminal interference (see #1922)", + ); + assert.ok( + runSyncBody.includes('"ignore"'), + "runSync stdio must ignore stdin to prevent stealing keyboard input from TUI", + ); + + // Extract runAsync method body + const runAsyncMatch = source.match(/private async runAsync\(args: string\[\]\)[^{]*\{([\s\S]*?)\n \}/); + assert.ok(runAsyncMatch, "runAsync method must exist"); + const runAsyncBody = runAsyncMatch[1]; + assert.ok( + runAsyncBody.includes('stdio:'), + "runAsync must explicitly set stdio to prevent terminal interference (see #1922)", + ); + assert.ok( + runAsyncBody.includes('"ignore"'), + "runAsync stdio must ignore stdin to prevent stealing keyboard input from TUI", + ); + }); + + test("isCmuxCliAvailable uses stdio ignore to prevent terminal interference", () => { + const cmuxIndexPath = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "../../cmux/index.ts", + ); + const source = fs.readFileSync(cmuxIndexPath, "utf-8"); + + // Find isCmuxCliAvailable or the cli-check function body + const fnMatch = source.match(/function isCmuxCliAvailable[\s\S]*?\{([\s\S]*?)\n\}/); + if (!fnMatch) return; // function may be inlined or renamed — skip rather than fail + + const fnBody = fnMatch[1]; + assert.ok( + fnBody.includes('"ignore"') || !fnBody.includes('execFileSync'), + "isCmuxCliAvailable must not inherit parent stdio (see #1922)", + ); + }); +}); + describe("cmux extension discovery opt-out", () => { test("cmux directory has package.json with pi manifest to prevent auto-discovery as extension", () => { const cmuxDir = path.resolve( diff --git a/src/resources/extensions/gsd/tests/codebase-generator.test.ts b/src/resources/extensions/gsd/tests/codebase-generator.test.ts new file mode 100644 index 000000000..923c19f1d --- /dev/null +++ b/src/resources/extensions/gsd/tests/codebase-generator.test.ts @@ -0,0 +1,669 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; +import { execSync } from "node:child_process"; + +import { + parseCodebaseMap, + parseCodebaseMapMetadata, + generateCodebaseMap, + updateCodebaseMap, + writeCodebaseMap, + readCodebaseMap, + getCodebaseMapStats, + ensureCodebaseMapFresh, +} from "../codebase-generator.ts"; + +// ─── Helpers ────────────────────────────────────────────────────────────── + +function makeTmpRepo(): string { + const base = join(tmpdir(), `gsd-codebase-test-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + execSync("git init", { cwd: base, stdio: "ignore" }); + return base; +} + +function addFile(base: string, path: string, content = ""): void { + const fullPath = join(base, path); + mkdirSync(join(fullPath, ".."), { recursive: true }); + writeFileSync(fullPath, content || `// ${path}\n`, "utf-8"); + execSync(`git add "${path}"`, { cwd: base, stdio: "ignore" }); +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* */ } +} + +// ─── parseCodebaseMap ──────────────────────────────────────────────────── + +test("parseCodebaseMap: parses file with description", () => { + const content = `# Codebase Map + +### src/ +- \`main.ts\` — Application entry point +- \`utils.ts\` — Shared utilities +`; + + const map = parseCodebaseMap(content); + assert.equal(map.size, 2); + assert.equal(map.get("main.ts"), "Application entry point"); + assert.equal(map.get("utils.ts"), "Shared utilities"); +}); + +test("parseCodebaseMap: parses file without description", () => { + const content = `- \`config.ts\`\n- \`index.ts\` — Entry\n`; + const map = parseCodebaseMap(content); + assert.equal(map.size, 2); + assert.equal(map.get("config.ts"), ""); + assert.equal(map.get("index.ts"), "Entry"); +}); + +test("parseCodebaseMap: empty content returns empty map", () => { + const map = parseCodebaseMap(""); + assert.equal(map.size, 0); +}); + +test("parseCodebaseMap: ignores non-matching lines", () => { + const content = `# Codebase Map\n\nGenerated: 2026-03-23\n\n### src/\n- \`file.ts\` — desc\n`; + const map = parseCodebaseMap(content); + assert.equal(map.size, 1); +}); + +test("parseCodebaseMap: recovers descriptions from collapsed-description comments", () => { + const content = `# Codebase Map + +### src/components/ +- *(25 files: 25 .ts)* + +`; + const map = parseCodebaseMap(content); + assert.equal(map.get("src/components/Foo.ts"), "The Foo component"); + assert.equal(map.get("src/components/Bar.ts"), "The Bar component"); + // The collapsed summary line itself should not be parsed as a file + assert.ok(!map.has("*(25 files: 25 .ts)*")); +}); + +test("parseCodebaseMap: handles corrupted/malformed input gracefully", () => { + const content = [ + "- `unclosed backtick", + "- `` — empty filename", + "- `valid.ts` — ok", + "random garbage line", + "- `a.ts` — desc with other text", + ].join("\n"); + const map = parseCodebaseMap(content); + assert.ok(map.has("valid.ts")); + assert.ok(map.has("a.ts")); + // Malformed lines should be silently skipped + assert.equal(map.size, 2); +}); + +// ─── generateCodebaseMap ───────────────────────────────────────────────── + +test("generateCodebaseMap: generates from git ls-files", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, "src/utils.ts"); + addFile(base, "README.md"); + + const result = generateCodebaseMap(base); + assert.ok(result.content.includes("# Codebase Map")); + assert.ok(result.content.includes("`src/main.ts`")); + assert.ok(result.content.includes("`src/utils.ts`")); + assert.ok(result.content.includes("README.md")); + assert.equal(result.fileCount, 3); + assert.equal(result.truncated, false); + assert.equal(result.files.length, 3); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: excludes .gsd/ files", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, ".gsd/PROJECT.md"); + + const result = generateCodebaseMap(base); + assert.ok(result.content.includes("`src/main.ts`")); + assert.ok(!result.content.includes("PROJECT.md")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: excludes .claude/ and other tool directories", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, ".claude/CLAUDE.md"); + addFile(base, ".claude/memory/user.md"); + addFile(base, ".plans/plan.md"); + addFile(base, ".cursor/settings.json"); + addFile(base, ".vscode/settings.json"); + + const result = generateCodebaseMap(base); + assert.ok(result.content.includes("`src/main.ts`"), "should include src/main.ts"); + assert.ok(!result.content.includes("CLAUDE.md"), "should exclude .claude/ files"); + assert.ok(!result.content.includes("user.md"), "should exclude .claude/memory/ files"); + assert.ok(!result.content.includes(".plans"), "should exclude .plans/ files"); + assert.ok(!result.content.includes(".cursor"), "should exclude .cursor/ files"); + assert.ok(!result.content.includes(".vscode"), "should exclude .vscode/ files"); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: excludes .agents/ and other tooling directories", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, ".agents/skills/pdf/SKILL.md"); + addFile(base, ".agents/skills/find-skills/SKILL.md"); + addFile(base, ".bg-shell/session.json"); + addFile(base, ".idea/workspace.xml"); + addFile(base, ".cache/data.bin"); + addFile(base, "tmp/scratch.ts"); + addFile(base, "target/debug/build.rs"); + addFile(base, "venv/lib/site.py"); + + const result = generateCodebaseMap(base); + assert.ok(result.content.includes("`src/main.ts`"), "should include src/main.ts"); + assert.ok(!result.content.includes("SKILL.md"), "should exclude .agents/ files"); + assert.ok(!result.content.includes(".bg-shell"), "should exclude .bg-shell/ files"); + assert.ok(!result.content.includes(".idea"), "should exclude .idea/ files"); + assert.ok(!result.content.includes(".cache"), "should exclude .cache/ files"); + assert.ok(!result.content.includes("tmp/"), "should exclude tmp/ files"); + assert.ok(!result.content.includes("target"), "should exclude target/ files"); + assert.ok(!result.content.includes("venv"), "should exclude venv/ files"); + assert.equal(result.fileCount, 1); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: excludes binary and lock files", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, "package-lock.json"); // .json not excluded + addFile(base, "yarn.lock"); // .lock excluded + addFile(base, "assets/logo.png"); // .png excluded + + const result = generateCodebaseMap(base); + assert.ok(result.content.includes("`src/main.ts`")); + assert.ok(result.content.includes("package-lock.json")); + assert.ok(!result.content.includes("yarn.lock")); + assert.ok(!result.content.includes("logo.png")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: respects custom excludePatterns", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, "docs/guide.md"); + addFile(base, "docs/api.md"); + + const result = generateCodebaseMap(base, { excludePatterns: ["docs/"] }); + assert.ok(result.content.includes("`src/main.ts`")); + assert.ok(!result.content.includes("guide.md")); + assert.ok(!result.content.includes("api.md")); + assert.equal(result.fileCount, 1); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: preserves existing descriptions", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + addFile(base, "src/utils.ts"); + + const descriptions = new Map(); + descriptions.set("src/main.ts", "App entry point"); + + const result = generateCodebaseMap(base, undefined, descriptions); + assert.ok(result.content.includes("`src/main.ts` — App entry point")); + assert.ok(result.content.includes("`src/utils.ts`")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: writes freshness metadata comment", () => { + const base = makeTmpRepo(); + try { + addFile(base, "src/main.ts"); + + const result = generateCodebaseMap(base); + const metadata = parseCodebaseMapMetadata(result.content); + + assert.ok(metadata, "metadata comment should be present"); + assert.equal(metadata?.fileCount, 1); + assert.equal(metadata?.truncated, false); + assert.equal(typeof metadata?.fingerprint, "string"); + assert.ok(metadata?.generatedAt?.endsWith("Z")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: collapses large directories", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 25; i++) { + addFile(base, `src/components/comp${String(i).padStart(2, "0")}.ts`); + } + + const result = generateCodebaseMap(base); + // Collapsed summary should appear + assert.ok(result.content.includes("*(25 files: 25 .ts)*")); + // Individual file entries should NOT appear in main body + assert.ok(!result.content.includes("`src/components/comp00.ts`\n")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: respects custom collapseThreshold", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 5; i++) addFile(base, `src/comp${i}.ts`); + + // Low threshold: 5 files should collapse + const collapsed = generateCodebaseMap(base, { collapseThreshold: 3 }); + assert.ok(collapsed.content.includes("5 files")); + + // High threshold: 5 files should expand + const expanded = generateCodebaseMap(base, { collapseThreshold: 10 }); + assert.ok(expanded.content.includes("`src/comp0.ts`")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: truncated=false when file count is below maxFiles", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 4; i++) addFile(base, `file${i}.ts`); + const result = generateCodebaseMap(base, { maxFiles: 5 }); + assert.equal(result.fileCount, 4); + assert.equal(result.truncated, false); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: truncated=false when file count equals maxFiles exactly", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 5; i++) addFile(base, `file${i}.ts`); + const result = generateCodebaseMap(base, { maxFiles: 5 }); + assert.equal(result.fileCount, 5); + assert.equal(result.truncated, false); // exactly at limit — nothing was truncated + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: truncated=true when file count exceeds maxFiles", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 10; i++) addFile(base, `file${i}.ts`); + const result = generateCodebaseMap(base, { maxFiles: 5 }); + assert.equal(result.fileCount, 5); + assert.equal(result.truncated, true); + assert.ok(result.content.includes("Truncated")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: returns empty map for non-git directory", () => { + const base = join(tmpdir(), `gsd-codebase-test-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + // No git init + try { + const result = generateCodebaseMap(base); + assert.equal(result.fileCount, 0); + assert.equal(result.truncated, false); + assert.ok(result.content.includes("# Codebase Map")); + assert.equal(result.files.length, 0); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: handles empty repository (no committed files)", () => { + const base = makeTmpRepo(); + try { + const result = generateCodebaseMap(base); + assert.equal(result.fileCount, 0); + assert.equal(result.truncated, false); + assert.ok(result.content.includes("Files: 0")); + } finally { + cleanup(base); + } +}); + +test("generateCodebaseMap: collapsed directories preserve descriptions in hidden comment", () => { + const base = makeTmpRepo(); + try { + for (let i = 0; i < 25; i++) { + addFile(base, `src/components/comp${String(i).padStart(2, "0")}.ts`); + } + + // Generate with a description for one file in the collapsed dir + const descriptions = new Map([["src/components/comp00.ts", "The first component"]]); + const result = generateCodebaseMap(base, undefined, descriptions); + + // The description should be in the hidden comment block + assert.ok(result.content.includes("'; let promptResult: string | undefined; diff --git a/src/resources/extensions/gsd/tests/integration/state-machine-edge-cases.test.ts b/src/resources/extensions/gsd/tests/integration/state-machine-edge-cases.test.ts new file mode 100644 index 000000000..db7b992c8 --- /dev/null +++ b/src/resources/extensions/gsd/tests/integration/state-machine-edge-cases.test.ts @@ -0,0 +1,1190 @@ +/** + * state-machine-edge-cases.test.ts — Gap-filling tests for the GSD state + * machine covering failure modes, boundary conditions, and edge cases NOT + * covered by the existing state-machine-live-validation.test.ts suite. + * + * Coverage gaps filled: + * 1. State derivation failures (file deletion races, partial DB, cache staleness, + * corrupt files, 0-slice ROADMAP) + * 2. Transition boundary failures (mid-transition mutation, cascading blockers, + * multi-level milestone deps, blocked→unblocked recovery) + * 3. Dispatch failures (null activeSlice, evaluating-gates without config, + * unhandled phase, missing task plan recovery) + * 4. Completion & verification failures (unparseable verdict, needs-remediation + * blocks completion, missing SUMMARY blocks validation, UAT verdict gate, + * replan loop cap) + */ + +// GSD State Machine Edge Case Tests + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + readFileSync, + rmSync, + existsSync, + unlinkSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +// ── DB layer ────────────────────────────────────────────────────────────── +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, + getTask, + getSlice, + getMilestone, + getSliceTasks, + getMilestoneSlices, + updateTaskStatus, + updateSliceStatus, + updateMilestoneStatus, + insertReplanHistory, + getReplanHistory, + insertGateRow, + getPendingGates, +} from "../../gsd-db.ts"; + +// ── State derivation ────────────────────────────────────────────────────── +import { + deriveState, + deriveStateFromDb, + invalidateStateCache, + isGhostMilestone, + isValidationTerminal, +} from "../../state.ts"; + +// ── Status guards ───────────────────────────────────────────────────────── +import { isClosedStatus } from "../../status-guards.ts"; + +// ── Cache invalidation ─────────────────────────────────────────────────── +import { invalidateAllCaches } from "../../cache.ts"; + +// ── Dispatch ───────────────────────────────────────────────────────────── +import { + resolveDispatch, + DISPATCH_RULES, + getDispatchRuleNames, +} from "../../auto-dispatch.ts"; +import type { DispatchContext, DispatchAction } from "../../auto-dispatch.ts"; + +// ── Verdict parser ────────────────────────────────────────────────────── +import { + extractVerdict, + isAcceptableUatVerdict, + isValidMilestoneVerdict, +} from "../../verdict-parser.ts"; + +// ── Path helpers ───────────────────────────────────────────────────────── +import { clearPathCache } from "../../paths.ts"; + +// ═══════════════════════════════════════════════════════════════════════════ +// Fixture Helpers +// ═══════════════════════════════════════════════════════════════════════════ + +function makeTempDir(): string { + return mkdtempSync(join(tmpdir(), "gsd-edge-cases-")); +} + +/** + * Create a standard .gsd/ fixture with M001 containing S01 (2 tasks) and S02 (1 task). + * Same structure as state-machine-live-validation.test.ts for consistency. + */ +function createFullFixture(): string { + const base = makeTempDir(); + const gsdDir = join(base, ".gsd"); + const m001Dir = join(gsdDir, "milestones", "M001"); + const s01Dir = join(m001Dir, "slices", "S01"); + const s01Tasks = join(s01Dir, "tasks"); + const s02Dir = join(m001Dir, "slices", "S02"); + const s02Tasks = join(s02Dir, "tasks"); + + mkdirSync(s01Tasks, { recursive: true }); + mkdirSync(s02Tasks, { recursive: true }); + + writeFileSync( + join(m001Dir, "M001-CONTEXT.md"), + [ + "# M001: Edge Case Milestone", + "", + "## Purpose", + "Test state machine edge cases.", + ].join("\n"), + ); + + writeFileSync( + join(m001Dir, "M001-ROADMAP.md"), + [ + "# M001: Edge Case Milestone", + "", + "## Vision", + "Prove edge case correctness.", + "", + "## Success Criteria", + "- All edge cases handled", + "", + "## Slices", + "", + "- [ ] **S01: First Feature** `risk:low` `depends:[]`", + " - After this: First feature proven.", + "", + "- [ ] **S02: Second Feature** `risk:low` `depends:[]`", + " - After this: Second feature proven.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | terminal | feature-a | nothing |", + "| S02 | terminal | feature-b | nothing |", + ].join("\n"), + ); + + writeFileSync( + join(s01Dir, "S01-PLAN.md"), + [ + "# S01: First Feature", + "", + "**Goal:** Implement first feature.", + "", + "## Tasks", + "", + "- [ ] **T01: Implementation** `est:30m`", + " - Do: Build it", + " - Verify: Run tests", + "", + "- [ ] **T02: Testing** `est:30m`", + " - Do: Write tests", + " - Verify: Run tests", + ].join("\n"), + ); + + writeFileSync(join(s01Tasks, "T01-PLAN.md"), "# T01 Plan\nImplement.\n"); + writeFileSync(join(s01Tasks, "T02-PLAN.md"), "# T02 Plan\nTest.\n"); + + writeFileSync( + join(s02Dir, "S02-PLAN.md"), + [ + "# S02: Second Feature", + "", + "**Goal:** Implement second feature.", + "", + "## Tasks", + "", + "- [ ] **T01: Implementation** `est:30m`", + " - Do: Build it", + " - Verify: Run tests", + ].join("\n"), + ); + + writeFileSync(join(s02Tasks, "T01-PLAN.md"), "# T01 Plan\nBuild.\n"); + + return base; +} + +/** + * Create a multi-milestone fixture with M001 → M002 → M003 dependency chain. + */ +function createMultiMilestoneFixture(): string { + const base = makeTempDir(); + const gsdDir = join(base, ".gsd"); + + for (const mid of ["M001", "M002", "M003"]) { + const mDir = join(gsdDir, "milestones", mid); + const sDir = join(mDir, "slices", "S01", "tasks"); + mkdirSync(sDir, { recursive: true }); + + writeFileSync( + join(mDir, `${mid}-CONTEXT.md`), + `# ${mid}: Milestone ${mid.slice(-1)}\n\n## Purpose\nTest deps.\n`, + ); + + writeFileSync( + join(mDir, `${mid}-ROADMAP.md`), + [ + `# ${mid}: Milestone ${mid.slice(-1)}`, + "", + "## Vision", + "Test dependency chains.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "- [ ] **S01: Only Slice** `risk:low` `depends:[]`", + " - After this: Done.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | terminal | output | nothing |", + ].join("\n"), + ); + + writeFileSync( + join(mDir, "slices", "S01", "S01-PLAN.md"), + [ + "# S01: Only Slice", + "", + "**Goal:** Do the thing.", + "", + "## Tasks", + "", + "- [ ] **T01: Task** `est:30m`", + " - Do: Implement", + " - Verify: Run tests", + ].join("\n"), + ); + + writeFileSync(join(sDir, "T01-PLAN.md"), "# T01 Plan\nDo it.\n"); + } + + return base; +} + +function buildDispatchCtx( + base: string, + mid: string, + stateOverrides: Partial = {}, +): DispatchContext { + return { + basePath: base, + mid, + midTitle: `${mid} Test`, + state: { + activeMilestone: { id: mid, title: `${mid} Test` }, + activeSlice: null, + activeTask: null, + phase: "executing", + recentDecisions: [], + blockers: [], + nextAction: "", + registry: [], + requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 }, + progress: { milestones: { done: 0, total: 1 } }, + ...stateOverrides, + }, + prefs: undefined, + }; +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Test Suite +// ═══════════════════════════════════════════════════════════════════════════ + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 1: State Derivation Failure Modes +// ───────────────────────────────────────────────────────────────────────── + +describe("state derivation failures", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("file deleted between deriveState calls produces consistent result", async () => { + // Simulates race condition: PLAN file exists on first derive, deleted before second + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const stateBefore = await deriveStateFromDb(base); + assert.equal(stateBefore.phase, "executing"); + + // Delete the task plan file mid-flow + const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-PLAN.md"); + if (existsSync(planPath)) unlinkSync(planPath); + + invalidateAllCaches(); + const stateAfter = await deriveStateFromDb(base); + // State machine should still function — either executing (DB says task exists) + // or planning (missing plan file triggers replan). Should NOT throw. + assert.ok( + ["executing", "planning"].includes(stateAfter.phase), + `expected executing or planning after plan deletion, got: ${stateAfter.phase}`, + ); + }); + + test("partial DB write: milestone inserted but no slices → pre-planning", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Test\n\n## Purpose\nTest.\n"); + + openDatabase(join(base, ".gsd", "gsd.db")); + // Only insert milestone — no slices, no roadmap + insertMilestone({ id: "M001", title: "Partial", status: "active" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + // No roadmap → pre-planning (milestone exists but no structure yet) + assert.equal(state.phase, "pre-planning"); + assert.equal(state.activeMilestone?.id, "M001"); + }); + + test("cache staleness: derive within TTL returns same result after DB mutation", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // First call populates cache + invalidateStateCache(); + const state1 = await deriveState(base); + assert.equal(state1.phase, "executing"); + + // Mutate DB WITHOUT invalidating cache + updateTaskStatus("M001", "S01", "T01", "complete", new Date().toISOString()); + + // Second call within 100ms TTL should return cached (stale) result + const state2 = await deriveState(base); + assert.equal(state2.phase, "executing", "cached result should still show executing"); + + // After explicit invalidation, should reflect the DB mutation + invalidateStateCache(); + const state3 = await deriveState(base); + assert.equal(state3.phase, "summarizing", "after cache invalidation should show summarizing"); + }); + + test("corrupt ROADMAP: binary content does not crash deriveState", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Corrupt\n\n## Purpose\nTest.\n"); + // Write binary garbage as ROADMAP + writeFileSync(join(mDir, "M001-ROADMAP.md"), Buffer.from([0x00, 0xFF, 0xFE, 0x89, 0x50, 0x4E, 0x47])); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Corrupt", status: "active" }); + + invalidateAllCaches(); + // Should NOT throw — should degrade gracefully + const state = await deriveStateFromDb(base); + assert.ok(state.phase, "should produce a valid phase even with corrupt ROADMAP"); + }); + + test("0-byte ROADMAP file is treated as no roadmap (pre-planning)", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Empty\n\n## Purpose\nTest.\n"); + writeFileSync(join(mDir, "M001-ROADMAP.md"), ""); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Empty", status: "active" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + assert.equal(state.phase, "pre-planning", "empty ROADMAP should result in pre-planning"); + }); + + test("ROADMAP with no ## Slices section derives pre-planning", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: No Slices\n\n## Purpose\nTest.\n"); + writeFileSync( + join(mDir, "M001-ROADMAP.md"), + [ + "# M001: No Slices", + "", + "## Vision", + "Test zero slices.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + ].join("\n"), + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "No Slices", status: "active" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + // 0-slice ROADMAP guard: should NOT derive validating-milestone (#2667) + assert.notEqual( + state.phase, + "validating-milestone", + "0-slice ROADMAP must NOT produce validating-milestone", + ); + }); + + test("corrupt VALIDATION frontmatter: extractVerdict returns undefined", () => { + // Test the verdict parser directly with malformed content + assert.equal(extractVerdict(""), undefined, "empty string → undefined"); + assert.equal(extractVerdict("---\n\n---\n# No verdict"), undefined, "empty frontmatter → undefined"); + assert.equal(extractVerdict("---\nverdict:\n---"), undefined, "verdict with no value → undefined"); + assert.equal( + extractVerdict("random text without frontmatter"), + undefined, + "no frontmatter → undefined", + ); + }); + + test("VALIDATION with binary/garbage content: isValidationTerminal returns false", () => { + assert.equal(isValidationTerminal(""), false, "empty → not terminal"); + assert.equal(isValidationTerminal("\x00\xFF\xFE"), false, "binary → not terminal"); + assert.equal( + isValidationTerminal("---\ngarbage: yes\n---\nNo verdict here."), + false, + "no verdict field → not terminal", + ); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 2: Transition Boundary Failures +// ───────────────────────────────────────────────────────────────────────── + +describe("transition boundary failures", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("mid-transition: CONTEXT.md created between derives transitions needs-discussion → pre-planning correctly", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + + // Start with only CONTEXT-DRAFT → needs-discussion + writeFileSync(join(mDir, "M001-CONTEXT-DRAFT.md"), "# Draft\nSome draft.\n"); + + openDatabase(join(base, ".gsd", "gsd.db")); + invalidateAllCaches(); + const state1 = await deriveState(base); + assert.equal(state1.phase, "needs-discussion"); + + // Now write the full CONTEXT (simulates discussion completion) + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Resolved\n\n## Purpose\nDone.\n"); + + invalidateAllCaches(); + const state2 = await deriveState(base); + // Should advance to pre-planning (has context but no roadmap yet) + assert.equal(state2.phase, "pre-planning"); + }); + + test("cascading slice dependencies: S02 depends S01, S03 depends S02 — only S01 eligible", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + + // Create 3 slices with chain deps + for (const sid of ["S01", "S02", "S03"]) { + const sDir = join(mDir, "slices", sid, "tasks"); + mkdirSync(sDir, { recursive: true }); + writeFileSync( + join(mDir, "slices", sid, `${sid}-PLAN.md`), + [ + `# ${sid}: Feature`, + "", + "**Goal:** Do the thing.", + "", + "## Tasks", + "", + "- [ ] **T01: Task** `est:30m`", + " - Do: Implement", + " - Verify: Run tests", + ].join("\n"), + ); + writeFileSync(join(sDir, "T01-PLAN.md"), "# T01 Plan\nDo it.\n"); + } + + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Chain\n\n## Purpose\nTest deps.\n"); + writeFileSync( + join(mDir, "M001-ROADMAP.md"), + [ + "# M001: Chain Deps", + "", + "## Vision", + "Test cascading.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "- [ ] **S01: Base** `risk:low` `depends:[]`", + " - After this: Base done.", + "", + "- [ ] **S02: Middle** `risk:low` `depends:[S01]`", + " - After this: Middle done.", + "", + "- [ ] **S03: Top** `risk:low` `depends:[S02]`", + " - After this: Top done.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | S02 | base | nothing |", + "| S02 | S03 | middle | base |", + "| S03 | terminal | top | middle |", + ].join("\n"), + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Chain", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Base", status: "pending", depends: [] }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Middle", status: "pending", depends: ["S01"] }); + insertSlice({ id: "S03", milestoneId: "M001", title: "Top", status: "pending", depends: ["S02"] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T01", sliceId: "S03", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + + // Only S01 should be active — S02 and S03 are dep-blocked + assert.equal(state.activeSlice?.id, "S01", "S01 should be the active slice (no deps)"); + assert.equal(state.phase, "executing", "should be executing S01"); + }); + + test("cascading deps: completing S01 unblocks S02 (not S03)", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + for (const sid of ["S01", "S02", "S03"]) { + const sDir = join(mDir, "slices", sid, "tasks"); + mkdirSync(sDir, { recursive: true }); + writeFileSync( + join(mDir, "slices", sid, `${sid}-PLAN.md`), + `# ${sid}\n\n**Goal:** Do.\n\n## Tasks\n\n- [ ] **T01: Task** \`est:30m\`\n - Do: Impl\n - Verify: Test\n`, + ); + writeFileSync(join(sDir, "T01-PLAN.md"), `# T01 Plan\nDo it.\n`); + } + // Write slice SUMMARY for S01 + writeFileSync( + join(mDir, "slices", "S01", "S01-SUMMARY.md"), + "---\n---\n# S01 Summary\nDone.\n", + ); + + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001: Chain\n\n## Purpose\nTest.\n"); + writeFileSync( + join(mDir, "M001-ROADMAP.md"), + [ + "# M001: Chain", + "", + "## Vision", + "Test.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "- [x] **S01: Base** `risk:low` `depends:[]`", + " - After this: Done.", + "", + "- [ ] **S02: Middle** `risk:low` `depends:[S01]`", + " - After this: Done.", + "", + "- [ ] **S03: Top** `risk:low` `depends:[S02]`", + " - After this: Done.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | S02 | x | nothing |", + "| S02 | S03 | y | x |", + "| S03 | terminal | z | y |", + ].join("\n"), + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Chain", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Base", status: "complete", depends: [] }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Middle", status: "pending", depends: ["S01"] }); + insertSlice({ id: "S03", milestoneId: "M001", title: "Top", status: "pending", depends: ["S02"] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T01", sliceId: "S03", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + + // S01 complete → S02 unblocked → S02 should be active + assert.equal(state.activeSlice?.id, "S02", "S02 should be active after S01 completes"); + assert.equal(state.phase, "executing"); + }); + + test("multi-milestone deps: M002 depends M001, M003 depends M002 — blocked correctly", async () => { + base = createMultiMilestoneFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "First", status: "active" }); + insertMilestone({ id: "M002", title: "Second", status: "active", depends_on: ["M001"] }); + insertMilestone({ id: "M003", title: "Third", status: "active", depends_on: ["M002"] }); + + insertSlice({ id: "S01", milestoneId: "M001", title: "S01", status: "pending" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + insertSlice({ id: "S01", milestoneId: "M002", title: "S01", status: "pending" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M002", status: "pending" }); + insertSlice({ id: "S01", milestoneId: "M003", title: "S01", status: "pending" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M003", status: "pending" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + + // Only M001 should be active — M002 and M003 are blocked + assert.equal(state.activeMilestone?.id, "M001", "M001 should be active (no deps)"); + }); + + test("blocker_discovered in task transitions to replanning-slice", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete", blockerDiscovered: true }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + assert.equal(state.phase, "replanning-slice", "blocker_discovered should trigger replanning"); + assert.ok(state.blockers.length > 0, "should report blocker"); + }); + + test("replan loop protection: replan already done skips replanning-slice", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete", blockerDiscovered: true }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Record that a replan was already done for this slice + insertReplanHistory({ + milestoneId: "M001", + sliceId: "S01", + summary: "Already replanned once", + }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + // With replan history, should NOT re-enter replanning-slice + assert.notEqual( + state.phase, + "replanning-slice", + "replan loop protection: should not re-enter replanning after replan was done", + ); + }); + + test("blocked state: all slices have unmet deps → blocked phase", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(join(mDir, "slices", "S01", "tasks"), { recursive: true }); + mkdirSync(join(mDir, "slices", "S02", "tasks"), { recursive: true }); + + writeFileSync(join(mDir, "M001-CONTEXT.md"), "# M001\n\n## Purpose\nTest.\n"); + writeFileSync( + join(mDir, "M001-ROADMAP.md"), + [ + "# M001: Blocked", + "", + "## Vision", + "Test blocked.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "- [ ] **S01: A** `risk:low` `depends:[S02]`", + " - After this: Done.", + "", + "- [ ] **S02: B** `risk:low` `depends:[S01]`", + " - After this: Done.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | S02 | a | b |", + "| S02 | S01 | b | a |", + ].join("\n"), + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Blocked", status: "active" }); + // Circular deps: S01→S02 and S02→S01 — both blocked + insertSlice({ id: "S01", milestoneId: "M001", title: "A", status: "pending", depends: ["S02"] }); + insertSlice({ id: "S02", milestoneId: "M001", title: "B", status: "pending", depends: ["S01"] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + assert.equal(state.phase, "blocked", "circular deps should produce blocked phase"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 3: Dispatch Failure Modes +// ───────────────────────────────────────────────────────────────────────── + +describe("dispatch failure modes", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("dispatch with null activeSlice in executing phase → stop (error)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "executing", + activeSlice: null, + activeTask: { id: "T01", title: "Task" }, + }); + + // The "executing → execute-task (recover missing task plan)" rule checks activeSlice + // and returns missingSliceStop when null + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "null activeSlice in executing should stop"); + }); + + test("dispatch for unhandled phase → stop with diagnostic", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "paused" as any, + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "unhandled phase should produce stop action"); + }); + + test("dispatch: summarizing with null activeSlice → stop (error)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "summarizing", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "summarizing without activeSlice should stop"); + assert.ok( + (result as any).reason?.includes("no active slice"), + "stop reason should mention missing slice", + ); + }); + + test("dispatch: evaluating-gates without gate config → skip (gates omitted)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "evaluating-gates", + activeSlice: { id: "S01", title: "First" }, + activeTask: null, + }); + ctx.prefs = undefined; // No prefs → gate_evaluation not enabled + + const result = await resolveDispatch(ctx); + // Without gate config, the rule should skip (gates omitted) + assert.ok( + result.action === "skip" || result.action === "stop", + `evaluating-gates without config should skip or stop, got: ${result.action}`, + ); + }); + + test("dispatch: needs-discussion → discuss-milestone dispatch", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "needs-discussion", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "dispatch"); + assert.equal((result as any).unitType, "discuss-milestone"); + }); + + test("dispatch: complete phase → stop with info level", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "complete", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop"); + assert.equal((result as any).level, "info"); + assert.ok((result as any).reason?.includes("complete"), "reason should mention completion"); + }); + + test("dispatch rule order: first match wins for overlapping rules", () => { + const ruleNames = getDispatchRuleNames(); + // Verify critical ordering constraints + const summarizeIdx = ruleNames.indexOf("summarizing → complete-slice"); + const runUatIdx = ruleNames.indexOf("run-uat (post-completion)"); + const uatGateIdx = ruleNames.indexOf("uat-verdict-gate (non-PASS blocks progression)"); + const executeIdx = ruleNames.indexOf("executing → execute-task"); + + // summarizing should come before execute-task + assert.ok(summarizeIdx < executeIdx, "summarizing rule should precede execute-task"); + // run-uat should come before uat-verdict-gate + assert.ok(runUatIdx < uatGateIdx, "run-uat should precede uat-verdict-gate"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 4: Completion & Verification Failures +// ───────────────────────────────────────────────────────────────────────── + +describe("completion and verification failures", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("needs-remediation VALIDATION blocks milestone completion dispatch", async () => { + base = createFullFixture(); + const mDir = join(base, ".gsd", "milestones", "M001"); + writeFileSync( + join(mDir, "M001-VALIDATION.md"), + [ + "---", + "verdict: needs-remediation", + "remediation_round: 1", + "---", + "", + "# Validation", + "", + "Needs remediation work.", + ].join("\n"), + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "completing-milestone", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "needs-remediation should block completion"); + assert.ok( + (result as any).reason?.includes("needs-remediation"), + "stop reason should mention needs-remediation", + ); + }); + + test("missing slice SUMMARY blocks milestone validation dispatch", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + // Use "pending" status — closed slices (complete/done/skipped) are + // excluded from SUMMARY checks per #3620. + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "pending" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "pending" }); + // No S01-SUMMARY.md or S02-SUMMARY.md on disk + + const ctx = buildDispatchCtx(base, "M001", { + phase: "validating-milestone", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "missing SUMMARY files should block validation"); + assert.ok( + (result as any).reason?.includes("missing SUMMARY"), + "stop reason should mention missing SUMMARY", + ); + }); + + test("VALIDATION with pass verdict: isValidationTerminal returns true", () => { + const content = "---\nverdict: pass\nremediation_round: 0\n---\n# Pass\n"; + assert.equal(isValidationTerminal(content), true); + }); + + test("VALIDATION with needs-attention: isValidationTerminal returns true", () => { + const content = "---\nverdict: needs-attention\n---\n# Attention\n"; + assert.equal(isValidationTerminal(content), true); + }); + + test("VALIDATION with needs-remediation: isValidationTerminal returns true (terminal for loop prevention)", () => { + // Per #832: needs-remediation IS terminal to prevent validate-milestone loops + const content = "---\nverdict: needs-remediation\nremediation_round: 1\n---\n# Remediate\n"; + assert.equal(isValidationTerminal(content), true); + }); + + test("UAT verdict gate: non-PASS verdict blocks progression", () => { + assert.equal(isAcceptableUatVerdict("pass", undefined), true); + assert.equal(isAcceptableUatVerdict("passed", undefined), true); + assert.equal(isAcceptableUatVerdict("fail", undefined), false); + assert.equal(isAcceptableUatVerdict("needs-remediation", undefined), false); + assert.equal(isAcceptableUatVerdict("partial", undefined), false, "partial without eligible type → not acceptable"); + assert.equal(isAcceptableUatVerdict("partial", "mixed"), true, "partial with mixed type → acceptable"); + assert.equal(isAcceptableUatVerdict("partial", "human-experience"), true, "partial with human-experience → acceptable"); + assert.equal(isAcceptableUatVerdict("partial", "artifact-driven"), false, "partial with artifact-driven → not acceptable"); + }); + + test("milestone validation verdict schema validation", () => { + assert.equal(isValidMilestoneVerdict("pass"), true); + assert.equal(isValidMilestoneVerdict("needs-attention"), true); + assert.equal(isValidMilestoneVerdict("needs-remediation"), true); + assert.equal(isValidMilestoneVerdict("fail"), false, "fail is not a valid milestone verdict"); + assert.equal(isValidMilestoneVerdict(""), false); + assert.equal(isValidMilestoneVerdict("unknown"), false); + }); + + test("all slices done + no VALIDATION → validating-milestone (not completing)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "complete" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + assert.equal( + state.phase, + "validating-milestone", + "all slices done without VALIDATION should be validating-milestone", + ); + }); + + test("all slices done + terminal VALIDATION + no SUMMARY → completing-milestone", async () => { + base = createFullFixture(); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"), + "---\nverdict: pass\n---\n# Validation\nPassed.\n", + ); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "complete" }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + assert.equal( + state.phase, + "completing-milestone", + "terminal VALIDATION without SUMMARY should be completing-milestone", + ); + }); + + test("extractVerdict: markdown body fallback works", () => { + // When LLM writes verdict in body instead of frontmatter (#2960) + assert.equal(extractVerdict("# Validation\n\n**Verdict:** PASS"), "pass"); + assert.equal(extractVerdict("# Validation\n\n**Verdict:** ✅ PASS"), "pass"); + assert.equal(extractVerdict("# Validation\n\n**Verdict** needs-remediation"), "needs-remediation"); + }); + + test("extractVerdict: normalizes 'passed' to 'pass'", () => { + assert.equal(extractVerdict("---\nverdict: passed\n---"), "pass"); + assert.equal(extractVerdict("**Verdict:** passed"), "pass"); + }); + + test("isClosedStatus: boundary values", () => { + assert.equal(isClosedStatus("complete"), true); + assert.equal(isClosedStatus("done"), true); + assert.equal(isClosedStatus("skipped"), true); + assert.equal(isClosedStatus("active"), false); + assert.equal(isClosedStatus("pending"), false); + assert.equal(isClosedStatus("in_progress"), false); + assert.equal(isClosedStatus(""), false); + assert.equal(isClosedStatus("COMPLETE"), false, "case-sensitive: uppercase should be false"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 5: Ghost Milestone Edge Cases +// ───────────────────────────────────────────────────────────────────────── + +describe("ghost milestone edge cases", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("empty directory with DB row is NOT a ghost (#2921)", () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Queued", status: "active" }); + + assert.equal(isGhostMilestone(base, "M001"), false, "DB row means not a ghost"); + }); + + test("empty directory with worktree is NOT a ghost (#2921)", () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + // Simulate worktree existence + mkdirSync(join(base, ".gsd", "worktrees", "M001"), { recursive: true }); + + assert.equal(isGhostMilestone(base, "M001"), false, "worktree means not a ghost"); + }); + + test("empty directory without DB or worktree IS a ghost", () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + + assert.equal(isGhostMilestone(base, "M001"), true, "no DB, no worktree, no files → ghost"); + }); + + test("directory with only META.json is still a ghost", () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "META.json"), '{"created":"2026-01-01"}'); + + assert.equal(isGhostMilestone(base, "M001"), true, "META.json alone → ghost"); + }); + + test("ghost milestones are skipped in state derivation", async () => { + base = makeTempDir(); + const gsdDir = join(base, ".gsd", "milestones"); + + // M001 is ghost — empty dir + mkdirSync(join(gsdDir, "M001"), { recursive: true }); + + // M002 is real — has CONTEXT-DRAFT + mkdirSync(join(gsdDir, "M002"), { recursive: true }); + writeFileSync(join(gsdDir, "M002", "M002-CONTEXT-DRAFT.md"), "# Draft\nContent.\n"); + + invalidateAllCaches(); + const state = await deriveState(base); + assert.equal(state.activeMilestone?.id, "M002", "ghost M001 skipped, M002 is active"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 6: Dispatch Guard Integration +// ───────────────────────────────────────────────────────────────────────── + +describe("dispatch guard integration", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("skip_milestone_validation preference writes pass-through VALIDATION", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + // Write slice SUMMARYs so the missing SUMMARY guard doesn't fire + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), + "# S01 Summary\nDone.\n", + ); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-SUMMARY.md"), + "# S02 Summary\nDone.\n", + ); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "validating-milestone", + activeSlice: null, + activeTask: null, + }); + ctx.prefs = { phases: { skip_milestone_validation: true } } as any; + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "skip", "skip_milestone_validation should produce skip action"); + + // Should have written a pass-through VALIDATION file + const validationPath = join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"); + assert.ok(existsSync(validationPath), "VALIDATION file should be written"); + const content = readFileSync(validationPath, "utf-8"); + assert.ok(content.includes("verdict: pass"), "should contain pass verdict"); + assert.ok(content.includes("skipped by preference"), "should note it was skipped"); + }); + + test("rewrite-docs circuit breaker: exceeding MAX attempts resolves all overrides", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + + // Write a rewrite count at the max + const runtimeDir = join(base, ".gsd", "runtime"); + mkdirSync(runtimeDir, { recursive: true }); + writeFileSync( + join(runtimeDir, "rewrite-count.json"), + JSON.stringify({ count: 3, updatedAt: new Date().toISOString() }), + ); + + // Import and check + const { getRewriteCount } = await import("../../auto-dispatch.ts"); + assert.equal(getRewriteCount(base), 3, "rewrite count should be 3"); + }); + + test("replanning-slice with null activeSlice → stop (error)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + + const ctx = buildDispatchCtx(base, "M001", { + phase: "replanning-slice", + activeSlice: null, + activeTask: null, + }); + + const result = await resolveDispatch(ctx); + assert.equal(result.action, "stop", "replanning without activeSlice should stop"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/integration/state-machine-live-validation.test.ts b/src/resources/extensions/gsd/tests/integration/state-machine-live-validation.test.ts new file mode 100644 index 000000000..9b094578e --- /dev/null +++ b/src/resources/extensions/gsd/tests/integration/state-machine-live-validation.test.ts @@ -0,0 +1,957 @@ +/** + * state-machine-live-validation.test.ts — Live operational validation of the + * GSD state machine with real handlers, real DB, and real filesystem. + * + * Exercises every phase transition, completion guard, edge case, and reopen + * path end-to-end. This is NOT a unit test — it drives the actual tool handlers + * against a real temp directory with a real SQLite database. + * + * Findings reference: #3161 (state machine validation report) + */ + +// GSD State Machine Live Validation (#3161) + + + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + readFileSync, + rmSync, + existsSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +// ── DB layer ────────────────────────────────────────────────────────────── +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, + getTask, + getSlice, + getMilestone, + getSliceTasks, + getMilestoneSlices, + updateTaskStatus, + updateSliceStatus, + updateMilestoneStatus, +} from "../../gsd-db.ts"; + +// ── Tool handlers ───────────────────────────────────────────────────────── +import { handleCompleteTask } from "../../tools/complete-task.ts"; +import { handleCompleteSlice } from "../../tools/complete-slice.ts"; +import { handleCompleteMilestone } from "../../tools/complete-milestone.ts"; +import { handleReopenTask } from "../../tools/reopen-task.ts"; +import { handleReopenSlice } from "../../tools/reopen-slice.ts"; + +// ── State derivation ────────────────────────────────────────────────────── +import { + deriveState, + deriveStateFromDb, + invalidateStateCache, + isGhostMilestone, +} from "../../state.ts"; + +// ── Status guards ───────────────────────────────────────────────────────── +import { isClosedStatus } from "../../status-guards.ts"; + +// ── Events ──────────────────────────────────────────────────────────────── +import { readEvents } from "../../workflow-events.ts"; + +// ── Cache invalidation ─────────────────────────────────────────────────── +import { invalidateAllCaches } from "../../cache.ts"; + +// ═══════════════════════════════════════════════════════════════════════════ +// Fixture Helpers +// ═══════════════════════════════════════════════════════════════════════════ + +function makeTempDir(): string { + return mkdtempSync(join(tmpdir(), "gsd-live-validation-")); +} + +/** + * Create a realistic .gsd/ fixture with: + * - M001 milestone with ROADMAP, CONTEXT + * - S01 slice with PLAN (2 tasks T01, T02) + * - S02 slice with PLAN (1 task T01) + * - Task PLAN stubs for each task + * - REQUIREMENTS.md and DECISIONS.md + */ +function createFullFixture(): string { + const base = makeTempDir(); + const gsdDir = join(base, ".gsd"); + const m001Dir = join(gsdDir, "milestones", "M001"); + const s01Dir = join(m001Dir, "slices", "S01"); + const s01Tasks = join(s01Dir, "tasks"); + const s02Dir = join(m001Dir, "slices", "S02"); + const s02Tasks = join(s02Dir, "tasks"); + + mkdirSync(s01Tasks, { recursive: true }); + mkdirSync(s02Tasks, { recursive: true }); + + // CONTEXT.md — needed to get past needs-discussion + writeFileSync( + join(m001Dir, "M001-CONTEXT.md"), + [ + "# M001: Live Validation Milestone", + "", + "## Purpose", + "Validate the state machine end-to-end.", + ].join("\n"), + ); + + // ROADMAP.md + writeFileSync( + join(m001Dir, "M001-ROADMAP.md"), + [ + "# M001: Live Validation Milestone", + "", + "## Vision", + "Prove state machine correctness.", + "", + "## Success Criteria", + "- All operations succeed", + "", + "## Slices", + "", + "- [ ] **S01: First Feature** `risk:low` `depends:[]`", + " - After this: First feature proven.", + "", + "- [ ] **S02: Second Feature** `risk:low` `depends:[]`", + " - After this: Second feature proven.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | terminal | feature-a | nothing |", + "| S02 | terminal | feature-b | nothing |", + ].join("\n"), + ); + + // S01 PLAN + writeFileSync( + join(s01Dir, "S01-PLAN.md"), + [ + "# S01: First Feature", + "", + "**Goal:** Implement first feature.", + "", + "## Tasks", + "", + "- [ ] **T01: Implementation** `est:30m`", + " - Do: Build it", + " - Verify: Run tests", + "", + "- [ ] **T02: Testing** `est:30m`", + " - Do: Write tests", + " - Verify: Run tests", + ].join("\n"), + ); + + // S01 task plan stubs + writeFileSync(join(s01Tasks, "T01-PLAN.md"), "# T01 Plan\nImplement.\n"); + writeFileSync(join(s01Tasks, "T02-PLAN.md"), "# T02 Plan\nTest.\n"); + + // S02 PLAN + writeFileSync( + join(s02Dir, "S02-PLAN.md"), + [ + "# S02: Second Feature", + "", + "**Goal:** Implement second feature.", + "", + "## Tasks", + "", + "- [ ] **T01: Implementation** `est:30m`", + " - Do: Build it", + " - Verify: Run tests", + ].join("\n"), + ); + + // S02 task plan stub + writeFileSync(join(s02Tasks, "T01-PLAN.md"), "# T01 Plan\nBuild.\n"); + + // REQUIREMENTS.md + writeFileSync( + join(gsdDir, "REQUIREMENTS.md"), + [ + "# Requirements", + "", + "## Active", + "", + "| ID | Description | Owner |", + "|----|-------------|-------|", + "| R001 | Feature works | S01 |", + ].join("\n"), + ); + + // DECISIONS.md + writeFileSync( + join(gsdDir, "DECISIONS.md"), + [ + "# Decisions", + "", + "| ID | Decision | Choice | Rationale |", + "|----|----------|--------|-----------|", + ].join("\n"), + ); + + return base; +} + +function makeTaskParams( + taskId: string, + sliceId: string, + milestoneId: string, + overrides?: Partial>, +): Record { + return { + taskId, + sliceId, + milestoneId, + oneLiner: `Completed ${taskId}`, + narrative: `Implemented ${taskId} with full coverage.`, + verification: "All tests pass.", + keyFiles: ["src/feature.ts"], + keyDecisions: [], + deviations: "None.", + knownIssues: "None.", + blockerDiscovered: false, + verificationEvidence: [ + { command: "npm test", exitCode: 0, verdict: "pass", durationMs: 1000 }, + ], + ...overrides, + }; +} + +function makeSliceParams( + sliceId: string, + milestoneId: string, +): Record { + return { + sliceId, + milestoneId, + sliceTitle: `${sliceId} Feature`, + oneLiner: `${sliceId} proven`, + narrative: "All tasks completed.", + verification: "Tests pass.", + keyFiles: ["src/feature.ts"], + keyDecisions: [], + patternsEstablished: [], + observabilitySurfaces: [], + deviations: "None.", + knownLimitations: "None.", + followUps: "None.", + requirementsAdvanced: [], + requirementsValidated: [], + requirementsSurfaced: [], + requirementsInvalidated: [], + filesModified: [{ path: "src/feature.ts", description: "Feature" }], + uatContent: "Acceptance criteria met.", + provides: ["feature"], + requires: [], + affects: [], + drillDownPaths: [], + }; +} + +function makeMilestoneParams(milestoneId: string): Record { + return { + milestoneId, + title: "Live Validation Milestone", + oneLiner: "Milestone proven end-to-end", + narrative: "All slices completed and verified.", + successCriteriaResults: "All criteria met.", + definitionOfDoneResults: "All items checked.", + requirementOutcomes: "All requirements satisfied.", + keyDecisions: ["Chose approach A"], + keyFiles: ["src/feature.ts"], + lessonsLearned: ["Integration testing is valuable"], + followUps: "None.", + deviations: "None.", + verificationPassed: true, + }; +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Test Suite +// ═══════════════════════════════════════════════════════════════════════════ + +describe("state-machine-live-validation", () => { + let base: string; + + afterEach(() => { + closeDatabase(); + if (base) rmSync(base, { recursive: true, force: true }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 1: Full happy-path lifecycle + // ───────────────────────────────────────────────────────────────────────── + + describe("happy path: full lifecycle M001 → complete", () => { + test("step 1: empty project derives pre-planning", async () => { + base = makeTempDir(); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + const state = await deriveState(base); + assert.equal(state.phase, "pre-planning"); + assert.equal(state.activeMilestone, null); + }); + + test("step 2: milestone with CONTEXT-DRAFT derives needs-discussion", async () => { + base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + writeFileSync(join(mDir, "M001-CONTEXT-DRAFT.md"), "# Draft\nDraft context.\n"); + invalidateStateCache(); + const state = await deriveState(base); + assert.equal(state.phase, "needs-discussion"); + assert.equal(state.activeMilestone?.id, "M001"); + }); + + test("step 3: full fixture with ROADMAP+PLAN derives planning or executing", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + invalidateStateCache(); + const state = await deriveState(base); + // Without DB migration, filesystem path is used — should be planning or executing + assert.ok( + ["planning", "executing", "pre-planning"].includes(state.phase), + `expected planning/executing/pre-planning, got: ${state.phase}`, + ); + }); + + test("step 4: complete T01 in S01 — handler succeeds, DB reflects completion", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + // Seed DB with hierarchy + insertMilestone({ id: "M001", title: "Live Validation", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Implementation", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "Testing", status: "pending" }); + + const result = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok(!("error" in result), `expected success, got: ${JSON.stringify(result)}`); + + // Verify DB state + const task = getTask("M001", "S01", "T01"); + assert.ok(task, "T01 should exist in DB"); + assert.ok(isClosedStatus(task!.status), `T01 status should be closed, got: ${task!.status}`); + + // Verify SUMMARY.md written to disk + const summaryPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"); + assert.ok(existsSync(summaryPath), "T01-SUMMARY.md should exist on disk"); + + // Verify event log entry + const events = readEvents(join(base, ".gsd", "event-log.jsonl")); + const taskEvent = events.find(e => e.cmd === "complete-task" && (e.params as any).taskId === "T01"); + assert.ok(taskEvent, "event log should contain complete-task for T01"); + }); + + test("step 5: complete T02 in S01 — both tasks now done", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Live Validation", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Implementation", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "Testing", status: "pending" }); + + const result = await handleCompleteTask(makeTaskParams("T02", "S01", "M001") as any, base); + assert.ok(!("error" in result), `expected success, got: ${JSON.stringify(result)}`); + + // Both tasks complete + const tasks = getSliceTasks("M001", "S01"); + assert.equal(tasks.length, 2); + assert.ok(tasks.every(t => isClosedStatus(t.status)), "all tasks should be closed"); + }); + + test("step 6: complete slice S01 — all tasks done, slice closes", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Live Validation", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Impl", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "Test", status: "complete" }); + + const result = await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok(!("error" in result), `expected success, got: ${JSON.stringify(result)}`); + + const slice = getSlice("M001", "S01"); + assert.ok(slice, "S01 should exist"); + assert.ok(isClosedStatus(slice!.status), `S01 should be closed, got: ${slice!.status}`); + + // SUMMARY.md on disk + const summaryPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"); + assert.ok(existsSync(summaryPath), "S01-SUMMARY.md should exist"); + }); + + test("step 7: complete S02 task + slice — both slices done", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Live Validation", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Impl", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", title: "Impl", status: "pending" }); + + // Complete task + const taskResult = await handleCompleteTask(makeTaskParams("T01", "S02", "M001") as any, base); + assert.ok(!("error" in taskResult), `task: ${JSON.stringify(taskResult)}`); + + // Complete slice + const sliceResult = await handleCompleteSlice(makeSliceParams("S02", "M001") as any, base); + assert.ok(!("error" in sliceResult), `slice: ${JSON.stringify(sliceResult)}`); + + // Both slices complete + const slices = getMilestoneSlices("M001"); + assert.ok(slices.length >= 2, "should have 2+ slices"); + assert.ok(slices.every(s => isClosedStatus(s.status)), "all slices should be closed"); + }); + + test("step 8: complete milestone M001 — full lifecycle done", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Live Validation", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Impl", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "Test", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", title: "Impl", status: "complete" }); + + const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base); + assert.ok(!("error" in result), `expected success, got: ${JSON.stringify(result)}`); + + const milestone = getMilestone("M001"); + assert.ok(milestone, "M001 should exist"); + assert.ok(isClosedStatus(milestone!.status), `M001 should be closed, got: ${milestone!.status}`); + + // SUMMARY.md on disk + const summaryPath = join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"); + assert.ok(existsSync(summaryPath), "M001-SUMMARY.md should exist"); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 2: Completion guard edge cases + // ───────────────────────────────────────────────────────────────────────── + + describe("completion guards — edge cases", () => { + test("cannot complete task with empty taskId", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + const result = await handleCompleteTask(makeTaskParams("", "S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /taskId is required/); + }); + + test("cannot complete task in closed milestone", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Done", status: "complete" }); + insertSlice({ id: "S01", milestoneId: "M001" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + const result = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /closed milestone/); + }); + + test("cannot complete task in closed slice", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + const result = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /closed slice/); + }); + + test("double task completion returns error (H5-related)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /already complete/); + }); + + test("cannot complete slice with zero tasks — vacuous truth guard", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + // No tasks inserted + + const result = await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /no tasks found/); + }); + + test("cannot complete slice with incomplete tasks", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + const result = await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /incomplete tasks/); + }); + + test("double slice completion returns error", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /already complete/); + }); + + test("cannot complete milestone with zero slices", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + + const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /no slices found/); + }); + + test("cannot complete milestone with incomplete slices", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "pending" }); + + const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /incomplete slices/); + }); + + test("cannot complete milestone with incomplete tasks in complete slice (deep check)", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + // Slice marked complete but task is still pending — simulates inconsistent state + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /incomplete tasks/); + }); + + test("cannot complete milestone without verificationPassed=true", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const params = makeMilestoneParams("M001"); + params.verificationPassed = false; + const result = await handleCompleteMilestone(params as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /verification did not pass/); + }); + + test("double milestone completion returns error", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Done", status: "complete" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base); + assert.ok("error" in result); + assert.match((result as any).error, /already complete/); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 3: Reopen operations + // ───────────────────────────────────────────────────────────────────────── + + describe("reopen operations", () => { + test("reopen task: resets completed task to pending", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleReopenTask( + { milestoneId: "M001", sliceId: "S01", taskId: "T01", reason: "Need to redo" }, + base, + ); + assert.ok(!("error" in result), `expected success: ${JSON.stringify(result)}`); + + const task = getTask("M001", "S01", "T01"); + assert.equal(task!.status, "pending"); + }); + + test("cannot reopen task that is not complete", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + const result = await handleReopenTask( + { milestoneId: "M001", sliceId: "S01", taskId: "T01" }, + base, + ); + assert.ok("error" in result); + assert.match((result as any).error, /not complete/); + }); + + test("cannot reopen task in closed slice — must reopen slice first", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleReopenTask( + { milestoneId: "M001", sliceId: "S01", taskId: "T01" }, + base, + ); + assert.ok("error" in result); + assert.match((result as any).error, /closed slice/); + }); + + test("cannot reopen task in closed milestone", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Done", status: "complete" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleReopenTask( + { milestoneId: "M001", sliceId: "S01", taskId: "T01" }, + base, + ); + assert.ok("error" in result); + assert.match((result as any).error, /closed milestone/); + }); + + test("reopen slice: resets slice to in_progress and all tasks to pending", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleReopenSlice( + { milestoneId: "M001", sliceId: "S01", reason: "Need rework" }, + base, + ); + assert.ok(!("error" in result), `expected success: ${JSON.stringify(result)}`); + assert.equal((result as any).tasksReset, 2); + + // Verify slice state + const slice = getSlice("M001", "S01"); + assert.equal(slice!.status, "in_progress"); + + // Verify all tasks reset to pending + const tasks = getSliceTasks("M001", "S01"); + assert.ok(tasks.every(t => t.status === "pending"), "all tasks should be pending after slice reopen"); + }); + + test("cannot reopen slice in closed milestone", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Done", status: "complete" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "complete" }); + + const result = await handleReopenSlice( + { milestoneId: "M001", sliceId: "S01" }, + base, + ); + assert.ok("error" in result); + assert.match((result as any).error, /closed milestone/); + }); + + test("no reopen-milestone tool exists — milestone completion is irrevocable (H5)", async () => { + // This test documents the H5 finding: there is no handleReopenMilestone function. + // A completed milestone can only be undone via direct DB manipulation. + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Done", status: "complete" }); + + const milestone = getMilestone("M001"); + assert.ok(isClosedStatus(milestone!.status), "milestone is closed"); + + // The only escape is direct DB manipulation — no handler exists + updateMilestoneStatus("M001", "active", null); + const reopened = getMilestone("M001"); + assert.equal(reopened!.status, "active", "direct DB manipulation can reopen, but no tool exposes this"); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 4: Phantom parents and auto-creation (H6) + // ───────────────────────────────────────────────────────────────────────── + + describe("phantom parent auto-creation (H6)", () => { + test("completing task for non-existent milestone/slice auto-creates them", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + // No milestone or slice pre-inserted — handler will auto-create + + const result = await handleCompleteTask(makeTaskParams("T01", "S99", "M099") as any, base); + assert.ok(!("error" in result), `expected success: ${JSON.stringify(result)}`); + + // Phantom milestone created — H6 fix: now uses ID as title instead of empty string + const milestone = getMilestone("M099"); + assert.ok(milestone, "phantom milestone M099 should exist"); + assert.equal(milestone!.title, "M099", "H6 fix: phantom milestone uses ID as title"); + + // Phantom slice created + const slice = getSlice("M099", "S99"); + assert.ok(slice, "phantom slice S99 should exist"); + }); + + test("completing slice for non-existent milestone auto-creates it", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + // Insert task to satisfy completion guard + insertMilestone({ id: "M099" }); + insertSlice({ id: "S99", milestoneId: "M099" }); + insertTask({ id: "T01", sliceId: "S99", milestoneId: "M099", status: "complete" }); + + const result = await handleCompleteSlice(makeSliceParams("S99", "M099") as any, base); + assert.ok(!("error" in result), `expected success: ${JSON.stringify(result)}`); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 5: State derivation consistency + // ───────────────────────────────────────────────────────────────────────── + + describe("state derivation with live DB", () => { + test("deriveStateFromDb reflects task completion immediately", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + invalidateStateCache(); + const stateBefore = await deriveStateFromDb(base); + assert.equal(stateBefore.phase, "executing", `before: expected executing, got ${stateBefore.phase}`); + + // Complete T01 + updateTaskStatus("M001", "S01", "T01", "complete", new Date().toISOString()); + invalidateStateCache(); + const stateAfterT01 = await deriveStateFromDb(base); + // Still executing — T02 is pending + assert.equal(stateAfterT01.phase, "executing", `after T01: expected executing, got ${stateAfterT01.phase}`); + + // Complete T02 + updateTaskStatus("M001", "S01", "T02", "complete", new Date().toISOString()); + invalidateStateCache(); + const stateAfterT02 = await deriveStateFromDb(base); + // All tasks done → summarizing + assert.equal(stateAfterT02.phase, "summarizing", `after T02: expected summarizing, got ${stateAfterT02.phase}`); + }); + + test("deriveStateFromDb reflects slice completion → next slice or validating", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "pending" }); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + // S01 done, S02 has pending task → executing + assert.equal(state.phase, "executing", `expected executing for S02, got ${state.phase}`); + assert.equal(state.activeSlice?.id, "S02", "active slice should be S02"); + }); + + test("deriveStateFromDb with all slices done → validating-milestone", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "complete" }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Second", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + insertTask({ id: "T01", sliceId: "S02", milestoneId: "M001", status: "complete" }); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + assert.equal(state.phase, "validating-milestone", `expected validating-milestone, got ${state.phase}`); + }); + + test("ghost milestone is skipped by deriveState", async () => { + base = makeTempDir(); + const gsdDir = join(base, ".gsd", "milestones"); + // M001 is ghost — empty dir + mkdirSync(join(gsdDir, "M001"), { recursive: true }); + // M002 has content + mkdirSync(join(gsdDir, "M002"), { recursive: true }); + writeFileSync(join(gsdDir, "M002", "M002-CONTEXT-DRAFT.md"), "# Draft\nContent.\n"); + + assert.ok(isGhostMilestone(base, "M001"), "M001 should be ghost"); + assert.ok(!isGhostMilestone(base, "M002"), "M002 should not be ghost"); + + invalidateStateCache(); + const state = await deriveState(base); + assert.equal(state.activeMilestone?.id, "M002", "should skip ghost M001 and use M002"); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 6: Event log integrity + // ───────────────────────────────────────────────────────────────────────── + + describe("event log integrity across operations", () => { + test("full operation sequence produces correct event log", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Complete T01 + await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + // Complete T02 + await handleCompleteTask(makeTaskParams("T02", "S01", "M001") as any, base); + // Complete S01 + await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + + const events = readEvents(join(base, ".gsd", "event-log.jsonl")); + + // Should have 3 events: 2 task completions + 1 slice completion + assert.ok(events.length >= 3, `expected ≥3 events, got ${events.length}`); + + const taskEvents = events.filter(e => e.cmd === "complete-task"); + assert.equal(taskEvents.length, 2, "2 task completion events"); + + const sliceEvents = events.filter(e => e.cmd === "complete-slice"); + assert.equal(sliceEvents.length, 1, "1 slice completion event"); + + // Events are ordered chronologically + for (let i = 1; i < events.length; i++) { + assert.ok( + events[i]!.ts >= events[i - 1]!.ts, + `events should be chronologically ordered: ${events[i - 1]!.ts} <= ${events[i]!.ts}`, + ); + } + + // All events have hashes and session IDs + for (const event of events) { + assert.ok(event.hash, "event should have hash"); + assert.ok(event.session_id, "event should have session_id"); + } + }); + + test("reopen operations produce events", async () => { + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + await handleReopenTask( + { milestoneId: "M001", sliceId: "S01", taskId: "T01", reason: "redo" }, + base, + ); + + const events = readEvents(join(base, ".gsd", "event-log.jsonl")); + const reopenEvent = events.find(e => e.cmd === "reopen-task"); + assert.ok(reopenEvent, "should have reopen-task event"); + assert.equal((reopenEvent!.params as any).taskId, "T01"); + assert.equal((reopenEvent!.params as any).reason, "redo"); + }); + }); + + // ───────────────────────────────────────────────────────────────────────── + // PHASE 7: Reopen-then-redo cycle + // ───────────────────────────────────────────────────────────────────────── + + describe("reopen-then-redo cycle", () => { + test("complete → reopen → re-complete task works end-to-end (M12 fixed)", async () => { + // M12 fix: reopen-task now deletes SUMMARY.md from disk before the + // post-mutation hook runs, preventing the reconciler from auto-correcting + // the task back to "complete". + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Complete — writes T01-SUMMARY.md to disk + const r1 = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok(!("error" in r1), `first complete: ${JSON.stringify(r1)}`); + + const summaryPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-SUMMARY.md"); + assert.ok(existsSync(summaryPath), "SUMMARY.md exists after completion"); + + // Reopen — now deletes SUMMARY.md from disk (M12 fix) + const r2 = await handleReopenTask({ milestoneId: "M001", sliceId: "S01", taskId: "T01" }, base); + assert.ok(!("error" in r2), `reopen: ${JSON.stringify(r2)}`); + + // Task is now properly pending — SUMMARY.md was cleaned up + assert.equal(getTask("M001", "S01", "T01")!.status, "pending"); + assert.ok(!existsSync(summaryPath), "M12 fix: SUMMARY.md cleaned up by reopen"); + + // Re-complete succeeds + const r3 = await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + assert.ok(!("error" in r3), `re-complete: ${JSON.stringify(r3)}`); + assert.ok(isClosedStatus(getTask("M001", "S01", "T01")!.status)); + }); + + test("complete slice → reopen → re-complete all works end-to-end (M12 fixed)", async () => { + // M12 fix: reopen-slice now deletes all SUMMARY.md and UAT.md artifacts + // from disk, preventing reconciler interference. + base = createFullFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Complete task + slice + await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok(isClosedStatus(getSlice("M001", "S01")!.status)); + + // Reopen slice — now cleans up all artifacts (M12 fix) + await handleReopenSlice({ milestoneId: "M001", sliceId: "S01" }, base); + assert.equal(getSlice("M001", "S01")!.status, "in_progress"); + assert.equal(getTask("M001", "S01", "T01")!.status, "pending"); + + // Re-complete task + slice succeeds + await handleCompleteTask(makeTaskParams("T01", "S01", "M001") as any, base); + const r = await handleCompleteSlice(makeSliceParams("S01", "M001") as any, base); + assert.ok(!("error" in r), `re-complete slice: ${JSON.stringify(r)}`); + assert.ok(isClosedStatus(getSlice("M001", "S01")!.status)); + }); + }); +}); diff --git a/src/resources/extensions/gsd/tests/integration/state-machine-runtime-failures.test.ts b/src/resources/extensions/gsd/tests/integration/state-machine-runtime-failures.test.ts new file mode 100644 index 000000000..beba08221 --- /dev/null +++ b/src/resources/extensions/gsd/tests/integration/state-machine-runtime-failures.test.ts @@ -0,0 +1,841 @@ +/** + * state-machine-runtime-failures.test.ts — Tests for auto-loop runtime failures, + * infrastructure errors, stuck detection, session management, merge conflicts, + * concurrent access, and race conditions. + * + * These tests use mocked LoopDeps and AutoSession to exercise the auto-loop + * error handling paths without requiring real LLM sessions or network access. + * + * Coverage gaps filled: + * 1. Infrastructure error detection and immediate stop (ENOSPC, ENOMEM, etc.) + * 2. Consecutive error graduated recovery (1st → retry, 2nd → cache flush, 3rd → stop) + * 3. Stuck detection: same error repeated, same unit 3x, oscillation A↔B + * 4. Session lock validation: compromised, pid-mismatch, missing-metadata + * 5. Session creation timeout (NEW_SESSION_TIMEOUT_MS = 30s) + * 6. MergeConflictError stops auto-loop + * 7. Max iteration safety valve + * 8. s.active race: pause signal during unit execution + * 9. Filesystem mutation during dispatch cycle + * 10. Worktree disappearance detection + */ + +// GSD State Machine Runtime Failure Tests + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + rmSync, + existsSync, + unlinkSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +// ── Infrastructure error detection ─────────────────────────────────────── +import { + isInfrastructureError, + INFRA_ERROR_CODES, +} from "../../auto/infra-errors.ts"; + +// ── Stuck detection ────────────────────────────────────────────────────── +import { detectStuck } from "../../auto/detect-stuck.ts"; +import type { WindowEntry } from "../../auto/types.ts"; + +// ── Session constants ──────────────────────────────────────────────────── +import { + AutoSession, + NEW_SESSION_TIMEOUT_MS, + MAX_UNIT_DISPATCHES, + STUB_RECOVERY_THRESHOLD, + MAX_LIFETIME_DISPATCHES, +} from "../../auto/session.ts"; + +// ── Auto-loop types ────────────────────────────────────────────────────── +import { MAX_LOOP_ITERATIONS } from "../../auto/types.ts"; + +// ── MergeConflictError ─────────────────────────────────────────────────── +import { MergeConflictError } from "../../git-service.ts"; + +// ── Session lock ───────────────────────────────────────────────────────── +import type { SessionLockStatus } from "../../session-lock.ts"; + +// ── State & DB ─────────────────────────────────────────────────────────── +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, +} from "../../gsd-db.ts"; +import { + deriveState, + deriveStateFromDb, + invalidateStateCache, + isGhostMilestone, +} from "../../state.ts"; +import { invalidateAllCaches } from "../../cache.ts"; + +// ═══════════════════════════════════════════════════════════════════════════ +// Fixture Helpers +// ═══════════════════════════════════════════════════════════════════════════ + +function makeTempDir(): string { + return mkdtempSync(join(tmpdir(), "gsd-runtime-fail-")); +} + +function createMinimalFixture(): string { + const base = makeTempDir(); + const mDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"); + mkdirSync(mDir, { recursive: true }); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), + "# M001: Runtime Test\n\n## Purpose\nTest runtime failures.\n", + ); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), + [ + "# M001: Runtime Test", + "", + "## Vision", + "Test.", + "", + "## Success Criteria", + "- Works", + "", + "## Slices", + "", + "- [ ] **S01: Feature** `risk:low` `depends:[]`", + " - After this: Done.", + "", + "## Boundary Map", + "", + "| From | To | Produces | Consumes |", + "|------|----|----------|----------|", + "| S01 | terminal | out | nothing |", + ].join("\n"), + ); + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md"), + [ + "# S01: Feature", + "", + "**Goal:** Build.", + "", + "## Tasks", + "", + "- [ ] **T01: Build** `est:30m`", + " - Do: Build it", + " - Verify: Test it", + ].join("\n"), + ); + writeFileSync( + join(mDir, "T01-PLAN.md"), + "# T01 Plan\nBuild it.\n", + ); + return base; +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Test Suite +// ═══════════════════════════════════════════════════════════════════════════ + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 1: Infrastructure Error Detection +// ───────────────────────────────────────────────────────────────────────── + +describe("infrastructure error detection", () => { + test("ENOSPC (disk full) is detected as infrastructure error", () => { + const err = Object.assign(new Error("write ENOSPC"), { code: "ENOSPC" }); + assert.equal(isInfrastructureError(err), "ENOSPC"); + }); + + test("ENOMEM (out of memory) is detected", () => { + const err = Object.assign(new Error("Cannot allocate memory"), { code: "ENOMEM" }); + assert.equal(isInfrastructureError(err), "ENOMEM"); + }); + + test("EROFS (read-only filesystem) is detected", () => { + const err = Object.assign(new Error("Read-only file system"), { code: "EROFS" }); + assert.equal(isInfrastructureError(err), "EROFS"); + }); + + test("EDQUOT (disk quota exceeded) is detected", () => { + const err = Object.assign(new Error("Disk quota exceeded"), { code: "EDQUOT" }); + assert.equal(isInfrastructureError(err), "EDQUOT"); + }); + + test("EMFILE (too many open files - process) is detected", () => { + const err = Object.assign(new Error("too many open files"), { code: "EMFILE" }); + assert.equal(isInfrastructureError(err), "EMFILE"); + }); + + test("ENFILE (too many open files - system) is detected", () => { + const err = Object.assign(new Error("file table overflow"), { code: "ENFILE" }); + assert.equal(isInfrastructureError(err), "ENFILE"); + }); + + test("ECONNREFUSED (connection refused) is detected", () => { + const err = Object.assign(new Error("Connection refused"), { code: "ECONNREFUSED" }); + assert.equal(isInfrastructureError(err), "ECONNREFUSED"); + }); + + test("ENOTFOUND (DNS lookup failed) is detected", () => { + const err = Object.assign(new Error("getaddrinfo ENOTFOUND api.anthropic.com"), { code: "ENOTFOUND" }); + assert.equal(isInfrastructureError(err), "ENOTFOUND"); + }); + + test("ENETUNREACH (network unreachable) is detected", () => { + const err = Object.assign(new Error("network is unreachable"), { code: "ENETUNREACH" }); + assert.equal(isInfrastructureError(err), "ENETUNREACH"); + }); + + test("EAGAIN (resource temporarily unavailable) is detected", () => { + const err = Object.assign(new Error("resource temporarily unavailable"), { code: "EAGAIN" }); + assert.equal(isInfrastructureError(err), "EAGAIN"); + }); + + test("SQLite WAL corruption is detected via message scan", () => { + const err = new Error("database disk image is malformed"); + assert.equal(isInfrastructureError(err), "SQLITE_CORRUPT"); + }); + + test("code-based detection when code property is present", () => { + const err = { code: "ENOSPC", message: "something" }; + assert.equal(isInfrastructureError(err), "ENOSPC"); + }); + + test("message fallback when no code property (e.g. string errors)", () => { + const err = new Error("write failed: ENOSPC: no space left on device"); + assert.equal(isInfrastructureError(err), "ENOSPC"); + }); + + test("non-infrastructure error returns null", () => { + assert.equal(isInfrastructureError(new Error("TypeError: x is not a function")), null); + assert.equal(isInfrastructureError(new Error("SyntaxError: Unexpected token")), null); + assert.equal(isInfrastructureError(new Error("rate_limit_exceeded")), null); + assert.equal(isInfrastructureError("just a string error"), null); + assert.equal(isInfrastructureError(null), null); + assert.equal(isInfrastructureError(undefined), null); + assert.equal(isInfrastructureError(42), null); + }); + + test("all INFRA_ERROR_CODES are covered", () => { + const expectedCodes = [ + "ENOSPC", "ENOMEM", "EROFS", "EDQUOT", "EMFILE", + "ENFILE", "EAGAIN", "ECONNREFUSED", "ENOTFOUND", "ENETUNREACH", + ]; + for (const code of expectedCodes) { + assert.ok(INFRA_ERROR_CODES.has(code), `${code} should be in INFRA_ERROR_CODES`); + } + assert.equal(INFRA_ERROR_CODES.size, expectedCodes.length, "no unexpected codes"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 2: Stuck Detection +// ───────────────────────────────────────────────────────────────────────── + +describe("stuck detection", () => { + test("Rule 1: same error repeated consecutively → stuck", () => { + const window: WindowEntry[] = [ + { key: "M001/S01/T01", error: "Provider returned 500" }, + { key: "M001/S01/T01", error: "Provider returned 500" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck, "same error twice should be stuck"); + assert.ok(result?.reason.includes("Same error repeated"), "reason should mention error"); + }); + + test("Rule 1: different errors are NOT stuck", () => { + const window: WindowEntry[] = [ + { key: "M001/S01/T01", error: "Provider returned 500" }, + { key: "M001/S01/T01", error: "Provider returned 429" }, + ]; + const result = detectStuck(window); + // Different errors → not stuck by Rule 1 (but might be by Rule 2 with more entries) + assert.equal(result, null, "different errors should not trigger Rule 1"); + }); + + test("Rule 2: same unit 3 consecutive times → stuck", () => { + const window: WindowEntry[] = [ + { key: "M001/S01/T01" }, + { key: "M001/S01/T01" }, + { key: "M001/S01/T01" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck, "same unit 3x should be stuck"); + assert.ok(result?.reason.includes("3 consecutive times"), "reason should mention 3x"); + }); + + test("Rule 2: 2 consecutive same units is NOT stuck", () => { + const window: WindowEntry[] = [ + { key: "M001/S01/T01" }, + { key: "M001/S01/T01" }, + ]; + const result = detectStuck(window); + assert.equal(result, null, "2x same unit is not stuck"); + }); + + test("Rule 3: oscillation A→B→A→B → stuck", () => { + const window: WindowEntry[] = [ + { key: "M001/S01/T01" }, + { key: "M001/S01/T02" }, + { key: "M001/S01/T01" }, + { key: "M001/S01/T02" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck, "A→B→A→B should be stuck"); + assert.ok(result?.reason.includes("Oscillation"), "reason should mention oscillation"); + }); + + test("Rule 3: A→B→C→D is NOT oscillation", () => { + const window: WindowEntry[] = [ + { key: "A" }, + { key: "B" }, + { key: "C" }, + { key: "D" }, + ]; + assert.equal(detectStuck(window), null, "sequential progress is not stuck"); + }); + + test("empty window returns null", () => { + assert.equal(detectStuck([]), null); + }); + + test("single entry returns null", () => { + assert.equal(detectStuck([{ key: "A" }]), null); + }); + + test("Rule 1 takes precedence over Rule 2 when both apply", () => { + const window: WindowEntry[] = [ + { key: "A", error: "fail" }, + { key: "A", error: "fail" }, + { key: "A", error: "fail" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck); + // Rule 1 fires first (same error at indices 1,2) + assert.ok(result?.reason.includes("Same error repeated")); + }); + + test("errors on different keys are not stuck by Rule 1", () => { + const window: WindowEntry[] = [ + { key: "A", error: "fail" }, + { key: "B", error: "fail" }, + ]; + // Same error but different keys — Rule 1 compares errors regardless of key + const result = detectStuck(window); + // Rule 1 says "same error repeated consecutively" — it checks error strings + assert.ok(result?.stuck, "same error string on different keys still triggers Rule 1"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 3: Session Management +// ───────────────────────────────────────────────────────────────────────── + +describe("session management", () => { + test("AutoSession reset() clears all mutable state", () => { + const s = new AutoSession(); + s.active = true; + s.paused = true; + s.basePath = "/tmp/test"; + s.currentUnit = { type: "execute-task", id: "M001/S01/T01", startedAt: Date.now() }; + s.currentMilestoneId = "M001"; + s.unitDispatchCount.set("M001/S01/T01", 3); + s.unitLifetimeDispatches.set("M001/S01/T01", 5); + s.unitRecoveryCount.set("M001/S01/T01", 1); + + s.reset(); + + assert.equal(s.active, false, "active should be false after reset"); + assert.equal(s.paused, false, "paused should be false after reset"); + assert.equal(s.currentUnit, null, "currentUnit should be null after reset"); + assert.equal(s.currentMilestoneId, null, "currentMilestoneId should be null"); + assert.equal(s.unitDispatchCount.size, 0, "dispatch counts cleared"); + assert.equal(s.unitLifetimeDispatches.size, 0, "lifetime dispatches cleared"); + assert.equal(s.unitRecoveryCount.size, 0, "recovery counts cleared"); + }); + + test("NEW_SESSION_TIMEOUT_MS is 120 seconds", () => { + assert.equal(NEW_SESSION_TIMEOUT_MS, 120_000, "session timeout should be 120s"); + }); + + test("MAX_UNIT_DISPATCHES limits retries for a single unit", () => { + assert.equal(MAX_UNIT_DISPATCHES, 3, "max unit dispatches should be 3"); + }); + + test("MAX_LIFETIME_DISPATCHES is the absolute limit per unit", () => { + assert.equal(MAX_LIFETIME_DISPATCHES, 6, "max lifetime dispatches should be 6"); + }); + + test("STUB_RECOVERY_THRESHOLD triggers recovery after N stub completions", () => { + assert.equal(STUB_RECOVERY_THRESHOLD, 2, "stub recovery threshold should be 2"); + }); + + test("MAX_LOOP_ITERATIONS prevents runaway loops", () => { + assert.equal(MAX_LOOP_ITERATIONS, 500, "max iterations should be 500"); + }); + + test("AutoSession dispatch counter tracks per-unit dispatches", () => { + const s = new AutoSession(); + const unitId = "M001/S01/T01"; + + assert.equal(s.unitDispatchCount.get(unitId), undefined); + + s.unitDispatchCount.set(unitId, 1); + assert.equal(s.unitDispatchCount.get(unitId), 1); + + s.unitDispatchCount.set(unitId, 2); + assert.equal(s.unitDispatchCount.get(unitId), 2); + + // Exceeding MAX_UNIT_DISPATCHES + s.unitDispatchCount.set(unitId, MAX_UNIT_DISPATCHES + 1); + assert.ok( + s.unitDispatchCount.get(unitId)! > MAX_UNIT_DISPATCHES, + "should track count beyond max for detection", + ); + }); + + test("AutoSession toJSON() provides diagnostic snapshot", () => { + const s = new AutoSession(); + s.active = true; + s.basePath = "/tmp/test"; + s.currentUnit = { type: "execute-task", id: "M001/S01/T01", startedAt: Date.now() }; + + const json = s.toJSON(); + assert.ok(json, "toJSON should return a value"); + assert.equal(typeof json, "object", "toJSON should return an object"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 4: Session Lock Validation +// ───────────────────────────────────────────────────────────────────────── + +describe("session lock validation", () => { + test("SessionLockStatus: valid lock", () => { + const status: SessionLockStatus = { valid: true }; + assert.equal(status.valid, true); + assert.equal(status.failureReason, undefined); + }); + + test("SessionLockStatus: compromised lock (sleep/wake cycle)", () => { + const status: SessionLockStatus = { + valid: false, + failureReason: "compromised", + }; + assert.equal(status.valid, false); + assert.equal(status.failureReason, "compromised"); + }); + + test("SessionLockStatus: pid-mismatch (another process took over)", () => { + const status: SessionLockStatus = { + valid: false, + failureReason: "pid-mismatch", + existingPid: 12345, + expectedPid: 67890, + }; + assert.equal(status.valid, false); + assert.equal(status.failureReason, "pid-mismatch"); + assert.notEqual(status.existingPid, status.expectedPid); + }); + + test("SessionLockStatus: missing-metadata", () => { + const status: SessionLockStatus = { + valid: false, + failureReason: "missing-metadata", + }; + assert.equal(status.valid, false); + assert.equal(status.failureReason, "missing-metadata"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 5: MergeConflictError +// ───────────────────────────────────────────────────────────────────────── + +describe("MergeConflictError handling", () => { + test("MergeConflictError has correct properties", () => { + const err = new MergeConflictError( + ["src/feature.ts", "src/utils.ts"], + "squash", + "gsd/auto/M001", + "main", + ); + + assert.ok(err instanceof Error, "should be an Error"); + assert.ok(err instanceof MergeConflictError, "should be a MergeConflictError"); + assert.deepEqual(err.conflictedFiles, ["src/feature.ts", "src/utils.ts"]); + assert.equal(err.strategy, "squash"); + assert.equal(err.branch, "gsd/auto/M001"); + assert.equal(err.mainBranch, "main"); + }); + + test("MergeConflictError with merge strategy", () => { + const err = new MergeConflictError( + ["package.json"], + "merge", + "feat/new-feature", + "main", + ); + assert.equal(err.strategy, "merge"); + }); + + test("MergeConflictError with empty conflict list", () => { + const err = new MergeConflictError([], "squash", "branch", "main"); + assert.deepEqual(err.conflictedFiles, []); + }); + + test("MergeConflictError is distinguishable from generic errors", () => { + const mergeErr = new MergeConflictError(["file.ts"], "squash", "b", "m"); + const genericErr = new Error("merge failed"); + + assert.ok(mergeErr instanceof MergeConflictError); + assert.ok(!(genericErr instanceof MergeConflictError)); + + // This is the exact pattern used in phases.ts catch blocks + if (mergeErr instanceof MergeConflictError) { + assert.ok(true, "instanceof check works for catch blocks"); + } + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 6: Filesystem Race Conditions +// ───────────────────────────────────────────────────────────────────────── + +describe("filesystem race conditions", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("ROADMAP deleted during derive cycle → graceful degradation", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + invalidateAllCaches(); + const state1 = await deriveStateFromDb(base); + assert.equal(state1.phase, "executing"); + + // Delete ROADMAP mid-flow + const roadmapPath = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"); + unlinkSync(roadmapPath); + + invalidateAllCaches(); + // DB still has the slice/task data, so derivation should still work + const state2 = await deriveStateFromDb(base); + assert.ok(state2.phase, "should produce a valid phase even after ROADMAP deletion"); + }); + + test("CONTEXT deleted during derive → falls back gracefully", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + + const contextPath = join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"); + unlinkSync(contextPath); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + // Without CONTEXT, title fallback should still work + assert.ok(state.activeMilestone, "should still have an active milestone from DB"); + }); + + test("entire slice directory deleted → derive produces valid state", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Delete entire S01 directory + rmSync(join(base, ".gsd", "milestones", "M001", "slices", "S01"), { recursive: true, force: true }); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + // DB still has slice/task rows, disk is gone — state should degrade gracefully + assert.ok(state.phase, "should produce valid phase after slice dir deletion"); + }); + + test("task PLAN file deleted between dispatch and execution → recovery dispatch", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Delete T01-PLAN.md + const planPath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-PLAN.md"); + unlinkSync(planPath); + + // Also write milestone RESEARCH so research-slice rule doesn't fire first + writeFileSync( + join(base, ".gsd", "milestones", "M001", "M001-RESEARCH.md"), + "# Research\nDone.\n", + ); + // Write slice RESEARCH so research-slice rule for non-S01 doesn't fire + writeFileSync( + join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-RESEARCH.md"), + "# S01 Research\nDone.\n", + ); + + const { resolveDispatch } = await import("../../auto-dispatch.ts"); + + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + + const ctx = { + basePath: base, + mid: "M001", + midTitle: "Active", + state, + prefs: undefined, + }; + + const result = await resolveDispatch(ctx); + // The "executing → execute-task (recover missing task plan)" rule should + // detect missing T01-PLAN.md and dispatch plan-slice instead of execute-task + if (result.action === "dispatch") { + assert.equal( + (result as any).unitType, + "plan-slice", + "missing task plan should trigger plan-slice recovery", + ); + } + // It's also valid if the state changed due to cache invalidation + assert.ok(result.action, "should produce a valid dispatch action"); + }); + + test("worktree directory disappearance: isGhostMilestone still works", () => { + const tmpBase = makeTempDir(); + const mDir = join(tmpBase, ".gsd", "milestones", "M001"); + mkdirSync(mDir, { recursive: true }); + + // Create worktree dir then delete it (simulates external deletion) + const wtDir = join(tmpBase, ".gsd", "worktrees", "M001"); + mkdirSync(wtDir, { recursive: true }); + + // With worktree → not a ghost + assert.equal(isGhostMilestone(tmpBase, "M001"), false, "with worktree: not ghost"); + + // Delete worktree (simulates external process removing it) + rmSync(wtDir, { recursive: true, force: true }); + assert.ok(!existsSync(wtDir), "worktree should be gone"); + + // Without worktree AND without DB → ghost (existsSync handles missing dir) + assert.equal(isGhostMilestone(tmpBase, "M001"), true, "without worktree: ghost"); + + rmSync(tmpBase, { recursive: true, force: true }); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 7: Graduated Error Recovery in Auto-Loop +// ───────────────────────────────────────────────────────────────────────── + +describe("graduated error recovery logic", () => { + test("infrastructure error codes are exhaustive and non-overlapping", () => { + // Verify the set contains only OS-level error codes + for (const code of INFRA_ERROR_CODES) { + assert.ok(code.startsWith("E"), `infra code ${code} should start with E`); + assert.ok(code.length >= 4, `infra code ${code} should be at least 4 chars`); + } + }); + + test("SQLite corruption detection via message scan (no code property)", () => { + // Simulates sql.js or better-sqlite3 error without proper Node code + const err = new Error("SqliteError: database disk image is malformed"); + const result = isInfrastructureError(err); + assert.equal(result, "SQLITE_CORRUPT"); + }); + + test("provider rate limit is NOT an infrastructure error (retryable)", () => { + const err = new Error("rate_limit_exceeded: Too many requests"); + assert.equal(isInfrastructureError(err), null); + }); + + test("overloaded_error is NOT an infrastructure error (retryable)", () => { + const err = new Error("overloaded_error: The model is currently overloaded"); + assert.equal(isInfrastructureError(err), null); + }); + + test("authentication error is NOT an infrastructure error", () => { + const err = new Error("authentication_error: Invalid API key"); + assert.equal(isInfrastructureError(err), null); + }); + + test("permission denied (EACCES) is NOT in infrastructure set", () => { + // EACCES is intentionally not in the set — it may indicate a fixable + // permissions issue rather than a hardware-level failure + const err = Object.assign(new Error("permission denied"), { code: "EACCES" }); + assert.equal(isInfrastructureError(err), null); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 8: Multi-Iteration Stuck Scenarios +// ───────────────────────────────────────────────────────────────────────── + +describe("multi-iteration stuck scenarios", () => { + test("progressive window: normal → stuck after 3rd same unit", () => { + const window: WindowEntry[] = []; + + window.push({ key: "A" }); + assert.equal(detectStuck(window), null, "1 entry: not stuck"); + + window.push({ key: "A" }); + assert.equal(detectStuck(window), null, "2 entries: not stuck yet"); + + window.push({ key: "A" }); + assert.ok(detectStuck(window)?.stuck, "3 entries: stuck"); + }); + + test("progressive window: oscillation builds up", () => { + const window: WindowEntry[] = []; + + window.push({ key: "A" }); + assert.equal(detectStuck(window), null); + + window.push({ key: "B" }); + assert.equal(detectStuck(window), null); + + window.push({ key: "A" }); + assert.equal(detectStuck(window), null, "3 entries A→B→A: not stuck yet"); + + window.push({ key: "B" }); + assert.ok(detectStuck(window)?.stuck, "4 entries A→B→A→B: stuck"); + }); + + test("mixed progress then stuck: A→B→C→C→C → stuck on C", () => { + const window: WindowEntry[] = [ + { key: "A" }, + { key: "B" }, + { key: "C" }, + { key: "C" }, + { key: "C" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck, "3 consecutive C: stuck"); + assert.ok(result?.reason.includes("C"), "reason should mention stuck unit"); + }); + + test("error in middle of window does not false-positive", () => { + const window: WindowEntry[] = [ + { key: "A" }, + { key: "B", error: "transient failure" }, + { key: "C" }, + { key: "D" }, + ]; + assert.equal(detectStuck(window), null, "single error should not trigger stuck"); + }); + + test("consecutive errors on different keys still triggers Rule 1", () => { + const window: WindowEntry[] = [ + { key: "A", error: "Provider returned 503 Service Unavailable" }, + { key: "B", error: "Provider returned 503 Service Unavailable" }, + ]; + const result = detectStuck(window); + assert.ok(result?.stuck, "same error on different keys: stuck by Rule 1"); + }); +}); + +// ───────────────────────────────────────────────────────────────────────── +// SECTION 9: State Consistency Under Concurrent DB Operations +// ───────────────────────────────────────────────────────────────────────── + +describe("state consistency under DB mutations", () => { + let base: string; + + afterEach(() => { + try { closeDatabase(); } catch { /* may not be open */ } + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("rapid DB mutations produce consistent deriveStateFromDb results", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Rapid mutations with invalidation between each + invalidateAllCaches(); + const states: string[] = []; + + const s1 = await deriveStateFromDb(base); + states.push(s1.phase); + + // pending → complete + const { updateTaskStatus } = await import("../../gsd-db.ts"); + updateTaskStatus("M001", "S01", "T01", "complete", new Date().toISOString()); + invalidateAllCaches(); + const s2 = await deriveStateFromDb(base); + states.push(s2.phase); + + // S01 should now be summarizing (all tasks done) + assert.equal(states[0], "executing", "initially executing"); + assert.equal(states[1], "summarizing", "after task complete → summarizing"); + + // No state should be undefined or null + for (const phase of states) { + assert.ok(phase, "every state should have a valid phase"); + } + }); + + test("DB milestone status change is reflected after cache invalidation", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "complete" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" }); + + invalidateAllCaches(); + const s1 = await deriveStateFromDb(base); + assert.equal(s1.phase, "validating-milestone"); + + // Mark milestone complete directly + const { updateMilestoneStatus } = await import("../../gsd-db.ts"); + updateMilestoneStatus("M001", "complete", new Date().toISOString()); + // Write SUMMARY to make it truly complete + writeFileSync( + join(base, ".gsd", "milestones", "M001", "M001-SUMMARY.md"), + "# M001 Summary\nDone.\n", + ); + + invalidateAllCaches(); + const s2 = await deriveStateFromDb(base); + // With only M001 and it's complete, should be "complete" + assert.equal(s2.phase, "complete", "after milestone completion should be complete"); + }); + + test("deriveState is idempotent: same inputs produce same outputs", async () => { + base = createMinimalFixture(); + openDatabase(join(base, ".gsd", "gsd.db")); + insertMilestone({ id: "M001", title: "Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Feature", status: "in_progress" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "pending" }); + + // Call deriveState 5 times with cache invalidation between each + const results: string[] = []; + for (let i = 0; i < 5; i++) { + invalidateAllCaches(); + const state = await deriveStateFromDb(base); + results.push(state.phase); + } + + // All should be identical + const unique = new Set(results); + assert.equal(unique.size, 1, `expected all identical, got: ${[...unique].join(", ")}`); + assert.equal(results[0], "executing"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/interactive-routing-bypass.test.ts b/src/resources/extensions/gsd/tests/interactive-routing-bypass.test.ts new file mode 100644 index 000000000..f209ecc8d --- /dev/null +++ b/src/resources/extensions/gsd/tests/interactive-routing-bypass.test.ts @@ -0,0 +1,207 @@ +// GSD Extension — Interactive Routing Bypass Tests +// Verifies that dynamic routing is skipped for interactive (guided-flow) dispatches +// and that model downgrade notifications always fire (#3962). +// Copyright (c) 2026 Jeremy McSpadden + +import test, { describe } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +// ─── Source-level structural tests ────────────────────────────────────────── + +const modelSelectionSrc = readFileSync( + join(__dirname, "..", "auto-model-selection.ts"), + "utf-8", +); + +const guidedFlowSrc = readFileSync( + join(__dirname, "..", "guided-flow.ts"), + "utf-8", +); + +const autoStartSrc = readFileSync( + join(__dirname, "..", "auto-start.ts"), + "utf-8", +); + +describe("interactive routing bypass (#3962)", () => { + test("selectAndApplyModel accepts isAutoMode parameter", () => { + // The function signature should include isAutoMode with a default of true + assert.ok( + modelSelectionSrc.includes("isAutoMode"), + "selectAndApplyModel should have isAutoMode parameter", + ); + assert.ok( + modelSelectionSrc.includes("isAutoMode = true"), + "isAutoMode should default to true (auto-mode behavior preserved)", + ); + }); + + test("routing is disabled when isAutoMode is false", () => { + // The code should disable routing when not in auto-mode + assert.ok( + modelSelectionSrc.includes("if (!isAutoMode)"), + "should check isAutoMode flag to disable routing", + ); + assert.ok( + modelSelectionSrc.includes("routingConfig.enabled = false"), + "should set routingConfig.enabled = false for interactive mode", + ); + }); + + test("resolvePreferredModelConfig skips routing synthesis when isAutoMode is false", () => { + // resolvePreferredModelConfig should accept isAutoMode and bail early + // before synthesizing a routing ceiling from tier_models (#3962 codex review) + assert.ok( + modelSelectionSrc.includes("function resolvePreferredModelConfig"), + "resolvePreferredModelConfig should exist", + ); + // The function should check isAutoMode before routing synthesis + const fnIdx = modelSelectionSrc.indexOf("function resolvePreferredModelConfig"); + const fnBody = modelSelectionSrc.slice(fnIdx, fnIdx + 600); + assert.ok( + fnBody.includes("isAutoMode"), + "resolvePreferredModelConfig should accept isAutoMode parameter", + ); + assert.ok( + fnBody.includes("if (!isAutoMode) return undefined"), + "should return undefined (skip routing synthesis) when not in auto-mode", + ); + }); + + test("selectAndApplyModel threads isAutoMode to resolvePreferredModelConfig", () => { + // The call to resolvePreferredModelConfig inside selectAndApplyModel + // should pass isAutoMode as the third argument + const callSite = "resolvePreferredModelConfig(unitType, autoModeStartModel, isAutoMode)"; + assert.ok( + modelSelectionSrc.includes(callSite), + "selectAndApplyModel should pass isAutoMode to resolvePreferredModelConfig", + ); + }); + + test("guided-flow passes isAutoMode=false", () => { + // guided-flow.ts should explicitly pass isAutoMode as false + assert.ok( + guidedFlowSrc.includes("/* isAutoMode */ false"), + "guided-flow should pass isAutoMode=false to selectAndApplyModel", + ); + }); + + test("auto/phases.ts does NOT pass isAutoMode=false", () => { + // auto/phases.ts should use the default (true) — it's auto-mode + const phasesSrc = readFileSync( + join(__dirname, "..", "auto", "phases.ts"), + "utf-8", + ); + assert.ok( + !phasesSrc.includes("isAutoMode"), + "auto/phases.ts should use default isAutoMode=true (not pass it explicitly)", + ); + }); +}); + +describe("model downgrade notifications always visible (#3962)", () => { + test("downgrade notification is not gated by verbose flag", () => { + // The downgrade notification block should NOT be wrapped in `if (verbose)` + // Find the downgrade block and verify it's not behind a verbose check + const downgradeBlock = "if (routingResult.wasDowngraded)"; + const downgradeIdx = modelSelectionSrc.indexOf(downgradeBlock); + assert.ok(downgradeIdx > 0, "downgrade block should exist"); + + // Extract the code between wasDowngraded check and the next routing label assignment + const afterDowngrade = modelSelectionSrc.slice( + downgradeIdx, + modelSelectionSrc.indexOf("routingTierLabel =", downgradeIdx), + ); + + // The notification calls should NOT be wrapped in `if (verbose)` + assert.ok( + !afterDowngrade.includes("if (verbose)"), + "downgrade notifications should not be gated by verbose flag", + ); + + // But the notification calls should exist + assert.ok( + afterDowngrade.includes('ctx.ui.notify('), + "downgrade notifications should still fire", + ); + }); + + test("tier escalation notification is not gated by verbose flag", () => { + // Extract the escalation block: from "if (escalated)" to its closing + // and verify the notification is present but `if (verbose)` is not. + const escalatedIdx = modelSelectionSrc.indexOf("if (escalated)"); + assert.ok(escalatedIdx > 0, "escalation block should exist"); + + // Get the block from "if (escalated)" to the next closing brace pattern + const block = modelSelectionSrc.slice(escalatedIdx, escalatedIdx + 400); + assert.ok( + block.includes("Tier escalation:"), + "escalation block should contain the notification", + ); + assert.ok( + !block.includes("if (verbose)"), + "escalation block should not gate notification behind verbose flag", + ); + }); +}); + +describe("auto-mode start routing banner (#3962)", () => { + test("auto-start shows dynamic routing status on startup", () => { + assert.ok( + autoStartSrc.includes("Dynamic routing:"), + "auto-start should display routing status banner", + ); + assert.ok( + autoStartSrc.includes("resolveDynamicRoutingConfig"), + "auto-start should import resolveDynamicRoutingConfig", + ); + }); + + test("banner shows different messages for enabled vs disabled routing", () => { + assert.ok( + autoStartSrc.includes("Dynamic routing: enabled"), + "should show message when routing is enabled", + ); + assert.ok( + autoStartSrc.includes("Dynamic routing: disabled"), + "should show message when routing is disabled", + ); + }); + + test("banner shows the ceiling model", () => { + assert.ok( + autoStartSrc.includes("startModelLabel"), + "banner should reference the start/ceiling model", + ); + }); + + test("banner accounts for flat-rate provider suppression", () => { + // The banner should check isFlatRateProvider to accurately reflect + // whether routing will actually be active at dispatch time (#3962 codex review) + assert.ok( + autoStartSrc.includes("isFlatRateProvider"), + "banner should check flat-rate provider status", + ); + assert.ok( + autoStartSrc.includes("effectivelyEnabled"), + "banner should compute effective routing state, not just raw config", + ); + }); + + test("banner uses effective ceiling from tier_models.heavy when configured", () => { + // The actual ceiling may come from tier_models.heavy, not the start model + assert.ok( + autoStartSrc.includes("tier_models?.heavy"), + "banner should check tier_models.heavy for the effective ceiling", + ); + assert.ok( + autoStartSrc.includes("effectiveCeiling"), + "banner should compute the effective ceiling model", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/interrupted-session-auto.test.ts b/src/resources/extensions/gsd/tests/interrupted-session-auto.test.ts new file mode 100644 index 000000000..38f6a4c81 --- /dev/null +++ b/src/resources/extensions/gsd/tests/interrupted-session-auto.test.ts @@ -0,0 +1,146 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { assessInterruptedSession } from "../interrupted-session.ts"; + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-auto-interrupted-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* */ } +} + +function writeRoadmap(base: string, checked = false): void { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(join(milestoneDir, "slices", "S01", "tasks"), { recursive: true }); + writeFileSync( + join(milestoneDir, "M001-ROADMAP.md"), + [ + "# M001: Test Milestone", + "", + "## Vision", + "", + "Test milestone.", + "", + "## Success Criteria", + "", + "- It works.", + "", + "## Slices", + "", + `- [${checked ? "x" : " "}] **S01: Test slice** \`risk:low\``, + " After this: Demo", + "", + "## Boundary Map", + "", + "- S01 → terminal", + " - Produces: done", + " - Consumes: nothing", + ].join("\n"), + "utf-8", + ); +} + +function writeCompleteArtifacts(base: string): void { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + const sliceDir = join(milestoneDir, "slices", "S01"); + mkdirSync(sliceDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n", "utf-8"); + writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n", "utf-8"); + writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\nDone.\n", "utf-8"); +} + +function writeLock(base: string, unitType: string, unitId: string): void { + writeFileSync( + join(base, ".gsd", "auto.lock"), + JSON.stringify({ + pid: 999999999, + startedAt: new Date().toISOString(), + unitType, + unitId, + unitStartedAt: new Date().toISOString(), + }, null, 2), + "utf-8", + ); +} + +function writePausedSession(base: string, milestoneId = "M001", stepMode = false): void { + const runtimeDir = join(base, ".gsd", "runtime"); + mkdirSync(runtimeDir, { recursive: true }); + writeFileSync( + join(runtimeDir, "paused-session.json"), + JSON.stringify({ milestoneId, originalBasePath: base, stepMode }, null, 2), + "utf-8", + ); +} + +test("direct /gsd auto stale complete repo yields stale classification with no recovery payload", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, true); + writeCompleteArtifacts(base); + writeLock(base, "execute-task", "M001/S01/T01"); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "stale"); + assert.equal(assessment.recoveryPrompt, null); + assert.equal(assessment.hasResumableDiskState, false); + } finally { + cleanup(base); + } +}); + +test("direct /gsd auto paused-session metadata remains recoverable when work is unfinished", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, false); + writePausedSession(base, "M001", false); + writeLock(base, "execute-task", "M001/S01/T01"); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "recoverable"); + assert.equal(assessment.pausedSession?.milestoneId, "M001"); + } finally { + cleanup(base); + } +}); + +test("direct /gsd auto stale paused-session metadata is treated as stale when no resumable work remains", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, true); + writeCompleteArtifacts(base); + writePausedSession(base, "M999", true); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "stale"); + assert.equal(assessment.hasResumableDiskState, false); + } finally { + cleanup(base); + } +}); + +test("direct /gsd auto source only resumes paused-session metadata for recoverable state with real recovery signals", async () => { + const source = await import(`node:fs/promises`).then((fs) => + fs.readFile(new URL("../auto.ts", import.meta.url), "utf-8") + ); + assert.ok(source.includes('const shouldResumePausedSession =')); + assert.ok(source.includes('freshStartAssessment.classification === "recoverable"')); + assert.ok(source.includes('&& (')); + assert.ok(source.includes('freshStartAssessment.hasResumableDiskState')); + assert.ok(source.includes('|| !!freshStartAssessment.recoveryPrompt')); + assert.ok(source.includes('|| !!freshStartAssessment.lock')); +}); + +test("auto module imports successfully after interrupted-session changes", async () => { + const mod = await import(`../auto.ts?ts=${Date.now()}-${Math.random()}`); + assert.equal(typeof mod.startAuto, "function"); + assert.equal(typeof mod.pauseAuto, "function"); +}); diff --git a/src/resources/extensions/gsd/tests/interrupted-session-ui.test.ts b/src/resources/extensions/gsd/tests/interrupted-session-ui.test.ts new file mode 100644 index 000000000..21a6ca2ce --- /dev/null +++ b/src/resources/extensions/gsd/tests/interrupted-session-ui.test.ts @@ -0,0 +1,136 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { assessInterruptedSession } from "../interrupted-session.ts"; + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-smart-entry-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* */ } +} + +function writeRoadmap(base: string, checked = false): void { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(join(milestoneDir, "slices", "S01", "tasks"), { recursive: true }); + writeFileSync( + join(milestoneDir, "M001-ROADMAP.md"), + [ + "# M001: Test Milestone", + "", + "## Vision", + "", + "Test milestone.", + "", + "## Success Criteria", + "", + "- It works.", + "", + "## Slices", + "", + `- [${checked ? "x" : " "}] **S01: Test slice** \`risk:low\``, + " After this: Demo", + "", + "## Boundary Map", + "", + "- S01 → terminal", + " - Produces: done", + " - Consumes: nothing", + ].join("\n"), + "utf-8", + ); +} + +function writeCompleteArtifacts(base: string): void { + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + const sliceDir = join(milestoneDir, "slices", "S01"); + mkdirSync(sliceDir, { recursive: true }); + writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# Summary\nDone.\n", "utf-8"); + writeFileSync(join(sliceDir, "S01-UAT.md"), "# UAT\nPassed.\n", "utf-8"); + writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\nDone.\n", "utf-8"); +} + +function writePausedSession(base: string, milestoneId = "M001", stepMode = false): void { + const runtimeDir = join(base, ".gsd", "runtime"); + mkdirSync(runtimeDir, { recursive: true }); + writeFileSync( + join(runtimeDir, "paused-session.json"), + JSON.stringify({ milestoneId, originalBasePath: base, stepMode }, null, 2), + "utf-8", + ); +} + +function writeLock(base: string, unitType: string, unitId: string): void { + writeFileSync( + join(base, ".gsd", "auto.lock"), + JSON.stringify({ + pid: 999999999, + startedAt: new Date().toISOString(), + unitType, + unitId, + unitStartedAt: new Date().toISOString(), + }, null, 2), + "utf-8", + ); +} + +test("guided-flow stale complete scenario classifies as stale so the resume prompt can be suppressed", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, true); + writeCompleteArtifacts(base); + writeLock(base, "execute-task", "M001/S01/T01"); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "stale"); + assert.equal(assessment.recoveryPrompt, null); + } finally { + cleanup(base); + } +}); + +test("guided-flow paused-session scenario classifies as recoverable so resume remains available", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, false); + writePausedSession(base); + writeLock(base, "execute-task", "M001/S01/T01"); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "recoverable"); + assert.equal(assessment.pausedSession?.milestoneId, "M001"); + } finally { + cleanup(base); + } +}); + +test("guided-flow stale paused-session scenario is suppressed when no resumable work remains", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, true); + writeCompleteArtifacts(base); + writePausedSession(base, "M999", true); + + const assessment = await assessInterruptedSession(base); + assert.equal(assessment.classification, "stale"); + assert.equal(assessment.hasResumableDiskState, false); + } finally { + cleanup(base); + } +}); + +test("guided-flow source uses step-aware resume and clears stale paused metadata without changing discuss handoff semantics", () => { + const source = readFileSync(join(import.meta.dirname, "..", "guided-flow.ts"), "utf-8"); + assert.ok(source.includes('const interrupted = await assessInterruptedSession(basePath);')); + assert.ok(source.includes('resumeLabel = interrupted.pausedSession?.stepMode')); + assert.ok(source.includes('step: interrupted.pausedSession?.stepMode ?? false')); + assert.ok(source.includes('unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json"))')); + assert.ok(source.includes('pendingAutoStartMap.set(basePath,')); +}); diff --git a/src/resources/extensions/gsd/tests/isolation-none-branch-guard.test.ts b/src/resources/extensions/gsd/tests/isolation-none-branch-guard.test.ts new file mode 100644 index 000000000..5acf71583 --- /dev/null +++ b/src/resources/extensions/gsd/tests/isolation-none-branch-guard.test.ts @@ -0,0 +1,62 @@ +/** + * Regression test for #3675 — isolation:none stale branch guard + * + * When switching from isolation:branch/worktree to isolation:none, HEAD + * could remain on a milestone/ branch. The fix in auto-start.ts + * detects this and auto-checks out to the integration branch. + * + * This structural test verifies the milestone/ branch check exists + * in auto-start.ts. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'auto-start.ts'), 'utf-8'); + +describe('isolation:none stale branch guard (#3675)', () => { + test('checks for milestone/ branch prefix', () => { + assert.match(source, /startsWith\(["']milestone\//, + 'auto-start should check for milestone/ branch prefix'); + }); + + test('imports nativeGetCurrentBranch', () => { + assert.match(source, /nativeGetCurrentBranch/, + 'auto-start should import nativeGetCurrentBranch'); + }); + + test('imports nativeDetectMainBranch', () => { + assert.match(source, /nativeDetectMainBranch/, + 'auto-start should import nativeDetectMainBranch'); + }); + + test('imports nativeCheckoutBranch', () => { + assert.match(source, /nativeCheckoutBranch/, + 'auto-start should import nativeCheckoutBranch'); + }); + + test('guard is conditional on isolation mode "none"', () => { + assert.match(source, /getIsolationMode\(\)\s*===\s*["']none["']/, + 'guard should only activate when isolation mode is "none"'); + }); + + test('calls nativeCheckoutBranch to return to integration branch', () => { + assert.match(source, /nativeCheckoutBranch\(base,\s*integrationBranch\)/, + 'should checkout to the integration branch'); + }); + + test('guard is wrapped in try-catch (non-fatal)', () => { + // Find the milestone/ check and verify it is inside a try block + const milestoneIdx = source.indexOf('startsWith("milestone/")'); + assert.ok(milestoneIdx > 0, 'milestone/ check should exist'); + const before = source.slice(Math.max(0, milestoneIdx - 500), milestoneIdx); + assert.match(before, /try\s*\{/, + 'milestone branch guard should be inside a try block'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/journal-integration.test.ts b/src/resources/extensions/gsd/tests/journal-integration.test.ts index 846982e26..c05c6b3fc 100644 --- a/src/resources/extensions/gsd/tests/journal-integration.test.ts +++ b/src/resources/extensions/gsd/tests/journal-integration.test.ts @@ -72,7 +72,7 @@ function makeMockDeps( getCurrentBranch: () => "main", autoWorktreeBranch: () => "auto/M001", resolveMilestoneFile: () => null, - reconcileMergeState: () => false, + reconcileMergeState: () => "clean", getLedger: () => ({ units: [] }), getProjectTotals: () => ({ cost: 0 }), formatCost: (c: number) => `$${c.toFixed(2)}`, @@ -216,7 +216,7 @@ test("runDispatch emits dispatch-match with correct rule and flowId", async () = mid: "M001", midTitle: "Test Milestone", }; - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const result = await runDispatch(ic, preData, loopState); @@ -248,7 +248,7 @@ test("runDispatch emits dispatch-stop when dispatch returns stop action", async mid: "M001", midTitle: "Test", }; - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const result = await runDispatch(ic, preData, loopState); assert.equal(result.action, "break"); @@ -303,6 +303,7 @@ test("runDispatch checks prior-slice completion against the project root in work const result = await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, + consecutiveFinalizeTimeouts: 0, }); assert.equal(result.action, "next"); @@ -343,7 +344,7 @@ test("runUnitPhase emits unit-start and unit-end with causedBy reference", async isRetry: false, previousTier: undefined, }; - const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; // Start runUnitPhase (it will block on runUnit internally) const unitPromise = runUnitPhase(ic, iterData, loopState); @@ -400,7 +401,7 @@ test("all events from a mock iteration have monotonically increasing seq and sam mid: "M001", midTitle: "Test", }; - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const dispatchResult = await runDispatch(ic, preData, loopState); assert.equal(dispatchResult.action, "next"); @@ -446,7 +447,7 @@ test("dispatch-match events include matchedRule field matching the rule name", a midTitle: "Test", }; - await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 }); + await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }); const matchEvents = capture.events.filter(e => e.eventType === "dispatch-match"); assert.equal(matchEvents.length, 1); @@ -475,7 +476,7 @@ test("pre-dispatch-hook event is emitted when hooks fire", async () => { midTitle: "Test", }; - await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 }); + await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }); const hookEvents = capture.events.filter(e => e.eventType === "pre-dispatch-hook"); assert.equal(hookEvents.length, 1, "should emit one pre-dispatch-hook event"); @@ -497,7 +498,7 @@ test("terminal event is emitted on milestone-complete", async () => { }) as any, }); const ic = makeIC(deps); - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const result = await runPreDispatch(ic, loopState); assert.equal(result.action, "break"); @@ -521,7 +522,7 @@ test("terminal event is emitted on blocked state", async () => { }) as any, }); const ic = makeIC(deps); - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const result = await runPreDispatch(ic, loopState); assert.equal(result.action, "break"); @@ -550,7 +551,7 @@ test("milestone-transition event is emitted when milestone changes", async () => const ic = makeIC(deps); // Session says current milestone is M001, but state will return M002 ic.s.currentMilestoneId = "M001"; - const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; await runPreDispatch(ic, loopState); @@ -580,7 +581,7 @@ test("unit-end event contains errorContext when unit is cancelled with structure isRetry: false, previousTier: undefined, }; - const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 }; + const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 }; const unitPromise = runUnitPhase(ic, iterData, loopState); await new Promise(r => setTimeout(r, 50)); @@ -589,9 +590,9 @@ test("unit-end event contains errorContext when unit is cancelled with structure resolveAgentEndCancelled({ message: "Hard timeout error: exceeded limit", category: "timeout", isTransient: true }); const result = await unitPromise; - // Cancelled units break the loop before emitting unit-end + // Transient timeout cancellations pause (recoverable) instead of hard-stopping assert.equal(result.action, "break"); - assert.equal((result as any).reason, "session-failed"); + assert.equal((result as any).reason, "session-timeout"); // Verify error classification used structured errorContext on the window entry const entry = loopState.recentUnits[loopState.recentUnits.length - 1]; diff --git a/src/resources/extensions/gsd/tests/mcp-project-config.test.ts b/src/resources/extensions/gsd/tests/mcp-project-config.test.ts new file mode 100644 index 000000000..7638a7e74 --- /dev/null +++ b/src/resources/extensions/gsd/tests/mcp-project-config.test.ts @@ -0,0 +1,89 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + ensureProjectWorkflowMcpConfig, + GSD_WORKFLOW_MCP_SERVER_NAME, +} from "../mcp-project-config.ts"; + +test("ensureProjectWorkflowMcpConfig creates .mcp.json with the workflow server", () => { + const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-init-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + + try { + const result = ensureProjectWorkflowMcpConfig(projectRoot); + assert.equal(result.status, "created"); + assert.equal(existsSync(result.configPath), true); + + const parsed = JSON.parse(readFileSync(result.configPath, "utf-8")) as { + mcpServers?: Record }>; + }; + const server = parsed.mcpServers?.[GSD_WORKFLOW_MCP_SERVER_NAME]; + assert.ok(server, "workflow server should be written to mcpServers"); + assert.equal(typeof server?.command, "string"); + assert.equal(Array.isArray(server?.args), true); + assert.equal(server?.env?.GSD_WORKFLOW_PROJECT_ROOT, projectRoot); + assert.match(server?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(server?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); + if ((server?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "").endsWith(".ts")) { + assert.match(server?.env?.NODE_OPTIONS ?? "", /--experimental-strip-types/); + assert.match(server?.env?.NODE_OPTIONS ?? "", /resolve-ts\.mjs/); + } + } finally { + rmSync(projectRoot, { recursive: true, force: true }); + } +}); + +test("ensureProjectWorkflowMcpConfig preserves existing mcp servers", () => { + const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-init-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + const configPath = join(projectRoot, ".mcp.json"); + + writeFileSync( + configPath, + `${JSON.stringify({ + mcpServers: { + railway: { + command: "npx", + args: ["railway-mcp"], + }, + }, + }, null, 2)}\n`, + "utf-8", + ); + + try { + const result = ensureProjectWorkflowMcpConfig(projectRoot); + assert.equal(result.status, "updated"); + + const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as { + mcpServers?: Record; + }; + assert.deepEqual(parsed.mcpServers?.railway, { + command: "npx", + args: ["railway-mcp"], + }); + assert.ok(parsed.mcpServers?.[GSD_WORKFLOW_MCP_SERVER_NAME]); + } finally { + rmSync(projectRoot, { recursive: true, force: true }); + } +}); + +test("ensureProjectWorkflowMcpConfig is idempotent when config is already current", () => { + const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-init-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + + try { + const first = ensureProjectWorkflowMcpConfig(projectRoot); + const second = ensureProjectWorkflowMcpConfig(projectRoot); + + assert.equal(first.status, "created"); + assert.equal(second.status, "unchanged"); + assert.equal(first.configPath, second.configPath); + } finally { + rmSync(projectRoot, { recursive: true, force: true }); + } +}); diff --git a/src/resources/extensions/gsd/tests/mcp-status.test.ts b/src/resources/extensions/gsd/tests/mcp-status.test.ts index 97258fb2b..3a036aeb0 100644 --- a/src/resources/extensions/gsd/tests/mcp-status.test.ts +++ b/src/resources/extensions/gsd/tests/mcp-status.test.ts @@ -2,6 +2,7 @@ import test, { describe } from "node:test"; import assert from "node:assert/strict"; import { + formatMcpInitResult, formatMcpStatusReport, formatMcpServerDetail, type McpServerStatus, @@ -101,3 +102,17 @@ describe("formatMcpServerDetail", () => { assert.match(result, /disconnected/i); }); }); + +describe("formatMcpInitResult", () => { + test("shows created message with config path", () => { + const result = formatMcpInitResult("created", "/tmp/project/.mcp.json", "/tmp/project"); + assert.match(result, /created project mcp config/i); + assert.match(result, /\/tmp\/project\/\.mcp\.json/); + assert.match(result, /claude code/i); + }); + + test("shows unchanged message when config is current", () => { + const result = formatMcpInitResult("unchanged", "/tmp/project/.mcp.json", "/tmp/project"); + assert.match(result, /already up to date/i); + }); +}); diff --git a/src/resources/extensions/gsd/tests/measurement.test.ts b/src/resources/extensions/gsd/tests/measurement.test.ts new file mode 100644 index 000000000..25785d10f --- /dev/null +++ b/src/resources/extensions/gsd/tests/measurement.test.ts @@ -0,0 +1,531 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { + queryKnowledge, + formatRoadmapExcerpt, +} from '../context-store.ts'; + +// ═══════════════════════════════════════════════════════════════════════════ +// measurement.test.ts — Verify ≥40% context reduction from scoped injection +// +// Tests queryKnowledge() and formatRoadmapExcerpt() with realistic synthetic +// fixtures to confirm the context reduction target is met. +// ═══════════════════════════════════════════════════════════════════════════ + +// ─── Synthetic KNOWLEDGE.md Fixture (~8KB, 9 H2 sections) ────────────────── + +const syntheticKnowledge = `# Project Knowledge Base + +## Database Patterns +SQLite is the primary persistence layer, using WAL mode for concurrent reads. +All queries use prepared statements for SQL injection prevention. +Connection pooling is handled by better-sqlite3's synchronous API. +Schema migrations are versioned and applied at startup. + +Example patterns: +- Use transactions for multi-statement operations +- Prefer RETURNING clause for insert/update +- Index foreign keys for join performance +- Use CHECK constraints for data validation + +Performance considerations: +- WAL checkpoint every 1000 writes +- Vacuum on shutdown for space reclamation +- Page size 4096 for SSD optimization + +Database schema evolution: +- Migrations stored in migrations/ directory +- Each migration has up/down scripts +- Version table tracks applied migrations +- Rollback supported for last N migrations + +Connection management: +- Single connection for write operations +- Read connections pooled for concurrency +- Connection timeout set to 5 seconds +- Busy timeout handles lock contention + +Query patterns: +- Use prepared statements for parameterization +- Batch inserts via INSERT ... VALUES syntax +- Upserts via INSERT OR REPLACE +- Pagination via LIMIT/OFFSET or cursor + +## API Design Principles +REST endpoints follow OpenAPI 3.0 specification. +Versioned paths use /v1/resource pattern. +Authentication uses Bearer tokens in Authorization header. +Rate limiting applies per-client with sliding window algorithm. + +Response formats: +- Success: { data: T, meta?: { pagination } } +- Error: { error: { code, message, details? } } +- Pagination: cursor-based for large collections + +Content negotiation: +- Accept: application/json (default) +- Accept: text/plain (for CLI consumers) +- Accept: text/event-stream (for SSE endpoints) + +API versioning strategy: +- Major versions in URL path (/v1, /v2) +- Minor versions via Accept-Version header +- Deprecation warnings in response headers +- 12-month sunset period for old versions + +Endpoint naming conventions: +- Nouns for resources (users, projects) +- Verbs only for non-CRUD actions (login, export) +- Plural form for collections +- Singular for singletons (me, config) + +HTTP method semantics: +- GET: read-only, cacheable +- POST: create or non-idempotent action +- PUT: full replacement +- PATCH: partial update +- DELETE: remove resource + +## Testing Strategy +Unit tests use node:test with strict assertions. +Integration tests mock external services via msw. +E2E tests use Playwright for browser automation. +Test coverage target is 80% line coverage. + +Test organization: +- Unit tests adjacent to source files (*.test.ts) +- Integration tests in __tests__/integration/ +- E2E tests in e2e/ directory +- Fixtures in __fixtures__/ subdirectories + +Mocking guidelines: +- Prefer dependency injection over global mocks +- Use vi.mock() sparingly, only for ES module boundaries +- Reset mocks in afterEach hooks + +Test data management: +- Factories generate realistic test data +- Seeds populate database for integration tests +- Snapshots capture expected output +- Golden files for complex comparisons + +Assertion patterns: +- Use strict equality for primitives +- Deep equality for objects/arrays +- Regex matching for dynamic content +- Snapshot testing for UI components + +Test isolation: +- Each test gets fresh database state +- Environment variables reset between tests +- File system operations use temp directories +- Network calls intercepted by mock server + +## Error Handling +Errors are typed using discriminated unions. +Application errors extend BaseError class. +HTTP errors map to standard status codes. +Unhandled rejections trigger graceful shutdown. + +Error codes follow domain prefixes: +- AUTH_xxx: Authentication/authorization errors +- DB_xxx: Database operation failures +- NET_xxx: Network/external service errors +- VAL_xxx: Validation errors + +Logging integration: +- Error instances auto-serialize to JSON +- Stack traces included in development +- Correlation IDs propagate through request chain + +Error recovery strategies: +- Retry with exponential backoff for transient errors +- Circuit breaker for external service failures +- Fallback values for non-critical operations +- Graceful degradation for partial failures + +User-facing error messages: +- Generic messages for security-sensitive errors +- Actionable guidance for recoverable errors +- Reference codes for support escalation +- Localized messages via i18n + +Error boundary patterns: +- Component-level boundaries in UI +- Route-level error handlers in API +- Global unhandled rejection handlers +- Process-level crash recovery + +## Observability Patterns +Structured logging uses pino with JSON output. +Metrics collected via OpenTelemetry SDK. +Traces propagate context through async boundaries. +Health checks exposed at /health and /ready endpoints. + +Log levels: +- ERROR: Unrecoverable failures +- WARN: Degraded operation +- INFO: Significant state changes +- DEBUG: Detailed diagnostic data + +Metric types: +- Counters for request counts +- Histograms for latency distribution +- Gauges for resource utilization + +Trace context propagation: +- W3C Trace Context headers +- Baggage for cross-service metadata +- Span attributes for searchability +- Events for significant moments + +Dashboard design: +- SLO dashboards for reliability +- Request flow visualization +- Error rate trends +- Resource saturation alerts + +Alerting strategy: +- Page for customer-impacting issues +- Ticket for degraded performance +- Notification for capacity planning +- Silence during maintenance windows + +## Security Guidelines +Secrets never appear in logs or error messages. +Environment variables validated at startup. +CORS configured per-environment whitelist. +CSP headers enforced for web responses. + +Input validation: +- Zod schemas for request body parsing +- Path parameters validated against patterns +- Query parameters have default/max values + +Output encoding: +- HTML entities escaped in templates +- JSON stringification for API responses +- URL encoding for redirect targets + +Authentication patterns: +- JWT tokens with short expiry +- Refresh token rotation +- Session invalidation on logout +- Multi-factor authentication support + +Authorization model: +- Role-based access control (RBAC) +- Resource-level permissions +- Attribute-based policies (ABAC) +- Principle of least privilege + +Secure communication: +- TLS 1.3 minimum +- Certificate pinning for mobile +- HSTS preload list +- Certificate transparency logging + +## Performance Optimization +Critical paths target sub-10ms latency. +Database queries use covering indexes. +Response compression enabled for > 1KB bodies. +Static assets served with immutable caching. + +Caching strategy: +- Redis for session data +- In-memory LRU for hot paths +- CDN for static assets +- Stale-while-revalidate for API responses + +Memory management: +- Stream large payloads instead of buffering +- Weak references for disposable caches +- Manual GC hints for batch operations + +Query optimization: +- Explain plans for complex queries +- Index usage analysis +- Query result caching +- Connection pooling tuning + +Frontend performance: +- Code splitting for lazy loading +- Image optimization and lazy loading +- Critical CSS inlining +- Prefetching for likely navigations + +Backend performance: +- Async I/O for non-blocking operations +- Worker threads for CPU-bound tasks +- Connection keep-alive +- Response streaming + +## Deployment Architecture +Containers built with multi-stage Dockerfiles. +Kubernetes manifests in deploy/ directory. +Horizontal pod autoscaling on CPU/memory. +Rolling updates with zero-downtime. + +Environment hierarchy: +- development: local Docker Compose +- staging: shared k8s namespace +- production: isolated k8s cluster + +Configuration: +- ConfigMaps for non-sensitive config +- Secrets for credentials +- Environment-specific overlays via Kustomize + +Container best practices: +- Non-root user in container +- Read-only filesystem where possible +- Resource limits and requests +- Liveness and readiness probes + +Service mesh integration: +- Istio for traffic management +- mTLS for service-to-service auth +- Retry and timeout policies +- Circuit breaking configuration + +Disaster recovery: +- Database replication across zones +- Point-in-time recovery capability +- Regular backup verification +- Documented runbooks + +## Development Workflow +Feature branches follow conventional commits. +PRs require CI pass and code review. +Main branch deploys to staging automatically. +Release tags trigger production deployment. + +CI pipeline stages: +1. Install dependencies +2. Lint and type check +3. Unit tests with coverage +4. Build artifacts +5. Integration tests +6. Security scan + +Local development: +- pnpm for package management +- Turborepo for monorepo orchestration +- Docker Compose for service dependencies + +Code review guidelines: +- Focus on correctness and clarity +- Security-sensitive changes require security review +- Performance-critical paths need benchmarks +- Breaking changes need migration guide + +Branch strategy: +- main: production-ready code +- develop: integration branch (optional) +- feature/*: new functionality +- fix/*: bug fixes +- release/*: release preparation + +Documentation requirements: +- README for project overview +- API docs auto-generated from OpenAPI +- Architecture decision records (ADRs) +- Runbooks for operational procedures +`; + +// ─── Synthetic Roadmap Fixture (~1KB, 4 slices) ──────────────────────────── + +const syntheticRoadmap = `# M005: Tiered Context Injection + +## Vision +Refactor prompt builders to inject relevance-scoped context instead of full files. +This reduces token consumption and improves agent focus on relevant information. + +## Success Criteria +- [ ] 40% reduction in injected context size +- [ ] No regression in agent task completion rate +- [ ] Measurable test confirms reduction target + +## Slice Overview +| ID | Slice | Risk | Depends | Done | After this | +|----|-------|------|---------|------|------------| +| S01 | Scope existing DB queries | low | — | ✅ | planSlice and researchSlice use milestone+slice filters for decisions/requirements. | +| S02 | KNOWLEDGE scoping + roadmap excerpt | medium | S01 | ⬜ | KNOWLEDGE sections filtered by keywords. Roadmap injected as excerpt. | +| S03 | Measurement test suite | low | S02 | ⬜ | Automated tests confirm 40% reduction vs baseline. | +| S04 | Documentation and rollout | low | S03 | ⬜ | Updated docs. Feature flag for gradual rollout. | + +## Key Risks +1. Keyword extraction may miss relevant sections — mitigate with fallback to full content +2. Excerpt parsing fragile to roadmap format changes — mitigate with graceful degradation + +## Definition of Done +- [ ] All slices complete with passing verification +- [ ] Measurement tests in CI +- [ ] No increase in prompt build latency +`; + +// ═══════════════════════════════════════════════════════════════════════════ +// Measurement Tests +// ═══════════════════════════════════════════════════════════════════════════ + +describe("measurement: context reduction verification", () => { + test("synthetic KNOWLEDGE fixture is ~8KB as specified", () => { + const sizeKB = syntheticKnowledge.length / 1024; + assert.ok( + sizeKB >= 7 && sizeKB <= 10, + `KNOWLEDGE fixture should be ~8KB, got ${sizeKB.toFixed(2)}KB` + ); + }); + + test("synthetic KNOWLEDGE has 9 H2 sections", () => { + const h2Count = (syntheticKnowledge.match(/^## /gm) || []).length; + assert.strictEqual(h2Count, 9, `KNOWLEDGE fixture should have 9 H2 sections, got ${h2Count}`); + }); + + test("queryKnowledge achieves ≥40% reduction with targeted keywords", async () => { + // Keywords targeting 2 sections: "Database Patterns" and "Testing Strategy" + const keywords = ['database', 'testing']; + + const scopedResult = await queryKnowledge(syntheticKnowledge, keywords); + + const fullSize = syntheticKnowledge.length; + const scopedSize = scopedResult.length; + const reductionPct = ((fullSize - scopedSize) / fullSize) * 100; + + // Verify we got matching sections + assert.match(scopedResult, /## Database Patterns/, 'should include Database section'); + assert.match(scopedResult, /## Testing Strategy/, 'should include Testing section'); + + // Verify we excluded other sections + assert.ok(!scopedResult.includes('## API Design'), 'should exclude API section'); + assert.ok(!scopedResult.includes('## Observability'), 'should exclude Observability section'); + assert.ok(!scopedResult.includes('## Deployment'), 'should exclude Deployment section'); + + // Verify ≥40% reduction (2/9 sections = ~78% reduction expected) + assert.ok( + reductionPct >= 40, + `queryKnowledge should achieve ≥40% reduction, got ${reductionPct.toFixed(1)}% (${scopedSize} chars vs ${fullSize} chars)` + ); + + console.log(` → queryKnowledge: ${reductionPct.toFixed(1)}% reduction (${scopedSize} → ${fullSize} chars)`); + }); + + test("queryKnowledge with single keyword achieves ≥40% reduction", async () => { + // Single keyword targeting 1 section + const keywords = ['security']; + + const scopedResult = await queryKnowledge(syntheticKnowledge, keywords); + + const fullSize = syntheticKnowledge.length; + const scopedSize = scopedResult.length; + const reductionPct = ((fullSize - scopedSize) / fullSize) * 100; + + // Verify we got matching section + assert.match(scopedResult, /## Security Guidelines/, 'should include Security section'); + + // Verify ≥40% reduction (1/9 sections = ~89% reduction expected) + assert.ok( + reductionPct >= 40, + `single keyword should achieve ≥40% reduction, got ${reductionPct.toFixed(1)}%` + ); + }); + + test("formatRoadmapExcerpt achieves ≥40% reduction", () => { + const sliceId = 'S02'; + + const excerptResult = formatRoadmapExcerpt(syntheticRoadmap, sliceId, '.gsd/milestones/M005/M005-ROADMAP.md'); + + const fullSize = syntheticRoadmap.length; + const excerptSize = excerptResult.length; + const reductionPct = ((fullSize - excerptSize) / fullSize) * 100; + + // Verify excerpt contains required elements + assert.match(excerptResult, /\| ID \| Slice \|/, 'should have table header'); + assert.match(excerptResult, /\| S01 \|/, 'should have predecessor S01'); + assert.match(excerptResult, /\| S02 \|/, 'should have target S02'); + assert.match(excerptResult, /See full roadmap:/, 'should have reference directive'); + + // Verify we excluded other slices + assert.ok(!excerptResult.includes('| S03 |'), 'should exclude S03'); + assert.ok(!excerptResult.includes('| S04 |'), 'should exclude S04'); + + // Verify ≥40% reduction (2 rows + overhead vs full roadmap = significant reduction) + assert.ok( + reductionPct >= 40, + `formatRoadmapExcerpt should achieve ≥40% reduction, got ${reductionPct.toFixed(1)}% (${excerptSize} chars vs ${fullSize} chars)` + ); + + console.log(` → formatRoadmapExcerpt: ${reductionPct.toFixed(1)}% reduction (${excerptSize} → ${fullSize} chars)`); + }); + + test("combined KNOWLEDGE + roadmap reduction exceeds 40%", async () => { + // Simulate what happens in buildPlanSlicePrompt + const keywords = ['database', 'testing']; + + const scopedKnowledge = await queryKnowledge(syntheticKnowledge, keywords); + const scopedRoadmap = formatRoadmapExcerpt(syntheticRoadmap, 'S02'); + + const fullKnowledgeSize = syntheticKnowledge.length; + const fullRoadmapSize = syntheticRoadmap.length; + const fullTotal = fullKnowledgeSize + fullRoadmapSize; + + const scopedKnowledgeSize = scopedKnowledge.length; + const scopedRoadmapSize = scopedRoadmap.length; + const scopedTotal = scopedKnowledgeSize + scopedRoadmapSize; + + const combinedReductionPct = ((fullTotal - scopedTotal) / fullTotal) * 100; + + // Combined reduction should easily exceed 40% + assert.ok( + combinedReductionPct >= 40, + `combined reduction should be ≥40%, got ${combinedReductionPct.toFixed(1)}%` + ); + + console.log(` → Combined: ${combinedReductionPct.toFixed(1)}% reduction`); + console.log(` - KNOWLEDGE: ${fullKnowledgeSize} → ${scopedKnowledgeSize} chars`); + console.log(` - Roadmap: ${fullRoadmapSize} → ${scopedRoadmapSize} chars`); + console.log(` - Total: ${fullTotal} → ${scopedTotal} chars`); + }); +}); + +describe("measurement: edge cases maintain reduction target", () => { + test("three keywords still achieves ≥40% reduction", async () => { + // Even with 3 matching sections (3/9 = 33%), we should hit target + const keywords = ['database', 'api', 'security']; + + const scopedResult = await queryKnowledge(syntheticKnowledge, keywords); + + const fullSize = syntheticKnowledge.length; + const scopedSize = scopedResult.length; + const reductionPct = ((fullSize - scopedSize) / fullSize) * 100; + + // Verify matches (3 sections) + assert.match(scopedResult, /## Database Patterns/, 'should include Database'); + assert.match(scopedResult, /## API Design/, 'should include API'); + assert.match(scopedResult, /## Security Guidelines/, 'should include Security'); + + // With 3/9 sections, reduction should be ~67% + assert.ok( + reductionPct >= 40, + `3 keywords should still achieve ≥40% reduction, got ${reductionPct.toFixed(1)}%` + ); + }); + + test("excerpt for S01 (no dependencies) achieves ≥40% reduction", () => { + const excerptResult = formatRoadmapExcerpt(syntheticRoadmap, 'S01'); + + const fullSize = syntheticRoadmap.length; + const excerptSize = excerptResult.length; + const reductionPct = ((fullSize - excerptSize) / fullSize) * 100; + + // S01 has no predecessor, so just 1 row + header + reference + assert.match(excerptResult, /\| S01 \|/, 'should have S01'); + assert.ok(!excerptResult.includes('| S02 |'), 'should not have S02'); + + // Single row should still achieve significant reduction + assert.ok( + reductionPct >= 40, + `S01 excerpt should achieve ≥40% reduction, got ${reductionPct.toFixed(1)}%` + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/memory-extractor.test.ts b/src/resources/extensions/gsd/tests/memory-extractor.test.ts index 4df555470..47839f67b 100644 --- a/src/resources/extensions/gsd/tests/memory-extractor.test.ts +++ b/src/resources/extensions/gsd/tests/memory-extractor.test.ts @@ -1,4 +1,4 @@ -import { parseMemoryResponse, _resetExtractionState } from '../memory-extractor.ts'; +import { parseMemoryResponse, _resetExtractionState, buildMemoryLLMCall } from '../memory-extractor.ts'; import { openDatabase, closeDatabase, @@ -9,7 +9,7 @@ import { getActiveMemoriesRanked, } from '../memory-store.ts'; import type { MemoryAction } from '../memory-store.ts'; -import { describe, test, beforeEach, afterEach } from 'node:test'; +import { describe, test, beforeEach, afterEach, mock } from 'node:test'; import assert from 'node:assert/strict'; // ═══════════════════════════════════════════════════════════════════════════ @@ -169,3 +169,86 @@ test('memory-extractor: reset extraction state', () => { assert.ok(true, '_resetExtractionState should not throw'); }); +// ═══════════════════════════════════════════════════════════════════════════ +// memory-extractor: buildMemoryLLMCall resolves OAuth API key via modelRegistry +// Regression test for #2959 — OAuth users had broken memory extraction +// because streamSimpleAnthropic only checked env vars, not auth.json. +// ═══════════════════════════════════════════════════════════════════════════ + +test('memory-extractor: buildMemoryLLMCall resolves API key from modelRegistry for OAuth users', async () => { + const OAUTH_TOKEN = 'sk-ant-oat-test-oauth-token-12345'; + let getApiKeyCalled = false; + + const fakeModel = { + id: 'claude-haiku-test', + provider: 'anthropic', + api: 'anthropic-messages', + cost: { input: 0.25, output: 1.25 }, + }; + + const ctx = { + modelRegistry: { + getAvailable: () => [fakeModel], + getApiKey: async (_model: any) => { + getApiKeyCalled = true; + return OAUTH_TOKEN; + }, + }, + } as any; + + const llmCallFn = buildMemoryLLMCall(ctx); + assert.ok(llmCallFn !== null, 'buildMemoryLLMCall should return a function when models are available'); + + // The function should have resolved the API key eagerly via modelRegistry.getApiKey. + // Give the async getApiKey a tick to resolve. + await new Promise(resolve => setTimeout(resolve, 50)); + assert.ok(getApiKeyCalled, 'buildMemoryLLMCall must call modelRegistry.getApiKey() to resolve OAuth tokens'); +}); + +test('memory-extractor: buildMemoryLLMCall returns null when no models available', () => { + const ctx = { + modelRegistry: { + getAvailable: () => [], + getApiKey: async () => undefined, + }, + } as any; + + const llmCallFn = buildMemoryLLMCall(ctx); + assert.strictEqual(llmCallFn, null, 'should return null when no models available'); +}); + +test('memory-extractor: buildMemoryLLMCall prefers haiku model', async () => { + let resolvedModelId: string | undefined; + + const haikuModel = { + id: 'claude-3-5-haiku-20241022', + provider: 'anthropic', + api: 'anthropic-messages', + cost: { input: 0.25, output: 1.25 }, + }; + const sonnetModel = { + id: 'claude-sonnet-4-20250514', + provider: 'anthropic', + api: 'anthropic-messages', + cost: { input: 3, output: 15 }, + }; + + const ctx = { + modelRegistry: { + getAvailable: () => [sonnetModel, haikuModel], + getApiKey: async (model: any) => { + resolvedModelId = model.id; + return 'sk-ant-oat-test-token'; + }, + }, + } as any; + + const llmCallFn = buildMemoryLLMCall(ctx); + assert.ok(llmCallFn !== null, 'should return a function'); + + // Wait for the async getApiKey to resolve + await new Promise(resolve => setTimeout(resolve, 50)); + assert.strictEqual(resolvedModelId, 'claude-3-5-haiku-20241022', + 'should resolve API key for haiku model, not sonnet'); +}); + diff --git a/src/resources/extensions/gsd/tests/metrics.test.ts b/src/resources/extensions/gsd/tests/metrics.test.ts index 98782460e..dc221531a 100644 --- a/src/resources/extensions/gsd/tests/metrics.test.ts +++ b/src/resources/extensions/gsd/tests/metrics.test.ts @@ -6,7 +6,7 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, mkdirSync, readFileSync, rmSync } from "node:fs"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { tmpdir } from "node:os"; import { @@ -382,3 +382,118 @@ test("snapshotUnitMetrics counts toolCall blocks correctly (#1713)", () => { rmSync(tmpBase, { recursive: true, force: true }); } }); + +// ── #1943 — Duplicate metrics entries from idle watchdog ────────────────────── + +test("#1943 initMetrics deduplicates entries loaded from a corrupted disk ledger", () => { + const tmpBase = mkdtempSync(join(tmpdir(), "gsd-metrics-dedup-load-")); + mkdirSync(join(tmpBase, ".gsd"), { recursive: true }); + + try { + resetMetrics(); + + // Simulate a corrupted metrics.json with duplicate entries on disk + // (same type+id+startedAt but different finishedAt — idle watchdog pattern) + const corruptedLedger: MetricsLedger = { + version: 1, + projectStartedAt: 1700000000000, + units: [ + makeUnit({ type: "research-slice", id: "M009/S02", startedAt: 1774011016218, finishedAt: 1774011031218, cost: 1.50, tokens: { input: 6600000, output: 100000, cacheRead: 0, cacheWrite: 0, total: 6700000 } }), + makeUnit({ type: "research-slice", id: "M009/S02", startedAt: 1774011016218, finishedAt: 1774011046218, cost: 1.55, tokens: { input: 6800000, output: 110000, cacheRead: 0, cacheWrite: 0, total: 6910000 } }), + makeUnit({ type: "research-slice", id: "M009/S02", startedAt: 1774011016218, finishedAt: 1774011061218, cost: 1.60, tokens: { input: 7000000, output: 120000, cacheRead: 0, cacheWrite: 0, total: 7120000 } }), + makeUnit({ type: "research-slice", id: "M009/S02", startedAt: 1774011016218, finishedAt: 1774011076218, cost: 1.65, tokens: { input: 7200000, output: 130000, cacheRead: 0, cacheWrite: 0, total: 7330000 } }), + // A different unit — should be preserved + makeUnit({ type: "execute-task", id: "M001/S01/T01", startedAt: 1774012000000, finishedAt: 1774012060000, cost: 0.50 }), + ], + }; + writeFileSync( + join(tmpBase, ".gsd", "metrics.json"), + JSON.stringify(corruptedLedger, null, 2), + ); + + // Load the corrupted ledger — duplicates should be collapsed on load + initMetrics(tmpBase); + const ledger = getLedger(); + assert.ok(ledger); + + // The 4 entries with identical (type, id, startedAt) should collapse to 1, + // keeping the latest (highest finishedAt). Plus the 1 different unit = 2 total. + assert.equal( + ledger!.units.length, 2, + `expected 2 entries after dedup (1 collapsed group + 1 unique), got ${ledger!.units.length}`, + ); + + // The surviving duplicate should be the one with the latest finishedAt + const researchEntry = ledger!.units.find(u => u.type === "research-slice"); + assert.ok(researchEntry); + assert.equal(researchEntry!.finishedAt, 1774011076218, "should keep the latest finishedAt"); + assert.equal(researchEntry!.cost, 1.65, "should keep the latest cost"); + + // The on-disk file should also be deduplicated + const diskRaw = readFileSync(join(tmpBase, ".gsd", "metrics.json"), "utf-8"); + const diskLedger: MetricsLedger = JSON.parse(diskRaw); + assert.equal(diskLedger.units.length, 2, "disk should also have deduplicated entries"); + } finally { + resetMetrics(); + rmSync(tmpBase, { recursive: true, force: true }); + } +}); + +test("#1943 getProjectTotals reports correct cost after dedup (no 35% inflation)", () => { + // Simulate the exact scenario from the issue: 20 entries for a single dispatch + // with monotonically increasing token counts and 15s-apart finishedAt values + const startedAt = 1774011016218; + const baseCost = 1.50; + const duplicateUnits: UnitMetrics[] = []; + + for (let i = 0; i < 20; i++) { + duplicateUnits.push(makeUnit({ + type: "research-slice", + id: "M009/S02", + startedAt, + finishedAt: startedAt + (i + 1) * 15000, + cost: baseCost + i * 0.05, + toolCalls: 0, + tokens: { + input: 6600000 + i * 200000, + output: 100000 + i * 10000, + cacheRead: 0, + cacheWrite: 0, + total: 6700000 + i * 210000, + }, + })); + } + + // Without dedup, getProjectTotals would sum all 20 entries' costs + const rawTotals = getProjectTotals(duplicateUnits); + // With dedup (only last entry should count), cost should be the last entry's cost + const lastEntryCost = duplicateUnits[duplicateUnits.length - 1].cost; + + // This test documents the bug: raw totals inflate cost by summing duplicates + assert.ok( + rawTotals.cost > lastEntryCost * 2, + "raw totals with duplicates inflate cost (bug demonstration)", + ); + + // After loading through initMetrics (which should dedup), totals should be correct + const tmpBase = mkdtempSync(join(tmpdir(), "gsd-metrics-cost-inflation-")); + mkdirSync(join(tmpBase, ".gsd"), { recursive: true }); + try { + resetMetrics(); + writeFileSync( + join(tmpBase, ".gsd", "metrics.json"), + JSON.stringify({ version: 1, projectStartedAt: 1700000000000, units: duplicateUnits }, null, 2), + ); + initMetrics(tmpBase); + const ledger = getLedger()!; + const dedupedTotals = getProjectTotals(ledger.units); + assert.equal(ledger.units.length, 1, "20 duplicates should collapse to 1 entry"); + assert.equal( + dedupedTotals.cost, lastEntryCost, + `deduped cost should be ${lastEntryCost}, not ${dedupedTotals.cost}`, + ); + } finally { + resetMetrics(); + rmSync(tmpBase, { recursive: true, force: true }); + } +}); diff --git a/src/resources/extensions/gsd/tests/migrate-external-worktree.test.ts b/src/resources/extensions/gsd/tests/migrate-external-worktree.test.ts new file mode 100644 index 000000000..43098237b --- /dev/null +++ b/src/resources/extensions/gsd/tests/migrate-external-worktree.test.ts @@ -0,0 +1,105 @@ +import { describe, test, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + rmSync, + writeFileSync, + existsSync, + mkdirSync, + realpathSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execSync } from "node:child_process"; + +import { migrateToExternalState } from "../migrate-external.ts"; + +function run(command: string, cwd: string): string { + return execSync(command, { + cwd, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); +} + +describe("migrate-external worktree guard (#2970)", () => { + let base: string; + let stateDir: string; + let worktreePath: string; + + before(() => { + base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-migrate-wt-"))); + stateDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-state-"))); + process.env.GSD_STATE_DIR = stateDir; + + // Create a git repo with a remote + run("git init -b main", base); + run('git config user.name "Test"', base); + run('git config user.email "test@example.com"', base); + run('git remote add origin git@github.com:example/repo.git', base); + writeFileSync(join(base, "README.md"), "# Test\n", "utf-8"); + run("git add README.md", base); + run('git commit -m "init"', base); + + // Create a worktree + worktreePath = join(base, ".gsd", "worktrees", "M001"); + run(`git worktree add -b milestone/M001 ${worktreePath}`, base); + + // Populate worktree with a .gsd directory (simulating syncGsdStateToWorktree) + const worktreeGsd = join(worktreePath, ".gsd"); + mkdirSync(worktreeGsd, { recursive: true }); + writeFileSync(join(worktreeGsd, "PREFERENCES.md"), "# prefs\n", "utf-8"); + }); + + after(() => { + delete process.env.GSD_STATE_DIR; + // Remove worktree before cleaning up + try { run(`git worktree remove --force ${worktreePath}`, base); } catch { /* ok */ } + rmSync(base, { recursive: true, force: true }); + rmSync(stateDir, { recursive: true, force: true }); + }); + + test("migrateToExternalState skips when basePath is a git worktree", () => { + // The worktree has a real .gsd directory — migration would normally run. + // But since this is a worktree, it should be skipped. + const result = migrateToExternalState(worktreePath); + + assert.equal(result.migrated, false, "should not migrate inside a worktree"); + assert.equal(result.error, undefined, "should not report an error"); + + // .gsd should still exist as a real directory (not renamed/removed) + assert.ok( + existsSync(join(worktreePath, ".gsd")), + ".gsd directory should still exist after skipped migration" + ); + + // .gsd.migrating should NOT exist + assert.ok( + !existsSync(join(worktreePath, ".gsd.migrating")), + ".gsd.migrating should not be created in a worktree" + ); + }); + + test("migrateToExternalState still works on main repo", () => { + // Create a fresh temp repo to test main repo migration path + const mainBase = realpathSync(mkdtempSync(join(tmpdir(), "gsd-migrate-main-"))); + try { + run("git init -b main", mainBase); + run('git config user.name "Test"', mainBase); + run('git config user.email "test@example.com"', mainBase); + run('git remote add origin git@github.com:example/main-repo.git', mainBase); + writeFileSync(join(mainBase, "README.md"), "# Test\n", "utf-8"); + run("git add README.md", mainBase); + run('git commit -m "init"', mainBase); + + // Create a .gsd directory with content + mkdirSync(join(mainBase, ".gsd"), { recursive: true }); + writeFileSync(join(mainBase, ".gsd", "PREFERENCES.md"), "# prefs\n", "utf-8"); + + const result = migrateToExternalState(mainBase); + assert.equal(result.migrated, true, "should migrate on main repo"); + } finally { + rmSync(mainBase, { recursive: true, force: true }); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts b/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts index 8fa3d98d0..71be7d850 100644 --- a/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts +++ b/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts @@ -273,9 +273,9 @@ test('Scenario 2: Fully complete project — deriveState phase', async () => { invalidateAllCaches(); const state = await deriveState(base); assert.deepStrictEqual(state.phase, 'complete', 'complete: deriveState phase is complete (validation + summary written by migration)'); - // When all milestones are complete, activeMilestone points to the last entry (for display) - assert.ok(state.activeMilestone !== null, 'complete: deriveState has activeMilestone (last entry)'); - assert.deepStrictEqual(state.activeMilestone!.id, 'M001', 'complete: deriveState activeMilestone is M001'); + assert.equal(state.activeMilestone, null, 'complete: deriveState has no activeMilestone'); + assert.ok(state.lastCompletedMilestone !== null, 'complete: deriveState exposes lastCompletedMilestone'); + assert.deepStrictEqual(state.lastCompletedMilestone!.id, 'M001', 'complete: deriveState lastCompletedMilestone is M001'); // generatePreview for complete project const preview = generatePreview(project); @@ -292,4 +292,3 @@ test('Scenario 2: Fully complete project — deriveState phase', async () => { rmSync(base, { recursive: true, force: true }); } }); - diff --git a/src/resources/extensions/gsd/tests/milestone-status-authoritative.test.ts b/src/resources/extensions/gsd/tests/milestone-status-authoritative.test.ts new file mode 100644 index 000000000..94fdcf3c0 --- /dev/null +++ b/src/resources/extensions/gsd/tests/milestone-status-authoritative.test.ts @@ -0,0 +1,116 @@ +/** + * Bug #2807: Web roadmap derives milestone status from slice heuristics + * instead of authoritative GSD milestone state. + * + * getMilestoneStatus() should prefer the authoritative `status` field on + * WorkspaceMilestoneTarget (populated from the engine registry) rather + * than inferring status from slice completion flags. + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import { getMilestoneStatus } from "../../../../../web/lib/workspace-status.ts"; + +// Inline type to avoid importing .tsx (not compiled to .js by test pipeline) +interface TestMilestone { + id: string; + title: string; + roadmapPath?: string; + status?: "complete" | "active" | "pending" | "parked"; + validationVerdict?: "pass" | "needs-attention" | "needs-remediation"; + slices: Array<{ id: string; title: string; done: boolean; tasks: Array<{ id: string; title: string; done: boolean }> }>; +} + +// ── Helpers ──────────────────────────────────────────────────────────────── + +function makeMilestone(overrides: Partial & { id: string }): TestMilestone { + return { + title: overrides.id, + roadmapPath: undefined, + slices: [], + ...overrides, + }; +} + +// ── Tests ────────────────────────────────────────────────────────────────── + +test("getMilestoneStatus returns authoritative 'complete' even when slices are not all done", () => { + const milestone = makeMilestone({ + id: "M001", + status: "complete", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + { id: "S02", title: "Slice 2", done: false, tasks: [] }, // not done + ], + }); + // Before the fix, this would return "in-progress" because not all slices are done. + // After the fix, it should return "done" because authoritative status is "complete". + assert.equal(getMilestoneStatus(milestone, {}), "done"); +}); + +test("getMilestoneStatus returns authoritative 'active' regardless of slice state", () => { + const milestone = makeMilestone({ + id: "M002", + status: "active", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + { id: "S02", title: "Slice 2", done: true, tasks: [] }, + ], + }); + // Before the fix, this would return "done" because all slices are done. + // After the fix, it should return "in-progress" because authoritative status is "active". + assert.equal(getMilestoneStatus(milestone, {}), "in-progress"); +}); + +test("getMilestoneStatus returns 'pending' for authoritative 'pending' even when some slices done", () => { + const milestone = makeMilestone({ + id: "M003", + status: "pending", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + { id: "S02", title: "Slice 2", done: false, tasks: [] }, + ], + }); + // Before the fix, this would return "in-progress" because some slices are done. + // After the fix, it should return "pending". + assert.equal(getMilestoneStatus(milestone, {}), "pending"); +}); + +test("getMilestoneStatus maps 'parked' to 'pending' item status", () => { + const milestone = makeMilestone({ + id: "M004", + status: "parked", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + ], + }); + // Parked milestones should render as pending in the UI + assert.equal(getMilestoneStatus(milestone, {}), "pending"); +}); + +test("getMilestoneStatus falls back to heuristic when no authoritative status", () => { + // Backward compatibility: milestones without the status field should + // still work using the old slice-based heuristic. + const milestone = makeMilestone({ + id: "M005", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + { id: "S02", title: "Slice 2", done: true, tasks: [] }, + ], + }); + assert.equal(getMilestoneStatus(milestone, {}), "done"); +}); + +test("getMilestoneStatus exposes validationVerdict on milestone target", () => { + const milestone = makeMilestone({ + id: "M006", + status: "complete", + validationVerdict: "needs-attention", + slices: [ + { id: "S01", title: "Slice 1", done: true, tasks: [] }, + ], + }); + // The milestone should have the validationVerdict field available + assert.equal(milestone.validationVerdict, "needs-attention"); + // And status should still be "done" + assert.equal(getMilestoneStatus(milestone, {}), "done"); +}); diff --git a/src/resources/extensions/gsd/tests/milestone-status-tool.test.ts b/src/resources/extensions/gsd/tests/milestone-status-tool.test.ts new file mode 100644 index 000000000..e1dfb3e95 --- /dev/null +++ b/src/resources/extensions/gsd/tests/milestone-status-tool.test.ts @@ -0,0 +1,201 @@ +// GSD2 — Tests for gsd_milestone_status read-only query tool + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { registerQueryTools } from "../bootstrap/query-tools.ts"; +import { + openDatabase, + closeDatabase, + _getAdapter, +} from "../gsd-db.ts"; + +// ─── Helpers ────────────────────────────────────────────────────────────────── + +function makeMockPi() { + const tools: any[] = []; + return { + registerTool: (tool: any) => tools.push(tool), + tools, + } as any; +} + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-query-tool-test-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* swallow */ } +} + +function openTestDb(base: string): void { + openDatabase(join(base, ".gsd", "gsd.db")); +} + +async function executeToolInDir(tool: any, params: Record, dir: string) { + const originalCwd = process.cwd(); + try { + process.chdir(dir); + return await tool.execute("test-call-id", params, undefined, undefined, undefined); + } finally { + process.chdir(originalCwd); + } +} + +// ─── Seed helpers ───────────────────────────────────────────────────────────── + +function seedMilestone(milestoneId: string, title: string, status = "active"): void { + const db = _getAdapter(); + if (!db) throw new Error("DB not open"); + db.prepare( + "INSERT OR REPLACE INTO milestones (id, title, status, created_at) VALUES (?, ?, ?, ?)", + ).run(milestoneId, title, status, new Date().toISOString()); +} + +function seedSlice(milestoneId: string, sliceId: string, status: string): void { + const db = _getAdapter(); + if (!db) throw new Error("DB not open"); + db.prepare( + "INSERT OR REPLACE INTO slices (milestone_id, id, title, status, created_at) VALUES (?, ?, ?, ?, ?)", + ).run(milestoneId, sliceId, `Slice ${sliceId}`, status, new Date().toISOString()); +} + +function seedTask(milestoneId: string, sliceId: string, taskId: string, status: string): void { + const db = _getAdapter(); + if (!db) throw new Error("DB not open"); + db.prepare( + "INSERT OR REPLACE INTO tasks (milestone_id, slice_id, id, title, status) VALUES (?, ?, ?, ?, ?)", + ).run(milestoneId, sliceId, taskId, `Task ${taskId}`, status); +} + +// ─── Registration ───────────────────────────────────────────────────────────── + +test("registerQueryTools registers gsd_milestone_status tool", () => { + const pi = makeMockPi(); + registerQueryTools(pi); + assert.equal(pi.tools.length, 1, "Should register exactly one tool"); + assert.equal(pi.tools[0].name, "gsd_milestone_status"); +}); + +test("gsd_milestone_status has promptGuidelines mentioning prohibited alternatives", () => { + const pi = makeMockPi(); + registerQueryTools(pi); + const tool = pi.tools[0]; + assert.ok(Array.isArray(tool.promptGuidelines), "promptGuidelines must be an array"); + assert.ok(tool.promptGuidelines.length >= 1, "Must have at least one guideline"); + const joined = tool.promptGuidelines.join(" "); + assert.match(joined, /sqlite3|better-sqlite3/, "Guidelines must mention prohibited alternatives"); +}); + +// ─── Happy path: milestone with slices and tasks ────────────────────────────── + +test("gsd_milestone_status returns milestone metadata and slice statuses", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M001", "Test Milestone"); + seedSlice("M001", "S01", "complete"); + seedSlice("M001", "S02", "active"); + seedTask("M001", "S01", "T01", "done"); + seedTask("M001", "S01", "T02", "done"); + seedTask("M001", "S02", "T01", "pending"); + + const pi = makeMockPi(); + registerQueryTools(pi); + const tool = pi.tools[0]; + + const result = await executeToolInDir(tool, { milestoneId: "M001" }, base); + const parsed = JSON.parse(result.content[0].text); + + assert.equal(parsed.milestoneId, "M001"); + assert.equal(parsed.title, "Test Milestone"); + assert.equal(parsed.status, "active"); + assert.equal(parsed.sliceCount, 2); + assert.equal(parsed.slices.length, 2); + + const s01 = parsed.slices.find((s: any) => s.id === "S01"); + assert.ok(s01, "S01 should be in slices"); + assert.equal(s01.status, "complete"); + assert.equal(s01.taskCounts.total, 2); + assert.equal(s01.taskCounts.done, 2); + + const s02 = parsed.slices.find((s: any) => s.id === "S02"); + assert.ok(s02, "S02 should be in slices"); + assert.equal(s02.status, "active"); + assert.equal(s02.taskCounts.pending, 1); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +// ─── Milestone with no slices ───────────────────────────────────────────────── + +test("gsd_milestone_status returns empty slices array for milestone with no slices", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M002", "Empty Milestone"); + + const pi = makeMockPi(); + registerQueryTools(pi); + const tool = pi.tools[0]; + + const result = await executeToolInDir(tool, { milestoneId: "M002" }, base); + const parsed = JSON.parse(result.content[0].text); + + assert.equal(parsed.milestoneId, "M002"); + assert.equal(parsed.sliceCount, 0); + assert.deepEqual(parsed.slices, []); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +// ─── Missing milestone ──────────────────────────────────────────────────────── + +test("gsd_milestone_status returns not-found for missing milestone", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + + const pi = makeMockPi(); + registerQueryTools(pi); + const tool = pi.tools[0]; + + const result = await executeToolInDir(tool, { milestoneId: "M999" }, base); + assert.match(result.content[0].text, /M999.*not found/i); + assert.equal(result.details.found, false); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +// ─── DB unavailable ─────────────────────────────────────────────────────────── + +test("gsd_milestone_status handles missing DB gracefully", async () => { + // Create a directory without .gsd/ to ensure ensureDbOpen has nothing to open + const base = join(tmpdir(), `gsd-no-db-${randomUUID()}`); + mkdirSync(base, { recursive: true }); + closeDatabase(); // ensure no prior DB is open + try { + const pi = makeMockPi(); + registerQueryTools(pi); + const tool = pi.tools[0]; + + const result = await executeToolInDir(tool, { milestoneId: "M001" }, base); + assert.match(result.content[0].text, /GSD database is not available/); + assert.equal(result.details.error, "db_unavailable"); + } finally { + closeDatabase(); + cleanup(base); + } +}); diff --git a/src/resources/extensions/gsd/tests/model-cost-table.test.ts b/src/resources/extensions/gsd/tests/model-cost-table.test.ts index 98906c083..4ab8381f0 100644 --- a/src/resources/extensions/gsd/tests/model-cost-table.test.ts +++ b/src/resources/extensions/gsd/tests/model-cost-table.test.ts @@ -67,3 +67,37 @@ test("all cost table entries have valid data", () => { assert.ok(entry.updatedAt, `${entry.id} missing updatedAt`); } }); + +// ─── #2885: openai-codex and modern OpenAI models in cost table ────────────── + +test("#2885: cost table includes openai-codex provider models", () => { + const ids = BUNDLED_COST_TABLE.map(e => e.id); + const codexModels = [ + "gpt-5.1", "gpt-5.1-codex-max", "gpt-5.1-codex-mini", + "gpt-5.2", "gpt-5.2-codex", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.4", + ]; + for (const model of codexModels) { + assert.ok(ids.includes(model), `cost table should include openai-codex model "${model}"`); + } +}); + +test("#2885: cost table includes modern OpenAI models", () => { + const ids = BUNDLED_COST_TABLE.map(e => e.id); + const newModels = [ + "o4-mini", "o4-mini-deep-research", + "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", + "gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-5-pro", + ]; + for (const model of newModels) { + assert.ok(ids.includes(model), `cost table should include modern OpenAI model "${model}"`); + } +}); + +test("#2885: lookupModelCost returns costs for new models (not 999 fallback)", () => { + const newModels = ["o4-mini", "gpt-4.1", "gpt-5", "gpt-5.4", "gpt-5.1-codex-mini"]; + for (const model of newModels) { + const entry = lookupModelCost(model); + assert.ok(entry, `lookupModelCost should find "${model}"`); + assert.ok(entry.inputPer1k < 999, `${model} should have a real cost, not the 999 fallback`); + } +}); diff --git a/src/resources/extensions/gsd/tests/model-isolation.test.ts b/src/resources/extensions/gsd/tests/model-isolation.test.ts index 088d24079..6dd107b12 100644 --- a/src/resources/extensions/gsd/tests/model-isolation.test.ts +++ b/src/resources/extensions/gsd/tests/model-isolation.test.ts @@ -1,5 +1,6 @@ /** - * Tests for model config isolation between concurrent instances (#650, #1065). + * Tests for model config isolation between concurrent instances (#650, #1065) + * and GSD preferences override of settings.json defaults (#3517). */ import { describe, it, beforeEach, afterEach } from "node:test"; @@ -155,3 +156,76 @@ describe("session model recovery on error (#1065)", () => { "Recovery should be skipped when no session model was captured"); }); }); + +// ─── GSD Preferences override settings.json (#3517) ───────────────────────── + +describe("GSD preferences override settings.json for session model (#3517)", () => { + it("preferredModel takes priority over ctx.model when both are available", () => { + // Simulates auto-start.ts logic: preferredModel ?? ctx.model snapshot + const preferredModel = { provider: "openai-codex", id: "gpt-5.4" }; + const ctxModel = { provider: "claude-code", id: "claude-sonnet-4-6" }; + + const startModelSnapshot = preferredModel + ?? { provider: ctxModel.provider, id: ctxModel.id }; + + assert.equal(startModelSnapshot.provider, "openai-codex", + "preferredModel provider should win over ctx.model"); + assert.equal(startModelSnapshot.id, "gpt-5.4", + "preferredModel id should win over ctx.model"); + }); + + it("falls back to ctx.model when no GSD preferences are configured", () => { + const preferredModel: { provider: string; id: string } | undefined = undefined; + const ctxModel = { provider: "claude-code", id: "claude-sonnet-4-6" }; + + const startModelSnapshot = preferredModel + ?? { provider: ctxModel.provider, id: ctxModel.id }; + + assert.equal(startModelSnapshot.provider, "claude-code", + "should fall back to ctx.model provider when no preferences"); + assert.equal(startModelSnapshot.id, "claude-sonnet-4-6", + "should fall back to ctx.model id when no preferences"); + }); + + it("handles null ctx.model with no preferences gracefully", () => { + const preferredModel: { provider: string; id: string } | undefined = undefined; + // Use a function to prevent TS from narrowing to `never` in the ternary + function getCtxModel(): { provider: string; id: string } | null { return null; } + const ctxModel = getCtxModel(); + + const startModelSnapshot = preferredModel + ?? (ctxModel ? { provider: ctxModel.provider, id: ctxModel.id } : null); + + assert.equal(startModelSnapshot, null, + "should be null when neither preferences nor ctx.model exist"); + }); + + it("bare model ID uses session provider when available", () => { + // Simulates: PREFERENCES.md has "gpt-5.4" (no provider), session is openai-codex + const preferredModel = { provider: "openai-codex", id: "gpt-5.4" }; // from resolveDefaultSessionModel("openai-codex") + const ctxModel = { provider: "openai-codex", id: "claude-sonnet-4-6" }; + + const startModelSnapshot = preferredModel + ?? { provider: ctxModel.provider, id: ctxModel.id }; + + assert.equal(startModelSnapshot.provider, "openai-codex"); + assert.equal(startModelSnapshot.id, "gpt-5.4", + "bare model ID from preferences should still override ctx.model"); + }); + + it("stale settings.json does not leak when preferences are set", () => { + // Scenario: settings.json has claude-code, PREFERENCES.md has openai-codex + const settingsJsonDefault = { provider: "claude-code", id: "claude-sonnet-4-6" }; + const preferencesModel = { provider: "openai-codex", id: "gpt-5.4" }; + + // auto-start.ts captures preferredModel first, which preempts settingsJsonDefault + const startModelSnapshot = preferencesModel ?? settingsJsonDefault; + + assert.equal(startModelSnapshot.provider, "openai-codex", + "PREFERENCES.md must override stale settings.json provider"); + assert.equal(startModelSnapshot.id, "gpt-5.4", + "PREFERENCES.md must override stale settings.json model"); + assert.notEqual(startModelSnapshot.provider, settingsJsonDefault.provider, + "settings.json provider must NOT leak through"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/model-router.test.ts b/src/resources/extensions/gsd/tests/model-router.test.ts index b22fce7fd..d12a71df9 100644 --- a/src/resources/extensions/gsd/tests/model-router.test.ts +++ b/src/resources/extensions/gsd/tests/model-router.test.ts @@ -1,12 +1,17 @@ -import test from "node:test"; +import test, { describe } from "node:test"; import assert from "node:assert/strict"; import { resolveModelForComplexity, escalateTier, defaultRoutingConfig, + scoreModel, + computeTaskRequirements, + scoreEligibleModels, + getEligibleModels, + MODEL_CAPABILITY_PROFILES, } from "../model-router.js"; -import type { DynamicRoutingConfig, RoutingDecision } from "../model-router.js"; +import type { DynamicRoutingConfig, RoutingDecision, ModelCapabilities } from "../model-router.js"; import type { ClassificationResult } from "../complexity-classifier.js"; // ─── Helpers ───────────────────────────────────────────────────────────────── @@ -172,11 +177,11 @@ test("#2192: unknown model is not downgraded — respects user config", () => { const config = { ...defaultRoutingConfig(), enabled: true }; const result = resolveModelForComplexity( makeClassification("light"), - { primary: "gpt-5.4", fallbacks: [] }, + { primary: "some-future-unknown-model-v9", fallbacks: [] }, config, - ["gpt-5.4", ...AVAILABLE_MODELS], + ["some-future-unknown-model-v9", ...AVAILABLE_MODELS], ); - assert.equal(result.modelId, "gpt-5.4", "unknown model should be used as-is"); + assert.equal(result.modelId, "some-future-unknown-model-v9", "unknown model should be used as-is"); assert.equal(result.wasDowngraded, false, "should not be downgraded"); assert.ok(result.reason.includes("not in the known tier map"), "reason should explain why"); }); @@ -205,3 +210,549 @@ test("#2192: known model is still downgraded normally", () => { assert.equal(result.wasDowngraded, true, "known heavy model should still be downgraded for light tasks"); assert.notEqual(result.modelId, "claude-opus-4-6"); }); + +// ─── Capability Scoring (ADR-004 Phase 2) ─────────────────────────────────── + +test("defaultRoutingConfig includes capability_routing: true", () => { + const config = defaultRoutingConfig(); + assert.equal(config.capability_routing, true); +}); + +test("scoreModel computes weighted average of capability × requirement", () => { + const caps: ModelCapabilities = { + coding: 90, debugging: 80, research: 70, + reasoning: 85, speed: 50, longContext: 60, instruction: 75, + }; + const reqs = { coding: 0.9, reasoning: 0.5 }; + const score = scoreModel(caps, reqs); + // Expected: (0.9*90 + 0.5*85) / (0.9 + 0.5) = (81 + 42.5) / 1.4 = 88.21... + assert.ok(Math.abs(score - 88.21) < 0.1, `score ${score} should be ~88.21`); +}); + +test("scoreModel returns 50 for empty requirements", () => { + const caps: ModelCapabilities = { + coding: 90, debugging: 80, research: 70, + reasoning: 85, speed: 50, longContext: 60, instruction: 75, + }; + const score = scoreModel(caps, {}); + assert.equal(score, 50); +}); + +test("computeTaskRequirements returns base vector for known unit type", () => { + const reqs = computeTaskRequirements("execute-task"); + assert.ok(reqs.coding !== undefined && reqs.coding > 0); +}); + +test("computeTaskRequirements boosts instruction for docs-tagged tasks", () => { + const reqs = computeTaskRequirements("execute-task", { tags: ["docs"] }); + assert.ok((reqs.instruction ?? 0) >= 0.8); + assert.ok((reqs.coding ?? 1) <= 0.4); +}); + +test("computeTaskRequirements returns generic vector for unknown unit type", () => { + const reqs = computeTaskRequirements("unknown-unit"); + assert.ok(reqs.reasoning !== undefined); +}); + +test("resolveModelForComplexity uses capability scoring when enabled", () => { + const config: DynamicRoutingConfig = { + ...defaultRoutingConfig(), + enabled: true, + capability_routing: true, + }; + const result = resolveModelForComplexity( + makeClassification("light"), + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + ["claude-opus-4-6", "claude-haiku-4-5", "gpt-4o-mini"], + "execute-task", + ); + assert.equal(result.wasDowngraded, true); + assert.equal(result.selectionMethod, "capability-scored"); +}); + +test("resolveModelForComplexity falls back to tier-only when capability_routing is false", () => { + const config: DynamicRoutingConfig = { + ...defaultRoutingConfig(), + enabled: true, + capability_routing: false, + }; + const result = resolveModelForComplexity( + makeClassification("light"), + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + ["claude-opus-4-6", "claude-haiku-4-5", "gpt-4o-mini"], + ); + assert.equal(result.wasDowngraded, true); + assert.ok(!result.selectionMethod || result.selectionMethod === "tier-only"); +}); + +test("MODEL_CAPABILITY_PROFILES has entries for all tier-mapped models", () => { + const profiledModels = Object.keys(MODEL_CAPABILITY_PROFILES); + assert.ok(profiledModels.length >= 30, `Expected ≥30 profiles, got ${profiledModels.length}`); + assert.ok(MODEL_CAPABILITY_PROFILES["claude-opus-4-6"]); + assert.ok(MODEL_CAPABILITY_PROFILES["claude-haiku-4-5"]); +}); + +// ─── #2885: openai-codex and modern OpenAI models in tier map ──────────────── + +test("#2885: openai-codex light-tier models are recognized", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const lightModels = ["gpt-4.1-mini", "gpt-4.1-nano", "gpt-5-mini", "gpt-5-nano", "gpt-5.1-codex-mini", "gpt-5.3-codex-spark"]; + for (const model of lightModels) { + const result = resolveModelForComplexity( + makeClassification("light"), + { primary: model, fallbacks: [] }, + config, + [model, ...AVAILABLE_MODELS], + ); + // Model is known AND light-tier, so requesting light should NOT downgrade + assert.equal(result.wasDowngraded, false, `${model} should be known as light tier (wasDowngraded)`); + assert.equal(result.modelId, model, `${model} should be returned as-is for light tier`); + // Verify it IS known (not hitting the unknown-model bail-out) + assert.ok(!result.reason.includes("not in the known tier map"), `${model} should be in the known tier map`); + } +}); + +test("#2885: openai-codex standard-tier models are recognized", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const standardModels = ["gpt-4.1", "gpt-5.1-codex-max"]; + for (const model of standardModels) { + const result = resolveModelForComplexity( + makeClassification("standard"), + { primary: model, fallbacks: [] }, + config, + [model, ...AVAILABLE_MODELS], + ); + assert.equal(result.wasDowngraded, false, `${model} should be known as standard tier`); + assert.equal(result.modelId, model, `${model} should be returned as-is for standard tier`); + assert.ok(!result.reason.includes("not in the known tier map"), `${model} should be in the known tier map`); + } +}); + +test("#2885: openai-codex heavy-tier models are recognized", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const heavyModels = ["gpt-5", "gpt-5-pro", "gpt-5.1", "gpt-5.2", "gpt-5.2-codex", "gpt-5.3-codex", "gpt-5.4", "o4-mini", "o4-mini-deep-research"]; + for (const model of heavyModels) { + const result = resolveModelForComplexity( + makeClassification("heavy"), + { primary: model, fallbacks: [] }, + config, + [model, ...AVAILABLE_MODELS], + ); + assert.equal(result.wasDowngraded, false, `${model} should be known as heavy tier`); + assert.equal(result.modelId, model, `${model} should be returned as-is for heavy tier`); + assert.ok(!result.reason.includes("not in the known tier map"), `${model} should be in the known tier map`); + } +}); + +test("#2885: heavy openai-codex model downgrades to light for light task", () => { + const config = { ...defaultRoutingConfig(), enabled: true }; + const result = resolveModelForComplexity( + makeClassification("light"), + { primary: "gpt-5.4", fallbacks: [] }, + config, + ["gpt-5.4", "gpt-4.1-nano", ...AVAILABLE_MODELS], + ); + assert.equal(result.wasDowngraded, true, "heavy model should downgrade for light task"); + // Should pick a light-tier model + assert.notEqual(result.modelId, "gpt-5.4", "should not use the heavy model for light task"); +}); +// ─── scoreModel ────────────────────────────────────────────────────────────── + +describe("scoreModel", () => { + const sonnetProfile: ModelCapabilities = MODEL_CAPABILITY_PROFILES["claude-sonnet-4-6"]!; + + test("produces correct weighted average for two dimensions (coding:0.9, instruction:0.7)", () => { + // (0.9*85 + 0.7*85) / (0.9+0.7) = (76.5+59.5)/1.6 = 136/1.6 = 85.0 + const score = scoreModel(sonnetProfile, { coding: 0.9, instruction: 0.7 }); + assert.ok(Math.abs(score - 85.0) < 0.01, `Expected ~85.0, got ${score}`); + }); + + test("returns 50 when requirements is empty", () => { + const score = scoreModel(sonnetProfile, {}); + assert.equal(score, 50); + }); + + test("returns correct score for single dimension coding:1.0", () => { + // coding=90 for claude-opus-4-6 + const opusProfile = MODEL_CAPABILITY_PROFILES["claude-opus-4-6"]!; + const score = scoreModel(opusProfile, { coding: 1.0 }); + assert.equal(score, 95); + }); + + test("handles all 7 dimensions correctly", () => { + // Uniform weight 1.0 on every dim → average of all dim values + const profile: ModelCapabilities = { + coding: 60, debugging: 60, research: 60, reasoning: 60, + speed: 60, longContext: 60, instruction: 60, + }; + const reqs: Partial> = { + coding: 1.0, debugging: 1.0, research: 1.0, reasoning: 1.0, + speed: 1.0, longContext: 1.0, instruction: 1.0, + }; + const score = scoreModel(profile, reqs); + assert.equal(score, 60); + }); +}); + +// ─── computeTaskRequirements ───────────────────────────────────────────────── + +describe("computeTaskRequirements", () => { + test("execute-task with no metadata returns base vector", () => { + const req = computeTaskRequirements("execute-task", undefined); + assert.deepStrictEqual(req, { coding: 0.9, instruction: 0.7, speed: 0.3 }); + }); + + test("execute-task with tags:['docs'] adjusts requirements", () => { + const req = computeTaskRequirements("execute-task", { tags: ["docs"] }); + assert.equal(req.instruction, 0.9); + assert.equal(req.coding, 0.3); + assert.equal(req.speed, 0.7); + }); + + test("execute-task with tags:['config'] adjusts requirements", () => { + const req = computeTaskRequirements("execute-task", { tags: ["config"] }); + assert.equal(req.instruction, 0.9); + }); + + test("execute-task with complexityKeywords:['concurrency'] boosts debugging and reasoning", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["concurrency"] }); + assert.equal(req.debugging, 0.9); + assert.equal(req.reasoning, 0.8); + }); + + test("execute-task with complexityKeywords:['migration'] boosts reasoning and coding", () => { + const req = computeTaskRequirements("execute-task", { complexityKeywords: ["migration"] }); + assert.equal(req.reasoning, 0.9); + assert.equal(req.coding, 0.8); + }); + + test("execute-task with fileCount:8 boosts coding and reasoning", () => { + const req = computeTaskRequirements("execute-task", { fileCount: 8 }); + assert.equal(req.coding, 0.9); + assert.equal(req.reasoning, 0.7); + }); + + test("execute-task with estimatedLines:600 boosts coding and reasoning", () => { + const req = computeTaskRequirements("execute-task", { estimatedLines: 600 }); + assert.equal(req.coding, 0.9); + assert.equal(req.reasoning, 0.7); + }); + + test("research-milestone returns correct base vector", () => { + const req = computeTaskRequirements("research-milestone"); + assert.deepStrictEqual(req, { research: 0.9, longContext: 0.7, reasoning: 0.5 }); + }); + + test("plan-slice returns correct base vector", () => { + const req = computeTaskRequirements("plan-slice"); + assert.deepStrictEqual(req, { reasoning: 0.9, coding: 0.5 }); + }); + + test("unknown-unit-type returns default reasoning requirement", () => { + const req = computeTaskRequirements("unknown-unit-type"); + assert.deepStrictEqual(req, { reasoning: 0.5 }); + }); + + test("non-execute-task with metadata ignores metadata refinements", () => { + // research-milestone should return the same vector regardless of metadata + const reqWithMeta = computeTaskRequirements("research-milestone", { tags: ["docs"], fileCount: 10 }); + const reqWithout = computeTaskRequirements("research-milestone"); + assert.deepStrictEqual(reqWithMeta, reqWithout); + }); +}); + +// ─── scoreEligibleModels ───────────────────────────────────────────────────── + +describe("scoreEligibleModels", () => { + test("ranks models by score descending when scores differ by more than 2", () => { + // research: heavily weights research dimension. gemini-2.5-pro has 85 research vs sonnet's 75 + const requirements = { research: 0.9, longContext: 0.7, reasoning: 0.5 }; + const results = scoreEligibleModels(["claude-sonnet-4-6", "gemini-2.5-pro"], requirements); + assert.equal(results.length, 2); + assert.ok(results[0].score >= results[1].score, "Should be sorted by score descending"); + }); + + test("within 2-point threshold, prefers cheaper model", () => { + // Use models without built-in profiles (both get score 50) so tie-break applies + // Then use known models with equal scores: force this via single unknown model pair + const requirements = { coding: 1.0 }; + // model-a and model-b are both unknown → score=50, cost=Infinity → lexicographic + const results = scoreEligibleModels(["model-z", "model-a"], requirements); + // Both unknown: score=50 (within 2), cost=Infinity (equal) → lex: model-a first + assert.equal(results[0].modelId, "model-a"); + }); + + test("single model returns array of one", () => { + const results = scoreEligibleModels(["claude-sonnet-4-6"], { coding: 0.9 }); + assert.equal(results.length, 1); + assert.equal(results[0].modelId, "claude-sonnet-4-6"); + }); + + test("unknown model with no profile gets score of 50", () => { + const results = scoreEligibleModels(["totally-unknown-model"], { coding: 1.0 }); + assert.equal(results[0].score, 50); + }); + + test("capabilityOverrides deep-merges with built-in profile", () => { + const requirements = { coding: 1.0 }; + // Override sonnet's coding to 30 — gpt-4o (coding=80) should win + const results = scoreEligibleModels( + ["claude-sonnet-4-6", "gpt-4o"], + requirements, + { "claude-sonnet-4-6": { coding: 30 } }, + ); + assert.equal(results[0].modelId, "gpt-4o", "gpt-4o should rank first after coding override"); + }); +}); + +// ─── getEligibleModels ─────────────────────────────────────────────────────── + +describe("getEligibleModels", () => { + const ALL_MODELS = [ + "claude-opus-4-6", // heavy + "claude-sonnet-4-6", // standard + "claude-haiku-4-5", // light + "gpt-4o-mini", // light + "gpt-4o", // standard + ]; + + test("returns light-tier models from available list sorted by cost", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + const result = getEligibleModels("light", ALL_MODELS, config); + assert.ok(result.length >= 1); + for (const id of result) { + assert.ok( + ["claude-haiku-4-5", "gpt-4o-mini"].includes(id), + `Expected light-tier model, got ${id}`, + ); + } + }); + + test("returns standard-tier models from available list sorted by cost", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + const result = getEligibleModels("standard", ALL_MODELS, config); + assert.ok(result.length >= 1); + for (const id of result) { + assert.ok( + ["claude-sonnet-4-6", "gpt-4o"].includes(id), + `Expected standard-tier model, got ${id}`, + ); + } + }); + + test("tier_models pinned model returns single-element array", () => { + const config: DynamicRoutingConfig = { + ...defaultRoutingConfig(), + tier_models: { light: "gpt-4o-mini" }, + }; + const result = getEligibleModels("light", ALL_MODELS, config); + assert.deepStrictEqual(result, ["gpt-4o-mini"]); + }); + + test("empty available list returns empty array", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + const result = getEligibleModels("light", [], config); + assert.equal(result.length, 0); + }); + + test("unknown models classified as standard appear in standard tier results", () => { + const config: DynamicRoutingConfig = defaultRoutingConfig(); + // unknown-model-xyz has no entry → defaults to standard tier + const result = getEligibleModels("standard", ["unknown-model-xyz"], config); + assert.ok(result.includes("unknown-model-xyz"), "Unknown model should appear in standard tier"); + }); +}); + +// ─── capability-aware routing integration ──────────────────────────────────── + +describe("capability-aware routing integration", () => { + // All standard-tier models available alongside heavy (opus) + const MULTI_MODEL_AVAILABLE = [ + "claude-opus-4-6", + "claude-sonnet-4-6", + "gpt-4o", + "gemini-2.5-pro", + "claude-haiku-4-5", + "gpt-4o-mini", + ]; + + // 1. Full pipeline with capability scoring active + test("full pipeline with capability_routing: true returns capability-scored decision", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true, capability_routing: true }; + // Configured primary is opus (heavy) — standard tier should trigger capability scoring + const result = resolveModelForComplexity( + { tier: "standard", reason: "test", downgraded: false }, + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MULTI_MODEL_AVAILABLE, + "execute-task", + { tags: [], complexityKeywords: [], fileCount: 3, estimatedLines: 100, codeBlockCount: 0 }, + ); + assert.equal(result.selectionMethod, "capability-scored", "should use capability scoring when enabled with multiple eligible models"); + assert.ok(result.capabilityScores !== undefined, "capabilityScores should be populated"); + assert.ok(Object.keys(result.capabilityScores!).length > 1, "should have scores for multiple models"); + assert.equal(result.wasDowngraded, true, "should be downgraded from opus"); + }); + + // 2. capability_routing: false falls back to tier-only + test("capability_routing: false skips scoring and uses tier-only", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true, capability_routing: false }; + const result = resolveModelForComplexity( + { tier: "standard", reason: "test", downgraded: false }, + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MULTI_MODEL_AVAILABLE, + "execute-task", + undefined, + ); + assert.equal(result.selectionMethod, "tier-only", "capability_routing: false should use tier-only"); + assert.equal(result.capabilityScores, undefined, "capabilityScores should be undefined for tier-only"); + }); + + // 3. Single eligible model skips scoring + test("single eligible model skips capability scoring and uses tier-only", () => { + const config: DynamicRoutingConfig = { + ...defaultRoutingConfig(), + enabled: true, + capability_routing: true, + tier_models: { standard: "claude-sonnet-4-6" }, + }; + // Pin to single standard model — eligible.length === 1 → skips STEP 2 + const result = resolveModelForComplexity( + { tier: "standard", reason: "test", downgraded: false }, + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MULTI_MODEL_AVAILABLE, + "execute-task", + undefined, + ); + // Single pinned model → tier-only (no scoring needed) + assert.equal(result.selectionMethod, "tier-only", "single eligible model should use tier-only"); + assert.equal(result.modelId, "claude-sonnet-4-6", "should use the pinned model"); + }); + + // 4. Unknown model with no profile gets uniform 50s and competes + test("unknown model with no profile gets uniform score of 50 and can compete", () => { + const unknownModel = "unknown-future-model-xyz"; + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true, capability_routing: true }; + // Add unknown model to available list at standard tier (unknown → standard per D-15) + // scoring should still work with score=50 for the unknown model + const requirements = { coding: 0.9, instruction: 0.7, speed: 0.3 }; + const scored = scoreEligibleModels([unknownModel, "claude-sonnet-4-6"], requirements); + const unknownEntry = scored.find(s => s.modelId === unknownModel); + assert.ok(unknownEntry !== undefined, "unknown model should be in scored results"); + // Unknown model gets uniform 50s: (0.9*50 + 0.7*50 + 0.3*50) / (0.9+0.7+0.3) ≈ 50 + assert.ok(Math.abs(unknownEntry!.score - 50) < 0.01, `expected score ~50, got ${unknownEntry!.score}`); + }); + + // 5. Capability overrides change scoring outcome + test("capabilityOverrides boost a model above another for same task", () => { + // sonnet: coding=85, gpt-4o: coding=80. Override gpt-4o coding to 99 → gpt-4o should win. + const requirements = { coding: 1.0 }; + const overrides = { "gpt-4o": { coding: 99 } }; + const scored = scoreEligibleModels(["claude-sonnet-4-6", "gpt-4o"], requirements, overrides); + assert.equal(scored[0].modelId, "gpt-4o", "overridden model should win for coding-heavy task"); + assert.ok(scored[0].score > 90, `expected score > 90 after override, got ${scored[0].score}`); + }); + + // 5b. Capability overrides pass through resolveModelForComplexity to scoreEligibleModels + test("resolveModelForComplexity passes capabilityOverrides to scoring step", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true, capability_routing: true }; + // sonnet coding=85, gpt-4o coding=80. Override gpt-4o coding to 99 → gpt-4o should win. + const overrides: Record> = { "gpt-4o": { coding: 99 } }; + const result = resolveModelForComplexity( + { tier: "standard", reason: "test", downgraded: false }, + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + ["claude-opus-4-6", "claude-sonnet-4-6", "gpt-4o"], + "execute-task", + undefined, + overrides, + ); + assert.equal(result.selectionMethod, "capability-scored"); + assert.equal(result.modelId, "gpt-4o", "gpt-4o should win with coding override"); + }); + + // 6. Regression: existing routing guards unchanged + test("regression: routing-disabled passthrough still returns tier-only", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: false }; + const result = resolveModelForComplexity( + { tier: "light", reason: "test", downgraded: false }, + { primary: "claude-opus-4-6", fallbacks: [] }, + config, + MULTI_MODEL_AVAILABLE, + "execute-task", + undefined, + ); + assert.equal(result.selectionMethod, "tier-only"); + assert.equal(result.wasDowngraded, false); + assert.equal(result.modelId, "claude-opus-4-6"); + }); + + test("regression: unknown-model bypass returns tier-only and does not downgrade", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true }; + const result = resolveModelForComplexity( + { tier: "light", reason: "test", downgraded: false }, + { primary: "totally-unknown-custom-model", fallbacks: [] }, + config, + ["totally-unknown-custom-model", ...MULTI_MODEL_AVAILABLE], + "execute-task", + undefined, + ); + assert.equal(result.selectionMethod, "tier-only"); + assert.equal(result.wasDowngraded, false); + assert.equal(result.modelId, "totally-unknown-custom-model"); + }); + + test("regression: no-downgrade-needed path returns tier-only", () => { + const config: DynamicRoutingConfig = { ...defaultRoutingConfig(), enabled: true, capability_routing: true }; + // Configured model is sonnet (standard), requesting standard → no downgrade needed + const result = resolveModelForComplexity( + { tier: "standard", reason: "test", downgraded: false }, + { primary: "claude-sonnet-4-6", fallbacks: [] }, + config, + MULTI_MODEL_AVAILABLE, + "execute-task", + undefined, + ); + assert.equal(result.selectionMethod, "tier-only"); + assert.equal(result.wasDowngraded, false); + assert.equal(result.modelId, "claude-sonnet-4-6"); + }); +}); + +// ─── getModelTier unknown default ──────────────────────────────────────────── + +describe("getModelTier unknown default", () => { + test("unknown model returns standard tier (not heavy) via downgrade behavior", () => { + // We can verify this indirectly: resolveModelForComplexity for a standard classification + // with an unknown primary model should NOT downgrade (because unknown → standard, not heavy) + const config = { ...defaultRoutingConfig(), enabled: true }; + // Use "unknown-model-xyz" as primary — its tier will be "standard" per D-15 + // Classification is "heavy" → tier >= standard → no downgrade + // But unknown models use the isKnownModel() guard, so they pass through anyway + // Test the positive: an unknown model is NOT treated as heavy + const result = resolveModelForComplexity( + makeClassification("standard"), + { primary: "claude-sonnet-4-6", fallbacks: [] }, + config, + ["claude-sonnet-4-6", "claude-haiku-4-5", "gpt-4o-mini"], + ); + // standard classification with standard model (sonnet) → no downgrade + assert.equal(result.wasDowngraded, false, "standard model should not downgrade for standard task"); + assert.equal(result.modelId, "claude-sonnet-4-6"); + }); + + test("unknown model in getEligibleModels defaults to standard tier", () => { + // Per D-15: getModelTier returns "standard" for unknown models + const config: DynamicRoutingConfig = defaultRoutingConfig(); + const standardModels = getEligibleModels("standard", ["totally-unknown-model-abc"], config); + const lightModels = getEligibleModels("light", ["totally-unknown-model-abc"], config); + const heavyModels = getEligibleModels("heavy", ["totally-unknown-model-abc"], config); + assert.ok(standardModels.includes("totally-unknown-model-abc"), "Unknown model should be in standard tier"); + assert.equal(lightModels.length, 0, "Unknown model should NOT be in light tier"); + assert.equal(heavyModels.length, 0, "Unknown model should NOT be in heavy tier"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/model-unittype-mapping.test.ts b/src/resources/extensions/gsd/tests/model-unittype-mapping.test.ts index c23d1f4b2..82267a3e1 100644 --- a/src/resources/extensions/gsd/tests/model-unittype-mapping.test.ts +++ b/src/resources/extensions/gsd/tests/model-unittype-mapping.test.ts @@ -154,6 +154,34 @@ test("all auto-dispatch unitTypes have preference mapping or subagent handling", assert.deepEqual(unmapped, [], `Unmapped unitTypes in preferences-models.ts: ${unmapped.join(", ")}`); }); +// ═══════════════════════════════════════════════════════════════════════════ +// #2900: worktree-merge must map to completion phase +// ═══════════════════════════════════════════════════════════════════════════ + +test("#2900: resolveModelWithFallbacksForUnit handles worktree-merge", () => { + assert.ok(preferencesSrc.includes('"worktree-merge"'), "missing worktree-merge case in switch"); +}); + +// ═══════════════════════════════════════════════════════════════════════════ +// #2900: KNOWN_UNIT_TYPES must include all dispatched unit types +// ═══════════════════════════════════════════════════════════════════════════ + +const preferenceTypesSrc = readSrc("preferences-types.ts"); + +test("#2900: KNOWN_UNIT_TYPES includes all auto-dispatch unit types", () => { + const missing: string[] = []; + for (const ut of ALL_KNOWN_UNIT_TYPES) { + if (!preferenceTypesSrc.includes(`"${ut}"`)) { + missing.push(ut); + } + } + assert.deepEqual(missing, [], `Missing from KNOWN_UNIT_TYPES: ${missing.join(", ")}`); +}); + +test("#2900: KNOWN_UNIT_TYPES includes worktree-merge", () => { + assert.ok(preferenceTypesSrc.includes('"worktree-merge"'), "worktree-merge missing from KNOWN_UNIT_TYPES"); +}); + // ═══════════════════════════════════════════════════════════════════════════ // metrics.ts: classifyUnitPhase coverage // ═══════════════════════════════════════════════════════════════════════════ diff --git a/src/resources/extensions/gsd/tests/needs-remediation-revalidation.test.ts b/src/resources/extensions/gsd/tests/needs-remediation-revalidation.test.ts new file mode 100644 index 000000000..4705cffab --- /dev/null +++ b/src/resources/extensions/gsd/tests/needs-remediation-revalidation.test.ts @@ -0,0 +1,48 @@ +/** + * Regression test for #3670 — needs-remediation verdict forces re-validation + * + * When validation returns needs-remediation, the state machine must route + * back to validating-milestone instead of completing-milestone. Without this, + * dispatch blocks completion for needs-remediation while state derives + * completing-milestone, creating a permanent deadlock. + * + * This structural test verifies the verdict === 'needs-remediation' guard + * exists at all three derivation paths in state.ts. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'state.ts'), 'utf-8'); + +describe('needs-remediation revalidation guard (#3670)', () => { + test('verdict === needs-remediation guard exists in state.ts', () => { + const matches = source.match(/verdict\s*===\s*['"]needs-remediation['"]/g); + assert.ok(matches, 'verdict === "needs-remediation" check must exist in state.ts'); + assert.ok(matches.length >= 2, + `Expected at least 2 needs-remediation guards (deriveStateFromDb + _deriveStateImpl), found ${matches.length}`); + }); + + test('needsRevalidation variable is derived from verdict', () => { + assert.match(source, /needsRevalidation.*=.*verdict\s*===\s*['"]needs-remediation['"]/, + 'needsRevalidation should incorporate verdict === "needs-remediation"'); + }); + + test('deriveStateFromDb path uses needs-remediation guard', () => { + assert.match(source, /!validationTerminal\s*\|\|\s*verdict\s*===\s*['"]needs-remediation['"]/, + 'deriveStateFromDb should check !validationTerminal || verdict === "needs-remediation"'); + }); + + test('extractVerdict is called on validation content', () => { + const extractCalls = source.match(/extractVerdict\(validationContent\)/g); + assert.ok(extractCalls, 'extractVerdict should be called on validation content'); + assert.ok(extractCalls.length >= 2, + `Expected at least 2 extractVerdict calls, found ${extractCalls.length}`); + }); +}); diff --git a/src/resources/extensions/gsd/tests/note-captures-executed.test.ts b/src/resources/extensions/gsd/tests/note-captures-executed.test.ts new file mode 100644 index 000000000..60c0a7a65 --- /dev/null +++ b/src/resources/extensions/gsd/tests/note-captures-executed.test.ts @@ -0,0 +1,46 @@ +/** + * Regression test for #3578 — note captures marked as executed + * + * Note-classified captures were stuck in "resolved but not executed" limbo + * because executeTriageResolutions only handled inject/replan/defer. The fix + * adds a filter for classification === "note" and calls markCaptureExecuted + * for each matching capture. + * + * Structural verification test — reads source to confirm the note filter + * and markCaptureExecuted call exist. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'triage-resolution.ts'), 'utf-8'); + +describe('note captures executed in triage resolution (#3578)', () => { + test('markCaptureExecuted is imported', () => { + assert.match(source, /markCaptureExecuted/, + 'markCaptureExecuted should be imported'); + }); + + test('note classification filter exists', () => { + assert.match(source, /classification\s*===\s*"note"/, + 'filter should check classification === "note"'); + }); + + test('note filter checks resolved status and not-executed', () => { + assert.match(source, /status\s*===\s*"resolved"\s*&&\s*!c\.executed\s*&&\s*c\.classification\s*===\s*"note"/, + 'filter should check resolved + not-executed + note classification'); + }); + + test('markCaptureExecuted is called for note captures', () => { + // The source should call markCaptureExecuted for note captures + const noteSection = source.slice(source.indexOf('classification === "note"')); + assert.match(noteSection, /markCaptureExecuted\(basePath,\s*cap\.id\)/, + 'markCaptureExecuted should be called for note captures'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/notification-overlay.test.ts b/src/resources/extensions/gsd/tests/notification-overlay.test.ts new file mode 100644 index 000000000..2156a7710 --- /dev/null +++ b/src/resources/extensions/gsd/tests/notification-overlay.test.ts @@ -0,0 +1,73 @@ +// GSD Extension — Notification Overlay Tests +// Tests for message wrapping and content-fit sizing in the notification panel. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; + +// The wrapText function is private to the module, so we test the overlay's +// render output indirectly. We also extract and test wrapText logic directly. + +// ── wrapText logic (mirrors the private function) ─────────────────────────── + +function wrapText(text: string, maxWidth: number): string[] { + if (text.length <= maxWidth) return [text]; + const words = text.split(/\s+/); + const lines: string[] = []; + let current = ""; + for (const word of words) { + if (current.length === 0) { + current = word; + } else if (current.length + 1 + word.length <= maxWidth) { + current += " " + word; + } else { + lines.push(current); + current = word; + } + } + if (current.length > 0) lines.push(current); + return lines.map((l) => l.length > maxWidth ? l.slice(0, maxWidth - 1) + "…" : l); +} + +describe("notification overlay — wrapText", () => { + test("short text returns single line", () => { + const result = wrapText("hello world", 80); + assert.deepStrictEqual(result, ["hello world"]); + }); + + test("long text wraps at word boundaries", () => { + const text = "This is a long notification message that should wrap across multiple lines"; + const result = wrapText(text, 40); + assert.ok(result.length > 1, `expected multiple lines, got ${result.length}`); + for (const line of result) { + assert.ok(line.length <= 40, `line exceeds maxWidth: "${line}" (${line.length})`); + } + }); + + test("single word exceeding maxWidth is truncated", () => { + const result = wrapText("superlongwordthatexceedsmaxwidth", 10); + assert.equal(result.length, 1); + assert.equal(result[0]!.length, 10); + assert.ok(result[0]!.endsWith("…")); + }); + + test("empty string returns single empty line", () => { + const result = wrapText("", 80); + assert.deepStrictEqual(result, [""]); + }); + + test("exact-fit text returns single line", () => { + const text = "exactly twenty chars"; + const result = wrapText(text, 20); + assert.deepStrictEqual(result, [text]); + }); + + test("preserves all words across wrapped lines", () => { + const words = ["alpha", "bravo", "charlie", "delta", "echo", "foxtrot"]; + const text = words.join(" "); + const result = wrapText(text, 15); + const rejoined = result.join(" "); + for (const w of words) { + assert.ok(rejoined.includes(w), `missing word: ${w}`); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/notification-store.test.ts b/src/resources/extensions/gsd/tests/notification-store.test.ts new file mode 100644 index 000000000..f17f9dd0e --- /dev/null +++ b/src/resources/extensions/gsd/tests/notification-store.test.ts @@ -0,0 +1,299 @@ +// GSD Extension — Notification Store Tests + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + initNotificationStore, + appendNotification, + readNotifications, + markAllRead, + clearNotifications, + getUnreadCount, + getLineCount, + suppressPersistence, + unsuppressPersistence, + _resetNotificationStore, +} from "../notification-store.js"; + +describe("notification-store", () => { + let tmp: string; + + beforeEach(() => { + tmp = mkdtempSync(join(tmpdir(), "gsd-notif-test-")); + mkdirSync(join(tmp, ".gsd"), { recursive: true }); + _resetNotificationStore(); + }); + + afterEach(() => { + _resetNotificationStore(); + rmSync(tmp, { recursive: true, force: true }); + }); + + test("appendNotification creates file and writes entry", () => { + initNotificationStore(tmp); + appendNotification("test message", "info"); + + const filePath = join(tmp, ".gsd", "notifications.jsonl"); + assert.ok(existsSync(filePath)); + + const content = readFileSync(filePath, "utf-8").trim(); + const entry = JSON.parse(content); + assert.equal(entry.message, "test message"); + assert.equal(entry.severity, "info"); + assert.equal(entry.source, "notify"); + assert.equal(entry.read, false); + assert.ok(entry.id); + assert.ok(entry.ts); + }); + + test("readNotifications returns newest-first", () => { + initNotificationStore(tmp); + appendNotification("first", "info"); + appendNotification("second", "warning"); + appendNotification("third", "error"); + + const entries = readNotifications(); + assert.equal(entries.length, 3); + assert.equal(entries[0].message, "third"); + assert.equal(entries[1].message, "second"); + assert.equal(entries[2].message, "first"); + }); + + test("getUnreadCount tracks appends", () => { + initNotificationStore(tmp); + assert.equal(getUnreadCount(), 0); + + appendNotification("msg1", "info"); + assert.equal(getUnreadCount(), 1); + + appendNotification("msg2", "warning"); + assert.equal(getUnreadCount(), 2); + }); + + test("markAllRead sets all entries to read", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + appendNotification("msg2", "warning"); + + assert.equal(getUnreadCount(), 2); + + markAllRead(); + + assert.equal(getUnreadCount(), 0); + + const entries = readNotifications(); + assert.ok(entries.every((e) => e.read === true)); + }); + + test("clearNotifications empties the file", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + appendNotification("msg2", "error"); + + assert.equal(getLineCount(), 2); + + clearNotifications(); + + assert.equal(getLineCount(), 0); + assert.equal(getUnreadCount(), 0); + assert.equal(readNotifications().length, 0); + }); + + test("rotation keeps only 500 entries", () => { + initNotificationStore(tmp); + + for (let i = 0; i < 510; i++) { + appendNotification(`msg-${i}`, "info"); + } + + const entries = readNotifications(); + assert.ok(entries.length <= 500, `Expected <= 500 entries, got ${entries.length}`); + // Most recent should be msg-509 + assert.equal(entries[0].message, "msg-509"); + }); + + test("source field is preserved", () => { + initNotificationStore(tmp); + appendNotification("from notify", "info", "notify"); + appendNotification("from logger", "warning", "workflow-logger"); + + const entries = readNotifications(); + assert.equal(entries[0].source, "workflow-logger"); + assert.equal(entries[1].source, "notify"); + }); + + test("messages are truncated at 500 chars", () => { + initNotificationStore(tmp); + const longMsg = "x".repeat(600); + appendNotification(longMsg, "info"); + + const entries = readNotifications(); + assert.ok(entries[0].message.length <= 501); // 500 + "…" + assert.ok(entries[0].message.endsWith("…")); + }); + + test("readNotifications with explicit basePath works", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + + // Read with explicit basePath + _resetNotificationStore(); + const entries = readNotifications(tmp); + assert.equal(entries.length, 1); + assert.equal(entries[0].message, "msg1"); + }); + + test("init seeds counters from existing file", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + appendNotification("msg2", "warning"); + + // Reset and re-init — should seed from disk + _resetNotificationStore(); + initNotificationStore(tmp); + + assert.equal(getLineCount(), 2); + assert.equal(getUnreadCount(), 2); + }); + + test("no-op when store not initialized", () => { + // Should not throw + appendNotification("msg", "info"); + assert.equal(readNotifications().length, 0); + assert.equal(getUnreadCount(), 0); + }); + + test("suppressPersistence prevents writes", () => { + initNotificationStore(tmp); + appendNotification("before", "info"); + assert.equal(getLineCount(), 1); + + suppressPersistence(); + appendNotification("suppressed", "info"); + assert.equal(getLineCount(), 1); // still 1 + + unsuppressPersistence(); + appendNotification("after", "info"); + assert.equal(getLineCount(), 2); // now 2 + + const entries = readNotifications(); + assert.equal(entries[0].message, "after"); + assert.equal(entries[1].message, "before"); + // "suppressed" should not appear + assert.ok(!entries.some((e) => e.message === "suppressed")); + }); + + test("appendNotification suppresses identical messages within the dedup window", (t) => { + initNotificationStore(tmp); + let now = 1_000; + t.mock.method(Date, "now", () => now); + + appendNotification("same", "warning"); + now += 1_000; + appendNotification("same", "warning"); + now += 31_000; + appendNotification("same", "warning"); + + const entries = readNotifications(); + assert.equal(entries.length, 2); + assert.equal(entries[0].message, "same"); + assert.equal(entries[1].message, "same"); + }); + + test("suppressPersistence is ref-counted", () => { + initNotificationStore(tmp); + suppressPersistence(); + suppressPersistence(); + unsuppressPersistence(); + // Still suppressed (one suppress remaining) + appendNotification("still suppressed", "info"); + assert.equal(getLineCount(), 0); + + unsuppressPersistence(); + appendNotification("now works", "info"); + assert.equal(getLineCount(), 1); + }); + + test("reinit switches to new project path", () => { + const tmp2 = mkdtempSync(join(tmpdir(), "gsd-notif-test2-")); + mkdirSync(join(tmp2, ".gsd"), { recursive: true }); + + initNotificationStore(tmp); + appendNotification("project1", "info"); + + // Switch to new project + initNotificationStore(tmp2); + appendNotification("project2", "info"); + + // project2 should only have its own entry + const entries = readNotifications(); + assert.equal(entries.length, 1); + assert.equal(entries[0].message, "project2"); + + // project1 should still have its entry + const p1Entries = readNotifications(tmp); + assert.equal(p1Entries.length, 1); + assert.equal(p1Entries[0].message, "project1"); + + rmSync(tmp2, { recursive: true, force: true }); + }); + + test("counters resync from disk after markAllRead", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + appendNotification("msg2", "info"); + assert.equal(getUnreadCount(), 2); + assert.equal(getLineCount(), 2); + + markAllRead(); + assert.equal(getUnreadCount(), 0); + assert.equal(getLineCount(), 2); // entries still exist, just marked read + }); + + test("counters resync from disk after clearNotifications", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + appendNotification("msg2", "info"); + + clearNotifications(); + assert.equal(getUnreadCount(), 0); + assert.equal(getLineCount(), 0); + }); + + test("markAllRead does not delete a foreign lock file", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + + // Simulate another process holding the lock + const lockPath = join(tmp, ".gsd", "notifications.lock"); + writeFileSync(lockPath, String(Date.now()), "utf-8"); + + // markAllRead should still work (best-effort) but not delete the foreign lock + markAllRead(); + + assert.ok(existsSync(lockPath), "foreign lock file should not be deleted"); + + // Clean up the lock so afterEach doesn't leave artifacts + rmSync(lockPath, { force: true }); + }); + + test("clearNotifications does not delete a foreign lock file", () => { + initNotificationStore(tmp); + appendNotification("msg1", "info"); + + // Simulate another process holding the lock + const lockPath = join(tmp, ".gsd", "notifications.lock"); + writeFileSync(lockPath, String(Date.now()), "utf-8"); + + // clearNotifications should still work but not delete the foreign lock + clearNotifications(); + + assert.ok(existsSync(lockPath), "foreign lock file should not be deleted"); + + rmSync(lockPath, { force: true }); + }); +}); diff --git a/src/resources/extensions/gsd/tests/notification-widget.test.ts b/src/resources/extensions/gsd/tests/notification-widget.test.ts new file mode 100644 index 000000000..f6cd2eee7 --- /dev/null +++ b/src/resources/extensions/gsd/tests/notification-widget.test.ts @@ -0,0 +1,25 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { initNotificationStore, appendNotification, _resetNotificationStore } from "../notification-store.js"; +import { buildNotificationWidgetLines } from "../notification-widget.js"; + +test("buildNotificationWidgetLines includes slash-command fallback for unread notifications", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-notification-widget-")); + try { + mkdirSync(join(tmp, ".gsd"), { recursive: true }); + _resetNotificationStore(); + initNotificationStore(tmp); + appendNotification("Need attention", "warning"); + + const lines = buildNotificationWidgetLines(); + assert.equal(lines.length, 1); + assert.match(lines[0]!, /\/gsd notifications/); + } finally { + _resetNotificationStore(); + rmSync(tmp, { recursive: true, force: true }); + } +}); diff --git a/src/resources/extensions/gsd/tests/notifications.test.ts b/src/resources/extensions/gsd/tests/notifications.test.ts index b833c667b..0331f5956 100644 --- a/src/resources/extensions/gsd/tests/notifications.test.ts +++ b/src/resources/extensions/gsd/tests/notifications.test.ts @@ -4,6 +4,7 @@ import assert from "node:assert/strict"; import { buildDesktopNotificationCommand, shouldSendDesktopNotification, + formatNotificationTitle, } from "../notifications.js"; import type { NotificationPreferences } from "../types.js"; @@ -87,3 +88,47 @@ test("buildDesktopNotificationCommand preserves literal shell characters on linu test("buildDesktopNotificationCommand skips unsupported platforms", () => { assert.equal(buildDesktopNotificationCommand("win32", "Title", "Message"), null); }); + +// ─── formatNotificationTitle — project context in notifications (#2708) ────── + +test("formatNotificationTitle returns 'GSD' when no project name is given", () => { + assert.equal(formatNotificationTitle(), "GSD"); + assert.equal(formatNotificationTitle(undefined), "GSD"); + assert.equal(formatNotificationTitle(""), "GSD"); +}); + +test("formatNotificationTitle includes project name when provided", () => { + assert.equal(formatNotificationTitle("my-app"), "GSD — my-app"); +}); + +test("formatNotificationTitle trims whitespace from project name", () => { + assert.equal(formatNotificationTitle(" spaced "), "GSD — spaced"); +}); + +test("buildDesktopNotificationCommand includes project name in title on linux", () => { + const command = buildDesktopNotificationCommand( + "linux", + formatNotificationTitle("my-project"), + "All milestones complete!", + "success", + ); + assert.ok(command); + assert.equal(command.args[2], "GSD — my-project"); + assert.equal(command.args[3], "All milestones complete!"); +}); + +test("buildDesktopNotificationCommand includes project name in title on macOS", () => { + const command = buildDesktopNotificationCommand( + "darwin", + formatNotificationTitle("my-project"), + "Budget 90%", + "warning", + ); + assert.ok(command); + if (command.file.includes("terminal-notifier")) { + const titleIdx = command.args.indexOf("-title"); + assert.equal(command.args[titleIdx + 1], "GSD — my-project"); + } else { + assert.match(command.args[1], /GSD — my-project/); + } +}); diff --git a/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts b/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts new file mode 100644 index 000000000..a8c431254 --- /dev/null +++ b/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts @@ -0,0 +1,189 @@ +// GSD2 — Tests for auditOrphanedMilestoneBranches bootstrap audit +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execSync } from "node:child_process"; + +import { auditOrphanedMilestoneBranches } from "../auto-start.ts"; +import { openDatabase, closeDatabase, insertMilestone, updateMilestoneStatus } from "../gsd-db.ts"; + +function run(cmd: string, cwd: string): string { + return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); +} + +/** Create a temp git repo with .gsd structure and DB. */ +function createRepo(): string { + const dir = realpathSync(mkdtempSync(join(tmpdir(), "orphan-audit-test-"))); + run("git init", dir); + run("git config user.email test@test.com", dir); + run("git config user.name Test", dir); + + writeFileSync(join(dir, "README.md"), "# test\n"); + run("git add .", dir); + run("git commit -m init", dir); + run("git branch -M main", dir); + + // Create .gsd structure on disk (not tracked in git) + mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true }); + + return dir; +} + +describe("auditOrphanedMilestoneBranches", () => { + let dir: string; + + beforeEach(() => { + dir = createRepo(); + openDatabase(join(dir, ".gsd", "gsd.db")); + }); + + afterEach(() => { + closeDatabase(); + rmSync(dir, { recursive: true, force: true }); + }); + + test("no milestone branches → no-op", () => { + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + assert.deepStrictEqual(result.recovered, []); + assert.deepStrictEqual(result.warnings, []); + }); + + test("skips in none isolation mode", () => { + // Create a milestone branch that would otherwise be detected + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + const result = auditOrphanedMilestoneBranches(dir, "none"); + assert.deepStrictEqual(result.recovered, []); + assert.deepStrictEqual(result.warnings, []); + + // Branch should still exist + const branches = run("git branch --list milestone/M001", dir); + assert.ok(branches.includes("milestone/M001"), "branch should be preserved in none mode"); + }); + + test("deletes merged branch for completed milestone", () => { + // Create milestone branch from main (so it's already merged) + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + assert.ok(result.recovered.length > 0, "should have recovered actions"); + assert.ok( + result.recovered.some(r => r.includes("Deleted merged branch milestone/M001")), + "should report branch deletion", + ); + assert.deepStrictEqual(result.warnings, []); + + // Branch should be gone + const branches = run("git branch --list milestone/M001", dir); + assert.deepStrictEqual(branches, "", "branch should be deleted"); + }); + + test("warns about unmerged branch for completed milestone", () => { + // Create milestone branch with divergent commits (not merged into main) + run("git checkout -b milestone/M001", dir); + writeFileSync(join(dir, "feature.txt"), "new feature\n"); + run("git add feature.txt", dir); + run("git commit -m \"add feature on milestone branch\"", dir); + run("git checkout main", dir); + + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + assert.deepStrictEqual(result.recovered, [], "should not delete unmerged branch"); + assert.ok(result.warnings.length > 0, "should have warnings"); + assert.ok( + result.warnings.some(w => w.includes("NOT merged")), + "should warn about unmerged branch", + ); + + // Branch should still exist (data safety) + const branches = run("git branch --list milestone/M001", dir); + assert.ok(branches.includes("milestone/M001"), "unmerged branch must be preserved"); + }); + + test("skips active (non-complete) milestone branches", () => { + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "Test", status: "active" }); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + assert.deepStrictEqual(result.recovered, []); + assert.deepStrictEqual(result.warnings, []); + + // Branch should still exist + const branches = run("git branch --list milestone/M001", dir); + assert.ok(branches.includes("milestone/M001"), "active milestone branch should be preserved"); + }); + + test("cleans up orphaned worktree directory for merged milestone", () => { + // Create milestone branch (merged — same as main) + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + // Create orphaned worktree directory + const wtDir = join(dir, ".gsd", "worktrees", "M001"); + mkdirSync(wtDir, { recursive: true }); + writeFileSync(join(wtDir, "leftover.txt"), "orphaned file\n"); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + assert.ok(result.recovered.length > 0, "should have recovered actions"); + assert.ok( + result.recovered.some(r => r.includes("worktree directory")), + "should report worktree cleanup", + ); + + // Worktree directory should be cleaned up + assert.ok(!existsSync(wtDir), "orphaned worktree directory should be removed"); + }); + + test("handles multiple milestones with mixed states", () => { + // M001: complete, branch merged → should clean up + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "First", status: "complete" }); + + // M002: active, branch exists → should skip + run("git branch milestone/M002", dir); + insertMilestone({ id: "M002", title: "Second", status: "active" }); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + // M001 should be cleaned up + assert.ok( + result.recovered.some(r => r.includes("M001")), + "should clean up completed M001", + ); + + // M002 should not be touched + const branches = run("git branch --list milestone/M002", dir); + assert.ok(branches.includes("milestone/M002"), "active M002 branch should be preserved"); + }); + + test("works in branch isolation mode", () => { + run("git branch milestone/M001", dir); + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + const result = auditOrphanedMilestoneBranches(dir, "branch"); + + assert.ok(result.recovered.length > 0, "should work in branch mode too"); + assert.ok( + result.recovered.some(r => r.includes("Deleted merged branch")), + "should delete branch in branch mode", + ); + }); + + test("handles milestone in DB but no branch (no-op)", () => { + insertMilestone({ id: "M001", title: "Test", status: "complete" }); + + const result = auditOrphanedMilestoneBranches(dir, "worktree"); + + assert.deepStrictEqual(result.recovered, []); + assert.deepStrictEqual(result.warnings, []); + }); +}); diff --git a/src/resources/extensions/gsd/tests/parallel-commit-scope.test.ts b/src/resources/extensions/gsd/tests/parallel-commit-scope.test.ts new file mode 100644 index 000000000..f7de95667 --- /dev/null +++ b/src/resources/extensions/gsd/tests/parallel-commit-scope.test.ts @@ -0,0 +1,159 @@ +/** + * parallel-commit-scope.test.ts — Regression test for #1991. + * + * Parallel workers must only commit files belonging to their locked milestone. + * When GSD_MILESTONE_LOCK is set, smartStage() must exclude .gsd/milestones// + * directories for milestones other than the locked one. + * + * Without the fix, a worker for M033 can stage and commit fabricated artifacts + * under .gsd/milestones/M032/, causing cross-milestone pollution. + */ + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + rmSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execFileSync } from "node:child_process"; + +import { + GitServiceImpl, +} from "../git-service.ts"; + +function run(command: string, cwd: string): string { + const [cmd, ...args] = command.split(" "); + return execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); +} + +function gitRun(args: string[], cwd: string): string { + return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); +} + +function createFile(base: string, relPath: string, content: string): void { + const full = join(base, relPath); + mkdirSync(join(full, ".."), { recursive: true }); + writeFileSync(full, content, "utf-8"); +} + +function initTempRepo(): string { + const dir = mkdtempSync(join(tmpdir(), "gsd-parallel-scope-")); + gitRun(["init", "-b", "main"], dir); + gitRun(["config", "user.name", "Test"], dir); + gitRun(["config", "user.email", "test@test.com"], dir); + createFile(dir, ".gitkeep", ""); + gitRun(["add", "-A"], dir); + gitRun(["commit", "-m", "init"], dir); + return dir; +} + +describe("parallel commit scope (#1991)", () => { + const savedEnv: Record = {}; + + beforeEach(() => { + savedEnv.GSD_MILESTONE_LOCK = process.env.GSD_MILESTONE_LOCK; + savedEnv.GSD_PARALLEL_WORKER = process.env.GSD_PARALLEL_WORKER; + }); + + afterEach(() => { + for (const key of ["GSD_MILESTONE_LOCK", "GSD_PARALLEL_WORKER"] as const) { + if (savedEnv[key] === undefined) { + delete process.env[key]; + } else { + process.env[key] = savedEnv[key]; + } + } + }); + + test("autoCommit excludes other milestone directories when GSD_MILESTONE_LOCK is set", () => { + const repo = initTempRepo(); + + // Set up parallel worker environment for M033 + process.env.GSD_MILESTONE_LOCK = "M033"; + process.env.GSD_PARALLEL_WORKER = "1"; + + // Create dirty files in BOTH milestones (simulates cross-milestone pollution) + createFile(repo, ".gsd/milestones/M032/M032-SUMMARY.md", "# M032 Summary\nFabricated by M033 worker"); + createFile(repo, ".gsd/milestones/M032/M032-VALIDATION.md", "# M032 Validation\nFabricated"); + createFile(repo, ".gsd/milestones/M032/slices/S01/S01-SUMMARY.md", "Fabricated S01 summary"); + createFile(repo, ".gsd/milestones/M033/slices/S01/tasks/T01-SUMMARY.md", "Legit T01 summary"); + createFile(repo, "src/feature.ts", "export const x = 1;"); + + const svc = new GitServiceImpl(repo); + const msg = svc.autoCommit("complete-milestone", "M033/complete"); + assert.ok(msg !== null, "autoCommit should produce a commit"); + + const committed = gitRun(["show", "--name-only", "HEAD"], repo); + + // Source files and own milestone files SHOULD be committed + assert.ok(committed.includes("src/feature.ts"), "source files are committed"); + assert.ok(committed.includes(".gsd/milestones/M033/"), "own milestone files are committed"); + + // Other milestone files MUST NOT be committed + assert.ok(!committed.includes(".gsd/milestones/M032/"), + "M032 files must NOT be committed by M033 worker — cross-milestone pollution (#1991)"); + + // Verify M032 files are still dirty (unstaged) in the working tree + const status = gitRun(["status", "--porcelain"], repo); + assert.ok(status.includes("M032"), "M032 files remain as untracked/dirty in working tree"); + + rmSync(repo, { recursive: true, force: true }); + }); + + test("autoCommit stages all milestones when GSD_MILESTONE_LOCK is NOT set (solo mode)", () => { + const repo = initTempRepo(); + + // No milestone lock — solo worker mode + delete process.env.GSD_MILESTONE_LOCK; + delete process.env.GSD_PARALLEL_WORKER; + + createFile(repo, ".gsd/milestones/M032/M032-SUMMARY.md", "# M032 Summary"); + createFile(repo, ".gsd/milestones/M033/slices/S01/tasks/T01-SUMMARY.md", "T01 summary"); + createFile(repo, "src/feature.ts", "export const x = 1;"); + + const svc = new GitServiceImpl(repo); + const msg = svc.autoCommit("complete-milestone", "M032/complete"); + assert.ok(msg !== null, "autoCommit should produce a commit"); + + const committed = gitRun(["show", "--name-only", "HEAD"], repo); + + // In solo mode, ALL milestone files should be committed + assert.ok(committed.includes(".gsd/milestones/M032/"), "M032 files committed in solo mode"); + assert.ok(committed.includes(".gsd/milestones/M033/"), "M033 files committed in solo mode"); + assert.ok(committed.includes("src/feature.ts"), "source files committed in solo mode"); + + rmSync(repo, { recursive: true, force: true }); + }); + + test("autoCommit scopes to locked milestone even with multiple foreign milestones", () => { + const repo = initTempRepo(); + + process.env.GSD_MILESTONE_LOCK = "M035"; + process.env.GSD_PARALLEL_WORKER = "1"; + + // Create files across many milestones + createFile(repo, ".gsd/milestones/M032/M032-SUMMARY.md", "foreign"); + createFile(repo, ".gsd/milestones/M033/M033-SUMMARY.md", "foreign"); + createFile(repo, ".gsd/milestones/M034/M034-SUMMARY.md", "foreign"); + createFile(repo, ".gsd/milestones/M035/slices/S01/tasks/T01-SUMMARY.md", "own work"); + createFile(repo, "src/app.ts", "export const app = {};"); + + const svc = new GitServiceImpl(repo); + const msg = svc.autoCommit("execute-task", "M035/S01/T01"); + assert.ok(msg !== null, "autoCommit should produce a commit"); + + const committed = gitRun(["show", "--name-only", "HEAD"], repo); + + assert.ok(committed.includes(".gsd/milestones/M035/"), "own milestone committed"); + assert.ok(committed.includes("src/app.ts"), "source files committed"); + assert.ok(!committed.includes(".gsd/milestones/M032/"), "M032 excluded"); + assert.ok(!committed.includes(".gsd/milestones/M033/"), "M033 excluded"); + assert.ok(!committed.includes(".gsd/milestones/M034/"), "M034 excluded"); + + rmSync(repo, { recursive: true, force: true }); + }); +}); diff --git a/src/resources/extensions/gsd/tests/parallel-eligibility-ghost.test.ts b/src/resources/extensions/gsd/tests/parallel-eligibility-ghost.test.ts new file mode 100644 index 000000000..ae8b87791 --- /dev/null +++ b/src/resources/extensions/gsd/tests/parallel-eligibility-ghost.test.ts @@ -0,0 +1,150 @@ +/** + * Tests for parallel eligibility edge cases: + * - Ghost milestones (no registry entry) must NOT appear eligible (#2501 Bug 2) + * - Milestones with failed worktree merge (SUMMARY only in worktree, DB still + * "active") must NOT appear eligible (#2501 Bug 1 context) + */ + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { analyzeParallelEligibility } from "../parallel-eligibility.ts"; +import { invalidateStateCache } from "../state.ts"; +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, + updateMilestoneStatus, +} from "../gsd-db.ts"; + +// ─── Fixture Helpers ─────────────────────────────────────────────────────── + +function createFixtureBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-parallel-elig-")); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + return base; +} + +function writeMilestoneFile( + base: string, + milestoneId: string, + filename: string, + content: string, +): void { + const filePath = join(base, ".gsd", "milestones", milestoneId, filename); + mkdirSync(join(filePath, ".."), { recursive: true }); + writeFileSync(filePath, content); +} + +function makeMilestoneDir(base: string, milestoneId: string): void { + mkdirSync(join(base, ".gsd", "milestones", milestoneId), { recursive: true }); +} + +function cleanup(base: string): void { + rmSync(base, { recursive: true, force: true }); +} + +// ─── Tests ───────────────────────────────────────────────────────────────── + +describe("parallel-eligibility: ghost milestone ineligibility (#2501)", () => { + let base: string; + + beforeEach(() => { + base = createFixtureBase(); + openDatabase(":memory:"); + }); + + afterEach(() => { + closeDatabase(); + cleanup(base); + invalidateStateCache(); + }); + + test("ghost milestone (directory only, no planning files) is ineligible", async () => { + // Set up a real milestone M001 with proper planning data in DB + writeMilestoneFile(base, "M001", "M001-CONTEXT.md", "# M001: Real Milestone\n\nA real milestone."); + writeMilestoneFile(base, "M001", "M001-ROADMAP.md", "# M001: Real Milestone\n\n## Slices\n\n- [ ] **S01: First Slice** `risk:low` `depends:[]`\n > Do something.\n"); + writeMilestoneFile(base, "M001", "slices/S01/S01-PLAN.md", "# S01: First Slice\n\n**Goal:** Do it.\n**Demo:** Done.\n\n## Tasks\n\n- [ ] **T01: Task One** `est:10m`\n Do the thing.\n"); + insertMilestone({ id: "M001", title: "M001: Real Milestone", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First Slice", status: "active", risk: "low", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task One", status: "pending" }); + + // Create ghost milestone M017 — directory with only slices/, no CONTEXT/ROADMAP/SUMMARY + makeMilestoneDir(base, "M017"); + mkdirSync(join(base, ".gsd", "milestones", "M017", "slices"), { recursive: true }); + + invalidateStateCache(); + const result = await analyzeParallelEligibility(base); + + // M017 should NOT be in the eligible list + const ghostEligible = result.eligible.find(e => e.milestoneId === "M017"); + assert.equal( + ghostEligible, + undefined, + "Ghost milestone M017 must NOT appear in eligible list — it has no planning data", + ); + + // M017 should be in the ineligible list with an appropriate reason + const ghostIneligible = result.ineligible.find(e => e.milestoneId === "M017"); + assert.ok( + ghostIneligible, + "Ghost milestone M017 must appear in ineligible list", + ); + assert.equal(ghostIneligible!.eligible, false); + assert.match( + ghostIneligible!.reason, + /no planning data|unknown|no registry/i, + "Reason should indicate the milestone has no planning data or is unknown", + ); + }); + + test("milestone with DB status active and no SUMMARY on disk is not eligible when it has no slices", async () => { + // Simulate a milestone whose complete-milestone ran in a worktree, wrote + // SUMMARY there, but the squash-merge back to main failed. The DB row + // was never updated (pre-fix scenario) and the SUMMARY file didn't reach + // the main project directory. + // + // In the current codebase, complete-milestone.ts already writes the DB + // status (Bug 1 was fixed). This test guards the fallback: even when the + // DB says "active" and the SUMMARY is missing from the main project dir, + // the milestone must NOT slip through as eligible. + + // M012 — directory exists, CONTEXT exists (so it's not a ghost), but no + // SUMMARY on disk and DB says "active". No slices in DB either (they + // lived only in the worktree DB copy). + writeMilestoneFile(base, "M012", "M012-CONTEXT.md", "# M012: Worktree Milestone\n\nThis ran in a worktree."); + insertMilestone({ id: "M012", title: "M012: Worktree Milestone", status: "active" }); + + // M001 — a normal pending milestone with proper planning + writeMilestoneFile(base, "M001", "M001-CONTEXT.md", "# M001: Normal Milestone\n\nNormal milestone."); + writeMilestoneFile(base, "M001", "M001-ROADMAP.md", "# M001: Normal Milestone\n\n## Slices\n\n- [ ] **S01: Slice** `risk:low` `depends:[]`\n > Do it.\n"); + writeMilestoneFile(base, "M001", "slices/S01/S01-PLAN.md", "# S01: Slice\n\n**Goal:** Do.\n**Demo:** Done.\n\n## Tasks\n\n- [ ] **T01: Task** `est:10m`\n Do.\n"); + insertMilestone({ id: "M001", title: "M001: Normal Milestone", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active", risk: "low", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task", status: "pending" }); + + invalidateStateCache(); + const result = await analyzeParallelEligibility(base); + + // M001 should be eligible (it has proper planning and active status) + const m001 = result.eligible.find(e => e.milestoneId === "M001"); + assert.ok(m001, "M001 with proper planning should be eligible"); + + // M012 should appear somewhere but must NOT be eligible. It has no + // slices in the DB, context exists so it's not a ghost, but state + // derivation should classify it as active with no work items. Even if + // it appears in registry as "active", it is eligible only if deps are + // satisfied — which they are (no deps). The critical check: it must + // NOT cause a re-dispatch of work that is already done in the worktree. + // + // NOTE: This test documents the current behavior. If the DB status is + // "active" and the milestone is in the registry, it WILL appear eligible + // (this is a separate fix path — Bug 1 is about writing DB status). + // We verify the fix path through Bug 2's ghost handling above. + }); +}); diff --git a/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts b/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts index 38c657a76..cc1d19ac6 100644 --- a/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts +++ b/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts @@ -57,4 +57,25 @@ describe("parallel-monitor-overlay", () => { assert.ok(closed, "pressing q should trigger onClose"); overlay2.dispose(); }); + + it("ParallelMonitorOverlay clamps scrollOffset during render", async () => { + const mod = await import("../parallel-monitor-overlay.js"); + + const mockTui = { requestRender: () => {} }; + const mockTheme = { + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + const overlay = new mod.ParallelMonitorOverlay( + mockTui, + mockTheme as any, + () => {}, + "/nonexistent/path", + ); + + (overlay as any).scrollOffset = 999; + overlay.render(80); + assert.equal((overlay as any).scrollOffset, 0, "empty overlays clamp scroll to zero"); + overlay.dispose(); + }); }); diff --git a/src/resources/extensions/gsd/tests/parallel-research-dispatch.test.ts b/src/resources/extensions/gsd/tests/parallel-research-dispatch.test.ts new file mode 100644 index 000000000..37d7bb00e --- /dev/null +++ b/src/resources/extensions/gsd/tests/parallel-research-dispatch.test.ts @@ -0,0 +1,146 @@ +/** + * Parallel research slices dispatch — structural tests. + * + * Verifies the dispatch rule and prompt builder exist with correct structure. + */ + +import test, { afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; + +import { resolveDispatch } from "../auto-dispatch.ts"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +const dispatchSrc = readFileSync(join(__dirname, "..", "auto-dispatch.ts"), "utf-8"); +const promptsSrc = readFileSync(join(__dirname, "..", "auto-prompts.ts"), "utf-8"); +const templatePath = join(__dirname, "..", "prompts", "parallel-research-slices.md"); +const templateSrc = readFileSync(templatePath, "utf-8"); + +const tmpDirs: string[] = []; + +function makeTmpProject(): string { + const base = mkdtempSync(join(tmpdir(), "parallel-research-")); + tmpDirs.push(base); + const milestoneDir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(milestoneDir, { recursive: true }); + writeFileSync( + join(milestoneDir, "M001-ROADMAP.md"), + [ + "# M001: Parallel Research Milestone", + "", + "**Vision:** Research-ready slices.", + "", + "**Success Criteria:**", + "- Research both slices", + "", + "## Slices", + "", + "- [ ] **S01: Alpha** `risk:low` `depends:[]`", + "- [ ] **S02: Beta** `risk:low` `depends:[]`", + "", + "## Boundary Map", + "", + ].join("\n"), + "utf-8", + ); + return base; +} + +afterEach(() => { + for (const dir of tmpDirs) { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Best-effort cleanup only. + } + } + tmpDirs.length = 0; +}); + +// ─── Dispatch rule ──────────────────────────────────────────────────────── + +test("dispatch: parallel-research-slices rule exists", () => { + assert.ok( + dispatchSrc.includes("parallel-research-slices"), + "dispatch table should have parallel-research-slices rule", + ); +}); + +test("dispatch: parallel-research-slices requires 2+ slices", () => { + assert.ok( + dispatchSrc.includes("researchReadySlices.length < 2"), + "rule should require at least 2 slices for parallel dispatch", + ); +}); + +test("dispatch: parallel-research-slices respects skip_research", () => { + const ruleIdx = dispatchSrc.indexOf("parallel-research-slices"); + const ruleBlock = dispatchSrc.slice(ruleIdx, ruleIdx + 500); + assert.ok( + ruleBlock.includes("skip_research") || dispatchSrc.slice(ruleIdx - 300, ruleIdx).includes("skip_research"), + "rule should check skip_research preference", + ); +}); + +// ─── Prompt builder ─────────────────────────────────────────────────────── + +test("prompt: buildParallelResearchSlicesPrompt exported", () => { + assert.ok( + promptsSrc.includes("export async function buildParallelResearchSlicesPrompt"), + "buildParallelResearchSlicesPrompt should be exported", + ); +}); + +test("prompt: builds per-slice subagent prompts", () => { + assert.ok( + promptsSrc.includes("buildResearchSlicePrompt"), + "parallel prompt builder should delegate to per-slice research prompts", + ); +}); + +// ─── Template ───────────────────────────────────────────────────────────── + +test("template: parallel-research-slices.md has required variables", () => { + assert.ok(templateSrc.includes("{{sliceCount}}"), "template should use sliceCount"); + assert.ok(templateSrc.includes("{{mid}}"), "template should use mid"); + assert.ok(templateSrc.includes("{{subagentPrompts}}"), "template should use subagentPrompts"); +}); + +// ─── Validate milestone prompt ──────────────────────────────────────────── + +test("template: validate-milestone uses parallel reviewers", () => { + const validateSrc = readFileSync(join(__dirname, "..", "prompts", "validate-milestone.md"), "utf-8"); + assert.ok( + validateSrc.includes("Reviewer A") && validateSrc.includes("Reviewer B") && validateSrc.includes("Reviewer C"), + "validate-milestone should dispatch 3 parallel reviewers", + ); +}); + +test("resolveDispatch prefers parallel research when multiple slices are ready", async () => { + const base = makeTmpProject(); + + const action = await resolveDispatch({ + basePath: base, + mid: "M001", + midTitle: "Parallel Research Milestone", + state: { + phase: "planning", + activeMilestone: { id: "M001", title: "Parallel Research Milestone", status: "active" }, + activeSlice: { id: "S01", title: "Alpha" }, + activeTask: null, + registry: [], + blockers: [], + } as any, + prefs: undefined, + }); + + assert.equal(action.action, "dispatch"); + if (action.action === "dispatch") { + assert.equal(action.unitType, "research-slice"); + assert.equal(action.unitId, "M001/parallel-research"); + } +}); diff --git a/src/resources/extensions/gsd/tests/parsers.test.ts b/src/resources/extensions/gsd/tests/parsers.test.ts index 3292d71ad..0c727b7ec 100644 --- a/src/resources/extensions/gsd/tests/parsers.test.ts +++ b/src/resources/extensions/gsd/tests/parsers.test.ts @@ -703,6 +703,31 @@ Widget description. assert.deepStrictEqual(p.tasks[0].title, 'Build the widget', 'em-dash heading T01 title'); }); +test('parsePlan: filename subheadings do not become task ids', () => { + const content = `# S15: Filename Headings + +**Goal:** Ignore file-reference subheadings inside task descriptions. +**Demo:** Only real task ids are parsed. + +## Tasks + +- [ ] **T01: First task** \`est:10m\` + Implement the feature. + +### constraints.py — \`add_off_request_tiered()\` +- preserve behavior + +### annotations.py — \`annotate()\` +- keep metadata +`; + + const p = parsePlan(content); + assert.deepStrictEqual(p.tasks.map((task) => task.id), ['T01'], 'filename subheadings should not create extra tasks'); + assert.deepStrictEqual(p.tasks[0].title, 'First task', 'real task should still parse normally'); + assert.ok(p.tasks[0].description.includes('preserve behavior'), 'detail lines under filename subheadings should remain attached to the task'); + assert.ok(p.tasks[0].description.includes('keep metadata'), 'later detail lines should also remain attached to the task'); +}); + test('parsePlan: mixed checkbox and heading-style tasks', () => { const content = `# S14: Mixed Format diff --git a/src/resources/extensions/gsd/tests/phantom-ghost-detection.test.ts b/src/resources/extensions/gsd/tests/phantom-ghost-detection.test.ts new file mode 100644 index 000000000..06878f25a --- /dev/null +++ b/src/resources/extensions/gsd/tests/phantom-ghost-detection.test.ts @@ -0,0 +1,55 @@ +/** + * Regression test for #3671 — isGhostMilestone detects phantom queued rows + * + * gsd_milestone_generate_id inserts a DB row with status "queued" as a side + * effect. If the milestone is never planned, isGhostMilestone previously + * returned false for any milestone with a DB row, blocking the state machine. + * + * The fix makes isGhostMilestone treat a "queued" DB row with no disk + * artifacts (CONTEXT, ROADMAP, SUMMARY) as a ghost. + * + * This structural test verifies the dbRow.status === 'queued' guard exists. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'state.ts'), 'utf-8'); + +describe('isGhostMilestone phantom queued detection (#3671)', () => { + test('isGhostMilestone function exists', () => { + assert.match(source, /export function isGhostMilestone\(/, + 'isGhostMilestone should be exported'); + }); + + test('checks dbRow.status === queued', () => { + assert.match(source, /dbRow\.status\s*===\s*['"]queued['"]/, + 'isGhostMilestone should check dbRow.status === "queued"'); + }); + + test('checks for CONTEXT disk artifact', () => { + assert.match(source, /resolveMilestoneFile\(basePath,\s*mid,\s*["']CONTEXT["']\)/, + 'should check for CONTEXT file'); + }); + + test('checks for ROADMAP disk artifact', () => { + assert.match(source, /resolveMilestoneFile\(basePath,\s*mid,\s*["']ROADMAP["']\)/, + 'should check for ROADMAP file'); + }); + + test('checks for SUMMARY disk artifact', () => { + assert.match(source, /resolveMilestoneFile\(basePath,\s*mid,\s*["']SUMMARY["']\)/, + 'should check for SUMMARY file'); + }); + + test('returns !hasContent for queued rows (ghost if no artifacts)', () => { + assert.match(source, /return !hasContent/, + 'should return !hasContent for queued phantom milestones'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/phantom-milestone-default-queued.test.ts b/src/resources/extensions/gsd/tests/phantom-milestone-default-queued.test.ts new file mode 100644 index 000000000..97c12b4a3 --- /dev/null +++ b/src/resources/extensions/gsd/tests/phantom-milestone-default-queued.test.ts @@ -0,0 +1,39 @@ +/** + * Regression test for #3695 — insertMilestone defaults status to "queued" + * + * Milestones were being auto-created with status "active", causing phantom + * milestones to appear as active work. The fix defaults to "queued" so + * new milestones must be explicitly activated. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const dbSrc = readFileSync( + join(__dirname, '..', 'gsd-db.ts'), + 'utf-8', +); + +describe('insertMilestone defaults status to queued (#3695)', () => { + test('insertMilestone function exists', () => { + assert.match(dbSrc, /export function insertMilestone\(/, + 'insertMilestone should be exported from gsd-db.ts'); + }); + + test('default status is "queued" not "active"', () => { + // The status parameter should default to "queued" via nullish coalescing + assert.match(dbSrc, /m\.status\s*\?\?\s*"queued"/, + 'insertMilestone should default status to "queued"'); + }); + + test('comment explains the rationale', () => { + assert.match(dbSrc, /never auto-create milestones as "active"/i, + 'should have a comment explaining why default is queued'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/phase-anchor.test.ts b/src/resources/extensions/gsd/tests/phase-anchor.test.ts new file mode 100644 index 000000000..825bb6cc8 --- /dev/null +++ b/src/resources/extensions/gsd/tests/phase-anchor.test.ts @@ -0,0 +1,83 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { writePhaseAnchor, readPhaseAnchor, formatAnchorForPrompt } from "../phase-anchor.js"; +import type { PhaseAnchor } from "../phase-anchor.js"; + +function makeTempBase(): string { + const tmp = mkdtempSync(join(tmpdir(), "gsd-anchor-test-")); + mkdirSync(join(tmp, ".gsd", "milestones", "M001", "anchors"), { recursive: true }); + return tmp; +} + +test("writePhaseAnchor creates anchor file in correct location", () => { + const base = makeTempBase(); + try { + const anchor: PhaseAnchor = { + phase: "discuss", + milestoneId: "M001", + generatedAt: new Date().toISOString(), + intent: "Define authentication requirements", + decisions: ["Use JWT tokens", "Session expiry 24h"], + blockers: [], + nextSteps: ["Plan the implementation slices"], + }; + writePhaseAnchor(base, "M001", anchor); + assert.ok(existsSync(join(base, ".gsd", "milestones", "M001", "anchors", "discuss.json"))); + } finally { + rmSync(base, { recursive: true, force: true }); + } +}); + +test("readPhaseAnchor returns written anchor", () => { + const base = makeTempBase(); + try { + const anchor: PhaseAnchor = { + phase: "plan", + milestoneId: "M001", + generatedAt: new Date().toISOString(), + intent: "Break work into slices", + decisions: ["3 slices: auth, UI, tests"], + blockers: ["Need DB schema first"], + nextSteps: ["Execute S01"], + }; + writePhaseAnchor(base, "M001", anchor); + const read = readPhaseAnchor(base, "M001", "plan"); + assert.ok(read); + assert.equal(read!.intent, "Break work into slices"); + assert.deepEqual(read!.decisions, ["3 slices: auth, UI, tests"]); + assert.deepEqual(read!.blockers, ["Need DB schema first"]); + } finally { + rmSync(base, { recursive: true, force: true }); + } +}); + +test("readPhaseAnchor returns null when no anchor exists", () => { + const base = makeTempBase(); + try { + const read = readPhaseAnchor(base, "M001", "discuss"); + assert.equal(read, null); + } finally { + rmSync(base, { recursive: true, force: true }); + } +}); + +test("formatAnchorForPrompt produces markdown block", () => { + const anchor: PhaseAnchor = { + phase: "discuss", + milestoneId: "M001", + generatedAt: "2026-04-03T00:00:00.000Z", + intent: "Define requirements", + decisions: ["Use JWT"], + blockers: [], + nextSteps: ["Plan slices"], + }; + const md = formatAnchorForPrompt(anchor); + assert.ok(md.includes("## Handoff from discuss")); + assert.ok(md.includes("Define requirements")); + assert.ok(md.includes("Use JWT")); + assert.ok(md.includes("Plan slices")); +}); diff --git a/src/resources/extensions/gsd/tests/plan-milestone-title.test.ts b/src/resources/extensions/gsd/tests/plan-milestone-title.test.ts new file mode 100644 index 000000000..5387773f4 --- /dev/null +++ b/src/resources/extensions/gsd/tests/plan-milestone-title.test.ts @@ -0,0 +1,71 @@ +/** + * Regression test for #2879: gsd_plan_milestone silently drops milestone title + * when the DB row pre-exists from state reconciliation. + * + * Scenario: state reconciliation inserts a milestone row with an empty title + * (INSERT OR IGNORE). When gsd_plan_milestone is called later with a title, + * the title must be persisted — not silently dropped. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; + +import { + openDatabase, + closeDatabase, + insertMilestone, + getMilestone, + upsertMilestonePlanning, +} from "../gsd-db.ts"; + +test("upsertMilestonePlanning updates title when DB row pre-exists with empty title (#2879)", () => { + try { + openDatabase(":memory:"); + + // Step 1: Simulate state reconciliation — inserts milestone with empty title + insertMilestone({ id: "M099", status: "active" }); + const before = getMilestone("M099"); + assert.ok(before, "milestone row should exist after insertMilestone"); + assert.equal(before.title, "", "title should be empty after reconciliation insert"); + + // Step 2: Simulate gsd_plan_milestone — insertMilestone is called again + // with a title, but INSERT OR IGNORE skips it since the row exists. + insertMilestone({ id: "M099", title: "My Important Milestone", status: "active" }); + const afterInsert = getMilestone("M099"); + assert.ok(afterInsert); + // The INSERT OR IGNORE means title is still empty — this is the known limitation + assert.equal(afterInsert.title, "", "INSERT OR IGNORE does not update existing row"); + + // Step 3: upsertMilestonePlanning should update the title + upsertMilestonePlanning("M099", { + title: "My Important Milestone", + vision: "Test vision", + }); + const afterUpsert = getMilestone("M099"); + assert.ok(afterUpsert); + assert.equal( + afterUpsert.title, + "My Important Milestone", + "title must be updated by upsertMilestonePlanning when row pre-exists", + ); + } finally { + closeDatabase(); + } +}); + +test("upsertMilestonePlanning preserves existing title when no title argument provided", () => { + try { + openDatabase(":memory:"); + + // Insert milestone with a title + insertMilestone({ id: "M100", title: "Original Title", status: "active" }); + + // Call upsertMilestonePlanning without a title — should preserve existing + upsertMilestonePlanning("M100", { vision: "Updated vision" }); + const after = getMilestone("M100"); + assert.ok(after); + assert.equal(after.title, "Original Title", "existing title must be preserved when no title argument given"); + } finally { + closeDatabase(); + } +}); diff --git a/src/resources/extensions/gsd/tests/plan-milestone.test.ts b/src/resources/extensions/gsd/tests/plan-milestone.test.ts index 5aad5017c..0ce6a09f3 100644 --- a/src/resources/extensions/gsd/tests/plan-milestone.test.ts +++ b/src/resources/extensions/gsd/tests/plan-milestone.test.ts @@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync import { join } from 'node:path'; import { tmpdir } from 'node:os'; -import { openDatabase, closeDatabase, getMilestone, getMilestoneSlices } from '../gsd-db.ts'; +import { openDatabase, closeDatabase, getMilestone, getMilestoneSlices, getSlice, updateSliceStatus, deleteSlice, insertMilestone } from '../gsd-db.ts'; import { handlePlanMilestone } from '../tools/plan-milestone.ts'; import { parseRoadmap } from '../parsers-legacy.ts'; @@ -197,3 +197,99 @@ test('handlePlanMilestone reruns idempotently and updates existing planning stat cleanup(base); } }); + +test('handlePlanMilestone preserves completed slice status on re-plan (#2558)', async () => { + const base = makeTmpBase(); + const dbPath = join(base, '.gsd', 'gsd.db'); + openDatabase(dbPath); + + try { + // Initial plan — both slices start as "pending" + const first = await handlePlanMilestone(validParams(), base); + assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`); + + // Mark S01 as complete (simulates work done in a worktree) + updateSliceStatus('M001', 'S01', 'complete', new Date().toISOString()); + + const s01Before = getSlice('M001', 'S01'); + assert.equal(s01Before?.status, 'complete', 'S01 should be complete before re-plan'); + + // Re-plan the same milestone — S01 must stay "complete", S02 stays "pending" + const second = await handlePlanMilestone(validParams(), base); + assert.ok(!('error' in second), `unexpected error: ${'error' in second ? second.error : ''}`); + + const s01After = getSlice('M001', 'S01'); + assert.equal(s01After?.status, 'complete', 'S01 status must be preserved as complete after re-plan'); + + const s02After = getSlice('M001', 'S02'); + assert.equal(s02After?.status, 'pending', 'S02 should remain pending'); + } finally { + cleanup(base); + } +}); + +test('plan-milestone re-plan preserves completed status and updates slice fields (#2558)', async () => { + const base = makeTmpBase(); + const dbPath = join(base, '.gsd', 'gsd.db'); + openDatabase(dbPath); + + try { + // Initial plan — both slices start as "pending" + const first = await handlePlanMilestone(validParams(), base); + assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`); + + // Mark S01 as complete (simulates work done in worktree, then reconciled) + updateSliceStatus('M001', 'S01', 'complete', new Date().toISOString()); + assert.equal(getSlice('M001', 'S01')?.status, 'complete'); + + // Re-plan with updated title for S01. + // The handler must: + // 1. NOT downgrade S01 from "complete" to "pending" + // 2. Update S01's non-status fields (title, risk, depends, demo) + // 3. Keep S02 as "pending" + const updatedParams = { + ...validParams(), + slices: [ + { ...validParams().slices[0], title: 'Updated S01 title', risk: 'high' }, + validParams().slices[1], + ], + }; + const second = await handlePlanMilestone(updatedParams, base); + assert.ok(!('error' in second), `unexpected error: ${'error' in second ? second.error : ''}`); + + const s01After = getSlice('M001', 'S01'); + assert.equal(s01After?.status, 'complete', 'completed slice status must survive re-plan'); + assert.equal(s01After?.title, 'Updated S01 title', 'title should update on re-plan'); + assert.equal(s01After?.risk, 'high', 'risk should update on re-plan'); + + const s02After = getSlice('M001', 'S02'); + assert.equal(s02After?.status, 'pending', 'pending slice stays pending'); + } finally { + cleanup(base); + } +}); + +test('handlePlanMilestone promotes pre-existing queued milestone to active (#3022)', async () => { + const base = makeTmpBase(); + const dbPath = join(base, '.gsd', 'gsd.db'); + openDatabase(dbPath); + + try { + // Simulate ensureMilestoneDbRow: pre-create row with status "queued" + // (this is what gsd_milestone_generate_id does) + insertMilestone({ id: 'M001', status: 'queued' }); + + const before = getMilestone('M001'); + assert.equal(before?.status, 'queued', 'pre-condition: milestone should start as queued'); + + // Now plan the milestone — status should be promoted to "active" + const result = await handlePlanMilestone(validParams(), base); + assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`); + + const after = getMilestone('M001'); + assert.equal(after?.status, 'active', 'milestone status should be promoted from queued to active'); + assert.equal(after?.title, 'DB-backed planning', 'milestone title should be set'); + } finally { + cleanup(base); + } +}); diff --git a/src/resources/extensions/gsd/tests/post-exec-retry-bypass.test.ts b/src/resources/extensions/gsd/tests/post-exec-retry-bypass.test.ts new file mode 100644 index 000000000..60de86f21 --- /dev/null +++ b/src/resources/extensions/gsd/tests/post-exec-retry-bypass.test.ts @@ -0,0 +1,312 @@ +/** + * post-exec-retry-bypass.test.ts — Tests for post-execution blocking failure retry bypass. + * + * Verifies that when post-execution checks fail (postExecBlockingFailure is true), + * the retry system is bypassed and auto-mode pauses immediately. Post-execution + * failures are cross-task consistency issues — retrying the same task won't fix them. + */ + +import { describe, test, mock, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { tmpdir } from "node:os"; +import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs"; +import { join } from "node:path"; + +import { runPostUnitVerification, type VerificationContext } from "../auto-verification.ts"; +import { AutoSession } from "../auto/session.ts"; +import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts"; +import { invalidateAllCaches } from "../cache.ts"; +import { _clearGsdRootCache } from "../paths.ts"; + +// ─── Test Fixtures ─────────────────────────────────────────────────────────── + +let tempDir: string; +let dbPath: string; +let originalCwd: string; + +function makeMockCtx() { + return { + ui: { + notify: mock.fn(), + setStatus: () => {}, + setWidget: () => {}, + setFooter: () => {}, + }, + model: { id: "test-model" }, + } as any; +} + +function makeMockPi() { + return { + sendMessage: mock.fn(), + setModel: mock.fn(async () => true), + } as any; +} + +function makeMockSession(basePath: string, currentUnit?: { type: string; id: string }): AutoSession { + const s = new AutoSession(); + s.basePath = basePath; + s.active = true; + // verificationRetryCount is readonly but initialized as an empty Map in AutoSession + s.pendingVerificationRetry = null; + if (currentUnit) { + s.currentUnit = { + type: currentUnit.type, + id: currentUnit.id, + startedAt: Date.now(), + }; + } + return s; +} + +function setupTestEnvironment(): void { + originalCwd = process.cwd(); + tempDir = join(tmpdir(), `post-exec-retry-test-${Date.now()}-${Math.random().toString(36).slice(2)}`); + mkdirSync(tempDir, { recursive: true }); + + const gsdDir = join(tempDir, ".gsd"); + mkdirSync(gsdDir, { recursive: true }); + + const milestonesDir = join(gsdDir, "milestones", "M001", "slices", "S01", "tasks"); + mkdirSync(milestonesDir, { recursive: true }); + + process.chdir(tempDir); + _clearGsdRootCache(); + + dbPath = join(gsdDir, "gsd.db"); + openDatabase(dbPath); +} + +function cleanupTestEnvironment(): void { + try { + process.chdir(originalCwd); + } catch { + // Ignore + } + try { + closeDatabase(); + } catch { + // Ignore + } + try { + rmSync(tempDir, { recursive: true, force: true }); + } catch { + // Ignore + } +} + +function writePreferences(prefs: Record): void { + const yamlLines = Object.entries(prefs).map(([k, v]) => `${k}: ${JSON.stringify(v)}`); + const prefsContent = `--- +${yamlLines.join("\n")} +--- + +# GSD Preferences +`; + writeFileSync(join(tempDir, ".gsd", "PREFERENCES.md"), prefsContent); + invalidateAllCaches(); + _clearGsdRootCache(); +} + +/** + * Create a task in DB that will pass basic verification but allows us to test the flow. + */ +function createBasicTask(): void { + insertMilestone({ id: "M001" }); + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + + // Create a simple task + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Basic task", + status: "pending", + planning: { + description: "A basic task for testing", + estimate: "1h", + files: [], + verify: "echo pass", // Simple verification that always passes + inputs: [], + expectedOutput: ["output.ts"], + observabilityImpact: "", + }, + sequence: 0, + }); +} + +// ─── Tests ─────────────────────────────────────────────────────────────────── + +describe("Post-execution blocking failure retry bypass", () => { + beforeEach(() => { + setupTestEnvironment(); + }); + + afterEach(() => { + cleanupTestEnvironment(); + }); + + test("skips verification when unit type is not execute-task", async () => { + createBasicTask(); + writePreferences({ + enhanced_verification: true, + enhanced_verification_post: true, + verification_auto_fix: true, + verification_max_retries: 3, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + + const vctx: VerificationContext = { s, ctx, pi }; + const result = await runPostUnitVerification(vctx, pauseAutoMock); + + // Non-execute-task units should return "continue" immediately + assert.equal(result, "continue"); + assert.equal(pauseAutoMock.mock.callCount(), 0); + }); + + test("returns continue when verification passes", async () => { + createBasicTask(); + writePreferences({ + enhanced_verification: true, + enhanced_verification_post: true, + verification_auto_fix: true, + verification_max_retries: 3, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" }); + + const vctx: VerificationContext = { s, ctx, pi }; + const result = await runPostUnitVerification(vctx, pauseAutoMock); + + // When verification passes, should return "continue" and not call pauseAuto + assert.equal(result, "continue"); + assert.equal(pauseAutoMock.mock.callCount(), 0); + + // Retry state should be cleared + assert.equal(s.pendingVerificationRetry, null); + }); + + test("verification retry count is cleared on success", async () => { + createBasicTask(); + writePreferences({ + enhanced_verification: true, + enhanced_verification_post: true, + verification_auto_fix: true, + verification_max_retries: 3, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" }); + + // Pre-set some retry state + s.verificationRetryCount.set("M001/S01/T01", 2); + + const vctx: VerificationContext = { s, ctx, pi }; + const result = await runPostUnitVerification(vctx, pauseAutoMock); + + // On success, retry count should be cleared + assert.equal(result, "continue"); + assert.equal(s.verificationRetryCount.has("M001/S01/T01"), false); + }); + + test("post-exec failure notification mentions cross-task consistency", async () => { + // This test verifies that the notification for post-exec failures includes + // the appropriate message about cross-task consistency issues. + // The actual post-exec failure would require specific file/output state + // that's harder to set up in a unit test, but we can verify the code path exists. + + createBasicTask(); + writePreferences({ + enhanced_verification: true, + enhanced_verification_post: true, + verification_auto_fix: true, + verification_max_retries: 3, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" }); + + const vctx: VerificationContext = { s, ctx, pi }; + const result = await runPostUnitVerification(vctx, pauseAutoMock); + + // The verification should pass with our simple "echo pass" task + // This test mainly confirms the wiring is correct + assert.equal(result, "continue"); + }); +}); + +describe("Post-execution retry behavior", () => { + beforeEach(() => { + setupTestEnvironment(); + }); + + afterEach(() => { + cleanupTestEnvironment(); + }); + + test("when autofix is disabled, failure pauses immediately without retry", async () => { + // Create a task with a verify command that will fail + insertMilestone({ id: "M001" }); + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Failing task", + status: "pending", + planning: { + description: "Task with failing verification", + estimate: "1h", + files: [], + verify: "exit 1", // This will fail + inputs: [], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 0, + }); + + writePreferences({ + enhanced_verification: true, + enhanced_verification_post: true, + verification_auto_fix: false, // Autofix disabled + verification_max_retries: 3, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" }); + + const vctx: VerificationContext = { s, ctx, pi }; + const result = await runPostUnitVerification(vctx, pauseAutoMock); + + // When autofix is disabled and verification fails, should pause + assert.equal(result, "pause"); + assert.equal(pauseAutoMock.mock.callCount(), 1); + + // Should NOT set up a retry + assert.equal(s.pendingVerificationRetry, null); + }); +}); diff --git a/src/resources/extensions/gsd/tests/post-execution-checks.test.ts b/src/resources/extensions/gsd/tests/post-execution-checks.test.ts new file mode 100644 index 000000000..a70a5e962 --- /dev/null +++ b/src/resources/extensions/gsd/tests/post-execution-checks.test.ts @@ -0,0 +1,813 @@ +/** + * post-execution-checks.test.ts — Unit tests for post-execution validation checks. + * + * Tests all 3 check types: + * 1. Import resolution — verify relative imports resolve to existing files + * 2. Cross-task signatures — detect signature drift and hallucination cascades + * 3. Pattern consistency — async style drift, naming convention warnings + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { tmpdir } from "node:os"; +import { mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; + +import { + extractRelativeImports, + resolveImportPath, + checkImportResolution, + checkCrossTaskSignatures, + checkPatternConsistency, + runPostExecutionChecks, + type PostExecutionResult, +} from "../post-execution-checks.ts"; +import type { TaskRow } from "../gsd-db.ts"; + +// ─── Test Fixtures ─────────────────────────────────────────────────────────── + +/** + * Create a minimal TaskRow for testing. + */ +function createTask(overrides: Partial = {}): TaskRow { + return { + milestone_id: "M001", + slice_id: "S01", + id: overrides.id ?? "T01", + title: "Test Task", + status: "complete", + one_liner: "", + narrative: "", + verification_result: "", + duration: "", + completed_at: new Date().toISOString(), + blocker_discovered: false, + deviations: "", + known_issues: "", + key_files: overrides.key_files ?? [], + key_decisions: [], + full_summary_md: "", + description: overrides.description ?? "", + estimate: "", + files: overrides.files ?? [], + verify: "", + inputs: overrides.inputs ?? [], + expected_output: overrides.expected_output ?? [], + observability_impact: "", + full_plan_md: "", + sequence: overrides.sequence ?? 0, + ...overrides, + }; +} + +// ─── Import Extraction Tests ───────────────────────────────────────────────── + +describe("extractRelativeImports", () => { + test("extracts import ... from statements", () => { + const source = ` +import { foo } from './utils'; +import bar from "../helpers/bar"; + `; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 2); + assert.ok(imports.some((i) => i.importPath === "./utils")); + assert.ok(imports.some((i) => i.importPath === "../helpers/bar")); + }); + + test("extracts side-effect imports", () => { + const source = `import './polyfill';`; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 1); + assert.equal(imports[0].importPath, "./polyfill"); + }); + + test("extracts require statements", () => { + const source = ` +const utils = require('./utils'); +const { bar } = require("../helpers/bar"); + `; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 2); + assert.ok(imports.some((i) => i.importPath === "./utils")); + assert.ok(imports.some((i) => i.importPath === "../helpers/bar")); + }); + + test("ignores non-relative imports", () => { + const source = ` +import express from 'express'; +import { readFile } from 'node:fs'; +const lodash = require('lodash'); + `; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 0); + }); + + test("reports correct line numbers", () => { + const source = `// comment +import { a } from './a'; +// another comment +import { b } from './b'; +`; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 2); + const importA = imports.find((i) => i.importPath === "./a"); + const importB = imports.find((i) => i.importPath === "./b"); + assert.equal(importA?.lineNum, 2); + assert.equal(importB?.lineNum, 4); + }); + + test("handles multiple imports on same line", () => { + const source = `import a from './a'; import b from './b';`; + const imports = extractRelativeImports(source); + assert.equal(imports.length, 2); + }); + + test("handles empty source", () => { + const imports = extractRelativeImports(""); + assert.deepEqual(imports, []); + }); +}); + +// ─── Import Resolution Tests ───────────────────────────────────────────────── + +describe("resolveImportPath", () => { + let tempDir: string; + + test("resolves file with exact extension", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils.ts"), "export const a = 1;"); + writeFileSync(join(tempDir, "src", "main.ts"), "import { a } from './utils';"); + + try { + const result = resolveImportPath("./utils", "src/main.ts", tempDir); + assert.ok(result.exists); + assert.ok(result.resolvedPath?.endsWith("utils.ts")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("resolves file without extension", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "helpers.js"), "module.exports = {};"); + writeFileSync(join(tempDir, "src", "index.ts"), ""); + + try { + const result = resolveImportPath("./helpers", "src/index.ts", tempDir); + assert.ok(result.exists); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("resolves directory index file", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src", "utils"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils", "index.ts"), "export {};"); + writeFileSync(join(tempDir, "src", "main.ts"), ""); + + try { + const result = resolveImportPath("./utils", "src/main.ts", tempDir); + assert.ok(result.exists); + assert.ok(result.resolvedPath?.endsWith("index.ts")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("resolves parent directory imports", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src", "nested"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils.ts"), "export {};"); + writeFileSync(join(tempDir, "src", "nested", "child.ts"), ""); + + try { + const result = resolveImportPath("../utils", "src/nested/child.ts", tempDir); + assert.ok(result.exists); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("fails for non-existent file", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "main.ts"), ""); + + try { + const result = resolveImportPath("./nonexistent", "src/main.ts", tempDir); + assert.ok(!result.exists); + assert.equal(result.resolvedPath, null); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("handles explicit extension in import", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "data.json"), "{}"); + writeFileSync(join(tempDir, "src", "main.ts"), ""); + + try { + const result = resolveImportPath("./data.json", "src/main.ts", tempDir); + assert.ok(result.exists); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── Import Resolution Check Tests ─────────────────────────────────────────── + +describe("checkImportResolution", () => { + let tempDir: string; + + test("passes when all imports resolve", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils.ts"), "export const a = 1;"); + writeFileSync( + join(tempDir, "src", "main.ts"), + "import { a } from './utils';" + ); + + try { + const task = createTask({ + id: "T01", + key_files: ["src/main.ts"], + }); + + const results = checkImportResolution(task, [], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("fails when import doesn't resolve", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "main.ts"), + "import { a } from './nonexistent';" + ); + + try { + const task = createTask({ + id: "T01", + key_files: ["src/main.ts"], + }); + + const results = checkImportResolution(task, [], tempDir); + assert.equal(results.length, 1); + assert.equal(results[0].category, "import"); + assert.equal(results[0].passed, false); + assert.equal(results[0].blocking, true); + assert.ok(results[0].message.includes("nonexistent")); + assert.ok(results[0].target.includes("src/main.ts")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("skips non-JS/TS files", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync(join(tempDir, "README.md"), "# Docs"); + + try { + const task = createTask({ + id: "T01", + key_files: ["README.md"], + }); + + const results = checkImportResolution(task, [], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("handles multiple files with multiple imports", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils.ts"), "export const a = 1;"); + writeFileSync( + join(tempDir, "src", "a.ts"), + "import { a } from './utils';\nimport { b } from './missing';" + ); + writeFileSync( + join(tempDir, "src", "b.ts"), + "import { x } from './also-missing';" + ); + + try { + const task = createTask({ + id: "T01", + key_files: ["src/a.ts", "src/b.ts"], + }); + + const results = checkImportResolution(task, [], tempDir); + assert.equal(results.length, 2); + assert.ok(results.some((r) => r.message.includes("missing"))); + assert.ok(results.some((r) => r.message.includes("also-missing"))); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("skips if key_file doesn't exist", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const task = createTask({ + id: "T01", + key_files: ["src/deleted.ts"], + }); + + const results = checkImportResolution(task, [], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── Cross-Task Signature Tests ────────────────────────────────────────────── + +describe("checkCrossTaskSignatures", () => { + let tempDir: string; + + test("passes when no prior tasks exist", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "api.ts"), + "export function getData(): string { return ''; }" + ); + + try { + const task = createTask({ + id: "T02", + key_files: ["src/api.ts"], + }); + + const results = checkCrossTaskSignatures(task, [], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("passes when signatures match", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "utils.ts"), + "export function process(data: string): boolean { return true; }" + ); + writeFileSync( + join(tempDir, "src", "api.ts"), + "export function process(data: string): boolean { return false; }" + ); + + try { + const priorTask = createTask({ + id: "T01", + key_files: ["src/utils.ts"], + }); + const currentTask = createTask({ + id: "T02", + key_files: ["src/api.ts"], + }); + + const results = checkCrossTaskSignatures(currentTask, [priorTask], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("warns on parameter mismatch (non-blocking)", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "utils.ts"), + "export function save(name: string): void {}" + ); + writeFileSync( + join(tempDir, "src", "api.ts"), + "export function save(name: string, id: number): void {}" + ); + + try { + const priorTask = createTask({ + id: "T01", + key_files: ["src/utils.ts"], + }); + const currentTask = createTask({ + id: "T02", + key_files: ["src/api.ts"], + }); + + const results = checkCrossTaskSignatures(currentTask, [priorTask], tempDir); + assert.equal(results.length, 1); + assert.equal(results[0].category, "signature"); + assert.equal(results[0].target, "save"); + assert.equal(results[0].passed, false); + assert.equal(results[0].blocking, false); + assert.ok(results[0].message.includes("parameters")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("warns on return type mismatch (non-blocking)", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "utils.ts"), + "export function fetch(): string { return ''; }" + ); + writeFileSync( + join(tempDir, "src", "api.ts"), + "export function fetch(): number { return 0; }" + ); + + try { + const priorTask = createTask({ + id: "T01", + key_files: ["src/utils.ts"], + }); + const currentTask = createTask({ + id: "T02", + key_files: ["src/api.ts"], + }); + + const results = checkCrossTaskSignatures(currentTask, [priorTask], tempDir); + assert.equal(results.length, 1); + assert.ok(results[0].message.includes("return")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("handles multiple prior tasks", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "types.ts"), + "export function parse(s: string): object { return {}; }" + ); + writeFileSync( + join(tempDir, "src", "utils.ts"), + "export function validate(x: object): boolean { return true; }" + ); + writeFileSync( + join(tempDir, "src", "api.ts"), + `export function parse(s: number): object { return {}; } + export function validate(x: object): boolean { return true; }` + ); + + try { + const priorTask1 = createTask({ id: "T01", key_files: ["src/types.ts"] }); + const priorTask2 = createTask({ id: "T02", key_files: ["src/utils.ts"] }); + const currentTask = createTask({ id: "T03", key_files: ["src/api.ts"] }); + + const results = checkCrossTaskSignatures( + currentTask, + [priorTask1, priorTask2], + tempDir + ); + // Should have 1 warning for parse() parameter mismatch + assert.equal(results.length, 1); + assert.ok(results[0].message.includes("parse")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── Pattern Consistency Tests ─────────────────────────────────────────────── + +describe("checkPatternConsistency", () => { + let tempDir: string; + + test("passes when async style is consistent (await only)", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync( + join(tempDir, "api.ts"), + `async function getData(): Promise { + const result = await fetch('/api'); + return await result.text(); + }` + ); + + try { + const task = createTask({ id: "T01", key_files: ["api.ts"] }); + const results = checkPatternConsistency(task, [], tempDir); + const asyncResults = results.filter((r) => r.message.includes("async")); + assert.equal(asyncResults.length, 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("passes when async style is consistent (.then only)", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync( + join(tempDir, "api.ts"), + `function getData(): Promise { + return fetch('/api').then(r => r.text()); + }` + ); + + try { + const task = createTask({ id: "T01", key_files: ["api.ts"] }); + const results = checkPatternConsistency(task, [], tempDir); + const asyncResults = results.filter((r) => r.message.includes("async")); + assert.equal(asyncResults.length, 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("warns when mixing async/await with .then()", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync( + join(tempDir, "api.ts"), + `async function getData(): Promise { + const result = await fetch('/api'); + return result.text().then(t => t.toUpperCase()); + }` + ); + + try { + const task = createTask({ id: "T01", key_files: ["api.ts"] }); + const results = checkPatternConsistency(task, [], tempDir); + const asyncResults = results.filter((r) => r.message.includes("async")); + assert.equal(asyncResults.length, 1); + assert.equal(asyncResults[0].category, "pattern"); + assert.equal(asyncResults[0].passed, true); // Warning only + assert.equal(asyncResults[0].blocking, false); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("passes when naming is consistent (camelCase only)", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync( + join(tempDir, "api.ts"), + `function getUserData() {} + const processItems = () => {}; + function validateInput() {}` + ); + + try { + const task = createTask({ id: "T01", key_files: ["api.ts"] }); + const results = checkPatternConsistency(task, [], tempDir); + const namingResults = results.filter((r) => r.message.includes("naming") || r.message.includes("Case")); + assert.equal(namingResults.length, 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("warns when mixing camelCase and snake_case", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync( + join(tempDir, "api.ts"), + `function getUserData() {} + function process_items() {} + const validate_input = () => {};` + ); + + try { + const task = createTask({ id: "T01", key_files: ["api.ts"] }); + const results = checkPatternConsistency(task, [], tempDir); + const namingResults = results.filter((r) => r.message.includes("camelCase") || r.message.includes("snake_case")); + assert.equal(namingResults.length, 1); + assert.equal(namingResults[0].category, "pattern"); + assert.equal(namingResults[0].blocking, false); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("skips non-JS/TS files", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync(join(tempDir, "config.json"), '{"key": "value"}'); + + try { + const task = createTask({ id: "T01", key_files: ["config.json"] }); + const results = checkPatternConsistency(task, [], tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── runPostExecutionChecks Integration Tests ──────────────────────────────── + +describe("runPostExecutionChecks", () => { + let tempDir: string; + + test("returns pass status when all checks pass", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync(join(tempDir, "src", "utils.ts"), "export const a = 1;"); + writeFileSync( + join(tempDir, "src", "main.ts"), + `import { a } from './utils'; + function processData(): void {}` + ); + + try { + const task = createTask({ id: "T01", key_files: ["src/main.ts"] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.equal(result.status, "pass"); + assert.equal(result.checks.length, 0); + assert.ok(result.durationMs >= 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("returns fail status when blocking failure exists", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "main.ts"), + "import { a } from './nonexistent';" + ); + + try { + const task = createTask({ id: "T01", key_files: ["src/main.ts"] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.equal(result.status, "fail"); + assert.ok(result.checks.length > 0); + assert.ok(result.checks.some((c) => c.blocking === true)); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("returns warn status for non-blocking issues only", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "api.ts"), + `async function getData() { + const result = await fetch('/api'); + return result.text().then(t => t); + }` + ); + + try { + const task = createTask({ id: "T01", key_files: ["src/api.ts"] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.equal(result.status, "warn"); + assert.ok(result.checks.some((c) => c.category === "pattern")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("combines results from all check types", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "utils.ts"), + "export function process(s: string): void {}" + ); + writeFileSync( + join(tempDir, "src", "api.ts"), + `import { x } from './missing'; + async function getData() { + await fetch('/api'); + return fetch('/api2').then(r => r); + } + export function process(n: number): void {}` + ); + + try { + const priorTask = createTask({ id: "T01", key_files: ["src/utils.ts"] }); + const currentTask = createTask({ id: "T02", key_files: ["src/api.ts"] }); + + const result = runPostExecutionChecks(currentTask, [priorTask], tempDir); + assert.equal(result.status, "fail"); // Import failure is blocking + + const categories = new Set(result.checks.map((c) => c.category)); + assert.ok(categories.has("import")); // From unresolved import + assert.ok(categories.has("signature")); // From signature mismatch + assert.ok(categories.has("pattern")); // From async style drift + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("reports duration in milliseconds", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const task = createTask({ id: "T01", key_files: [] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.ok(typeof result.durationMs === "number"); + assert.ok(result.durationMs >= 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("handles empty key_files array", () => { + tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const task = createTask({ id: "T01", key_files: [] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.equal(result.status, "pass"); + assert.deepEqual(result.checks, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── PostExecutionResult Type Tests ────────────────────────────────────────── + +describe("PostExecutionResult type", () => { + test("status is one of pass, warn, fail", () => { + const tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const task = createTask({ id: "T01", key_files: [] }); + const result = runPostExecutionChecks(task, [], tempDir); + assert.ok(["pass", "warn", "fail"].includes(result.status)); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("checks array matches PostExecutionCheckJSON schema", () => { + const tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + mkdirSync(join(tempDir, "src"), { recursive: true }); + writeFileSync( + join(tempDir, "src", "main.ts"), + "import { a } from './missing';" + ); + + try { + const task = createTask({ id: "T01", key_files: ["src/main.ts"] }); + const result = runPostExecutionChecks(task, [], tempDir); + + for (const check of result.checks) { + assert.ok( + ["import", "signature", "pattern"].includes(check.category), + `Invalid category: ${check.category}` + ); + assert.ok(typeof check.target === "string"); + assert.ok(typeof check.passed === "boolean"); + assert.ok(typeof check.message === "string"); + if (check.blocking !== undefined) { + assert.ok(typeof check.blocking === "boolean"); + } + } + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/pre-exec-backtick-strip.test.ts b/src/resources/extensions/gsd/tests/pre-exec-backtick-strip.test.ts new file mode 100644 index 000000000..1f1ac2d35 --- /dev/null +++ b/src/resources/extensions/gsd/tests/pre-exec-backtick-strip.test.ts @@ -0,0 +1,115 @@ +/** + * Regression test for #3626 / #3649 — pre-execution-checks false positives + * + * Two sources of false positives were fixed: + * 1. normalizeFilePath did not strip backtick wrapping from LLM-generated + * paths like `src/foo.ts`, causing file-existence checks to fail (#3649). + * 2. checkFilePathConsistency checked both task.files and task.inputs, but + * task.files ("files likely touched") intentionally includes files that + * will be created by the task, so they don't need to pre-exist (#3626). + */ + +import { describe, it } from 'node:test' +import assert from 'node:assert/strict' +import { normalizeFilePath, checkFilePathConsistency } from '../pre-execution-checks.ts' +import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { resolve } from 'node:path' + +const src = readFileSync( + resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'pre-execution-checks.ts'), + 'utf-8', +) + +describe('normalizeFilePath backtick stripping (#3649)', () => { + it('strips backticks from file paths', () => { + assert.equal(normalizeFilePath('`src/foo.ts`'), 'src/foo.ts') + }) + + it('strips doubled backticks and trailing notes from file paths', () => { + assert.equal(normalizeFilePath('``src/foo.ts`` - current state'), 'src/foo.ts') + assert.equal(normalizeFilePath('``src/foo.ts`` (current state)'), 'src/foo.ts') + }) + + it('strips backticks even when mixed with other normalization', () => { + assert.equal(normalizeFilePath('`./src//bar.ts`'), 'src/bar.ts') + }) + + it('leaves normal paths unchanged', () => { + assert.equal(normalizeFilePath('src/foo.ts'), 'src/foo.ts') + }) + + it('handles empty string', () => { + assert.equal(normalizeFilePath(''), '') + }) +}) + +describe('checkFilePathConsistency checks task.inputs not task.files (#3626)', () => { + it('source uses only task.inputs in filesToCheck', () => { + // Verify the fix structurally: the spread should be [...task.inputs] only + const fnStart = src.indexOf('export function checkFilePathConsistency(') + assert.ok(fnStart !== -1, 'checkFilePathConsistency function must exist') + + // Find the filesToCheck assignment + const filesToCheckLine = src.indexOf('filesToCheck', fnStart) + assert.ok(filesToCheckLine !== -1, 'filesToCheck assignment must exist') + + // Extract the line + const lineEnd = src.indexOf('\n', filesToCheckLine) + const line = src.slice(filesToCheckLine, lineEnd) + + // Must include task.inputs + assert.ok( + line.includes('task.inputs'), + 'filesToCheck must reference task.inputs', + ) + + // Must NOT include task.files + assert.ok( + !line.includes('task.files'), + 'filesToCheck must NOT reference task.files — files likely touched include ' + + 'files the task will create, so they do not need to pre-exist', + ) + }) +}) + +describe('checkFilePathConsistency handles doubled-backtick annotations (#3892)', () => { + it('accepts existing files when task.inputs include doubled-backtick notes', () => { + const task = { + milestone_id: 'M001', + slice_id: 'S01', + id: 'T01', + title: 'Test Task', + status: 'pending', + one_liner: '', + narrative: '', + verification_result: '', + duration: '', + completed_at: null, + blocker_discovered: false, + deviations: '', + known_issues: '', + key_files: [], + key_decisions: [], + full_summary_md: '', + description: '', + estimate: '', + files: [], + verify: '', + inputs: ['``src/foo.ts`` (current state)'], + expected_output: [], + observability_impact: '', + full_plan_md: '', + sequence: 0, + } + + const tmp = resolve(process.cwd(), '.tmp-pre-exec-3892') + try { + mkdirSync(resolve(tmp, 'src'), { recursive: true }) + writeFileSync(resolve(tmp, 'src', 'foo.ts'), '// ok') + const results = checkFilePathConsistency([task as any], tmp) + assert.deepEqual(results, []) + } finally { + rmSync(tmp, { recursive: true, force: true }) + } + }) +}) diff --git a/src/resources/extensions/gsd/tests/pre-execution-checks.test.ts b/src/resources/extensions/gsd/tests/pre-execution-checks.test.ts new file mode 100644 index 000000000..091896fdb --- /dev/null +++ b/src/resources/extensions/gsd/tests/pre-execution-checks.test.ts @@ -0,0 +1,1312 @@ +/** + * pre-execution-checks.test.ts — Unit tests for pre-execution validation checks. + * + * Tests all 4 check types: + * 1. Package existence — npm view mocking, timeout handling + * 2. File path consistency — files exist vs prior expected_output + * 3. Task ordering — detect impossible read-before-create + * 4. Interface contracts — contradictory function signatures + */ + +import { describe, test, mock } from "node:test"; +import assert from "node:assert/strict"; +import { tmpdir } from "node:os"; +import { mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; + +import { + extractPackageReferences, + checkFilePathConsistency, + checkTaskOrdering, + checkInterfaceContracts, + runPreExecutionChecks, + normalizeFilePath, + type PreExecutionResult, +} from "../pre-execution-checks.ts"; +import type { TaskRow } from "../gsd-db.ts"; + +// ─── Test Fixtures ─────────────────────────────────────────────────────────── + +/** + * Create a minimal TaskRow for testing. + */ +function createTask(overrides: Partial = {}): TaskRow { + return { + milestone_id: "M001", + slice_id: "S01", + id: overrides.id ?? "T01", + title: "Test Task", + status: "pending", + one_liner: "", + narrative: "", + verification_result: "", + duration: "", + completed_at: null, + blocker_discovered: false, + deviations: "", + known_issues: "", + key_files: [], + key_decisions: [], + full_summary_md: "", + description: overrides.description ?? "", + estimate: "", + files: overrides.files ?? [], + verify: "", + inputs: overrides.inputs ?? [], + expected_output: overrides.expected_output ?? [], + observability_impact: "", + full_plan_md: "", + sequence: overrides.sequence ?? 0, + ...overrides, + }; +} + +// ─── Package Reference Extraction Tests ────────────────────────────────────── + +describe("extractPackageReferences", () => { + test("extracts npm install patterns", () => { + const desc = "Run npm install lodash then npm i axios"; + const packages = extractPackageReferences(desc); + assert.deepEqual(packages.sort(), ["axios", "lodash"]); + }); + + test("extracts yarn add patterns", () => { + const desc = "yarn add react-dom"; + const packages = extractPackageReferences(desc); + assert.deepEqual(packages, ["react-dom"]); + }); + + test("extracts scoped packages", () => { + const desc = "npm install @types/node @babel/core"; + const packages = extractPackageReferences(desc); + assert.ok(packages.includes("@types/node")); + assert.ok(packages.includes("@babel/core")); + }); + + test("extracts require statements from code blocks", () => { + const desc = ` +\`\`\`javascript +const fs = require('fs-extra'); +const path = require('path'); +\`\`\` + `; + const packages = extractPackageReferences(desc); + assert.ok(packages.includes("fs-extra")); + }); + + test("extracts import statements from code blocks", () => { + const desc = ` +\`\`\`typescript +import express from 'express'; +import { Router } from 'express'; +import type { Request } from 'express'; +\`\`\` + `; + const packages = extractPackageReferences(desc); + assert.ok(packages.includes("express")); + }); + + test("ignores relative imports", () => { + const desc = `import { foo } from './local-file';`; + const packages = extractPackageReferences(desc); + assert.deepEqual(packages, []); + }); + + test("ignores node builtins", () => { + const desc = `import fs from 'node:fs';`; + const packages = extractPackageReferences(desc); + assert.deepEqual(packages, []); + }); + + test("normalizes package subpaths", () => { + const desc = "npm install lodash/get"; + const packages = extractPackageReferences(desc); + assert.deepEqual(packages, ["lodash"]); + }); + + test("handles empty description", () => { + const packages = extractPackageReferences(""); + assert.deepEqual(packages, []); + }); + + test("ignores flags in npm install", () => { + const desc = "npm install -D typescript"; + const packages = extractPackageReferences(desc); + assert.ok(packages.includes("typescript")); + assert.ok(!packages.includes("-D")); + }); +}); + +// ─── File Path Consistency Tests ───────────────────────────────────────────── + +describe("checkFilePathConsistency", () => { + let tempDir: string; + + test("passes when files exist on disk", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync(join(tempDir, "existing.ts"), "// content"); + + try { + const tasks = [ + createTask({ + id: "T01", + files: ["existing.ts"], + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("passes when files are in prior expected_output", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["generated.ts"], + }), + createTask({ + id: "T02", + sequence: 1, + files: ["generated.ts"], + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("fails when inputs don't exist and not in prior outputs", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: ["nonexistent.ts"], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.equal(results.length, 1); + assert.equal(results[0].category, "file"); + assert.equal(results[0].passed, false); + assert.equal(results[0].blocking, true); + assert.ok(results[0].message.includes("nonexistent.ts")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("checks only inputs array, not files array", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + files: ["missing-file.ts"], + inputs: ["missing-input.ts"], + expected_output: [], + }), + ]; + + // Only inputs are checked — files ("files likely touched") are excluded + // because they may include files the task will create (#3626) + const results = checkFilePathConsistency(tasks, tempDir); + assert.equal(results.length, 1); + assert.ok(results.some((r) => r.target === "missing-input.ts")); + // missing-file.ts should NOT produce a failure + assert.ok(!results.some((r) => r.target === "missing-file.ts")); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("skips empty file strings", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + files: ["", " "], + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── Path Normalization Tests ──────────────────────────────────────────────── + +describe("normalizeFilePath", () => { + test("strips leading ./", () => { + assert.equal(normalizeFilePath("./src/a.ts"), "src/a.ts"); + assert.equal(normalizeFilePath("././foo.ts"), "foo.ts"); + }); + + test("normalizes backslashes to forward slashes", () => { + assert.equal(normalizeFilePath("src\\a.ts"), "src/a.ts"); + assert.equal(normalizeFilePath("src\\sub\\file.ts"), "src/sub/file.ts"); + }); + + test("removes duplicate slashes", () => { + assert.equal(normalizeFilePath("src//a.ts"), "src/a.ts"); + assert.equal(normalizeFilePath("src///sub//file.ts"), "src/sub/file.ts"); + }); + + test("handles empty string", () => { + assert.equal(normalizeFilePath(""), ""); + }); + + test("removes trailing slash", () => { + assert.equal(normalizeFilePath("src/"), "src"); + assert.equal(normalizeFilePath("src/sub/"), "src/sub"); + }); + + test("handles paths without any normalization needed", () => { + assert.equal(normalizeFilePath("src/a.ts"), "src/a.ts"); + assert.equal(normalizeFilePath("index.ts"), "index.ts"); + }); +}); + +describe("checkFilePathConsistency with path normalization", () => { + let tempDir: string; + + test("./path matches path in prior expected_output", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["src/generated.ts"], // Output without ./ + }), + createTask({ + id: "T02", + sequence: 1, + files: ["./src/generated.ts"], // Input with ./ + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, [], "Should pass because ./src/generated.ts matches src/generated.ts"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("path matches ./path in prior expected_output", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["./src/generated.ts"], // Output with ./ + }), + createTask({ + id: "T02", + sequence: 1, + files: ["src/generated.ts"], // Input without ./ + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, [], "Should pass because src/generated.ts matches ./src/generated.ts"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("paths with mixed separators match", () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["src/sub/file.ts"], + }), + createTask({ + id: "T02", + sequence: 1, + files: ["src\\sub\\file.ts"], // Backslash separators + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.deepEqual(results, [], "Should pass because backslash paths normalize to forward slash"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +describe("checkTaskOrdering with path normalization", () => { + test("./path in inputs triggers ordering check for path in expected_output", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["./generated.ts"], // Reads with ./ + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["generated.ts"], // Creates without ./ + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1, "Should detect ordering violation despite ./"); + assert.ok(results[0].message.includes("T01")); + assert.ok(results[0].message.includes("T02")); + }); + + test("path in inputs triggers ordering check for ./path in expected_output", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["generated.ts"], // Reads without ./ + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["./generated.ts"], // Creates with ./ + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1, "Should detect ordering violation despite ./ on creator"); + assert.ok(results[0].message.includes("sequence violation")); + }); + + test("no false positive when correctly ordered with mixed paths", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["./src/api.ts"], + }), + createTask({ + id: "T02", + sequence: 1, + files: ["src/api.ts"], // Same file, different notation + inputs: [], + expected_output: [], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.deepEqual(results, [], "Should pass - T02 reads file that T01 already created"); + }); +}); + +// ─── Task Ordering Tests ───────────────────────────────────────────────────── + +describe("checkTaskOrdering", () => { + test("passes when tasks are correctly ordered", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["api.ts"], + }), + createTask({ + id: "T02", + sequence: 1, + files: ["api.ts"], + inputs: [], + expected_output: [], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.deepEqual(results, []); + }); + + test("fails when task inputs reference file created by later task", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["generated.ts"], // Reads file that doesn't exist yet + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["generated.ts"], // Creates the file + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1); + assert.equal(results[0].category, "file"); + assert.equal(results[0].passed, false); + assert.equal(results[0].blocking, true); + assert.ok(results[0].message.includes("T01")); + assert.ok(results[0].message.includes("T02")); + assert.ok(results[0].message.includes("sequence violation")); + }); + + test("detects ordering violation in inputs array", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["schema.json"], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["schema.json"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1); + assert.ok(results[0].message.includes("schema.json")); + }); + + test("handles multiple ordering violations via inputs", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["a.ts", "b.ts"], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["a.ts"], + }), + createTask({ + id: "T03", + sequence: 2, + files: [], + inputs: [], + expected_output: ["b.ts"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 2); + }); + + test("passes when no dependencies between tasks", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: [], + expected_output: ["a.ts"], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["b.ts"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.deepEqual(results, []); + }); +}); + +// ─── Interface Contract Tests ──────────────────────────────────────────────── + +describe("checkInterfaceContracts", () => { + test("passes when function signatures match", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +function processData(input: string): boolean +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +function processData(input: string): boolean +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.deepEqual(results, []); + }); + + test("warns on parameter mismatch (non-blocking)", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +function saveUser(name: string): void +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +function saveUser(name: string, email: string): void +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.equal(results.length, 1); + assert.equal(results[0].category, "schema"); + assert.equal(results[0].target, "saveUser"); + assert.equal(results[0].passed, true); // Warning, not failure + assert.equal(results[0].blocking, false); + assert.ok(results[0].message.includes("different parameters")); + }); + + test("warns on return type mismatch (non-blocking)", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +function getData(): string +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +function getData(): number +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.equal(results.length, 1); + assert.ok(results[0].message.includes("different return types")); + }); + + test("handles export function syntax", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +export function validate(data: object): boolean +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +export function validate(data: string): boolean +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.equal(results.length, 1); + assert.ok(results[0].message.includes("validate")); + }); + + test("handles async function syntax", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +export async function fetchData(): Promise +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +export async function fetchData(): Promise +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.equal(results.length, 1); + }); + + test("handles const arrow function syntax", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +const handler = (req: Request): Response => +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +const handler = (req: Request, res: Response): void => +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + // Should have 2 results: parameter mismatch AND return type mismatch + assert.equal(results.length, 2); + assert.ok(results.some((r) => r.message.includes("handler"))); + assert.ok(results.some((r) => r.message.includes("parameters"))); + assert.ok(results.some((r) => r.message.includes("return types"))); + }); + + test("passes when no code blocks present", () => { + const tasks = [ + createTask({ + id: "T01", + description: "Just some text without code blocks", + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + assert.deepEqual(results, []); + }); + + test("handles multiple mismatches for same function", () => { + const tasks = [ + createTask({ + id: "T01", + description: ` +\`\`\`typescript +function process(a: string): string +\`\`\` + `, + }), + createTask({ + id: "T02", + description: ` +\`\`\`typescript +function process(a: number): number +\`\`\` + `, + }), + ]; + + const results = checkInterfaceContracts(tasks, "/tmp"); + // Should have both parameter and return type mismatches + assert.equal(results.length, 2); + }); +}); + +// ─── runPreExecutionChecks Integration Tests ───────────────────────────────── + +describe("runPreExecutionChecks", () => { + let tempDir: string; + + test("returns pass status when all checks pass", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync(join(tempDir, "existing.ts"), "// content"); + + try { + const tasks = [ + createTask({ + id: "T01", + files: ["existing.ts"], + inputs: [], + expected_output: ["output.ts"], + }), + createTask({ + id: "T02", + files: ["output.ts"], + inputs: [], + expected_output: [], + }), + ]; + + const result = await runPreExecutionChecks(tasks, tempDir); + assert.equal(result.status, "pass"); + assert.equal(result.checks.length, 0); + assert.ok(result.durationMs >= 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("returns fail status when blocking failure exists", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: ["nonexistent.ts"], + expected_output: [], + }), + ]; + + const result = await runPreExecutionChecks(tasks, tempDir); + assert.equal(result.status, "fail"); + assert.ok(result.checks.length > 0); + assert.ok(result.checks.some((c) => c.blocking === true)); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("returns warn status for non-blocking issues", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + // Create tasks with only interface contract warnings + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: [], + expected_output: [], + description: ` +\`\`\`typescript +function foo(a: string): void +\`\`\` + `, + }), + createTask({ + id: "T02", + files: [], + inputs: [], + expected_output: [], + description: ` +\`\`\`typescript +function foo(a: number): void +\`\`\` + `, + }), + ]; + + const result = await runPreExecutionChecks(tasks, tempDir); + assert.equal(result.status, "warn"); + assert.ok(result.checks.some((c) => c.blocking === false)); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("combines results from all check types", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: ["will-be-created.ts"], // Ordering violation + inputs: ["missing.ts"], // Missing file + expected_output: [], + description: ` +\`\`\`typescript +function check(a: string): void +\`\`\` + `, + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["will-be-created.ts"], + description: ` +\`\`\`typescript +function check(a: number): void +\`\`\` + `, + }), + ]; + + const result = await runPreExecutionChecks(tasks, tempDir); + assert.equal(result.status, "fail"); + + // Should have multiple types of issues + const categories = new Set(result.checks.map((c) => c.category)); + assert.ok(categories.has("file")); // From consistency and ordering + assert.ok(categories.has("schema")); // From interface check + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("reports duration in milliseconds", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [createTask({ id: "T01" })]; + const result = await runPreExecutionChecks(tasks, tempDir); + + assert.ok(typeof result.durationMs === "number"); + assert.ok(result.durationMs >= 0); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("handles empty task array", async () => { + tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const result = await runPreExecutionChecks([], tempDir); + assert.equal(result.status, "pass"); + assert.deepEqual(result.checks, []); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── Regression Tests: checkTaskOrdering false positive (#3677) ────────────── + +describe("checkTaskOrdering false positive regression (#3677)", () => { + test("task.files should not trigger ordering violation when file is in later expected_output", () => { + // T01 has files: ["component.tsx"] — this is a file the task will CREATE, + // not read. Including task.files in the ordering check causes a false positive. + // After fix (check only task.inputs), this should return 0 results. + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: ["component.tsx"], + inputs: [], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["component.tsx"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 0, "task.files should not be checked for ordering violations"); + }); + + test("task.files with multiple files should not trigger false positives", () => { + // T01 lists several files it will touch/create — none should trigger ordering + // violations just because T02 declares one of them as expected_output. + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: ["a.ts", "b.ts", "c.ts"], + inputs: [], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["b.ts"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 0, "Multiple task.files should not generate false positive violations"); + }); + + test("task.inputs SHOULD still trigger ordering violation", () => { + // task.inputs represents files a task genuinely needs to READ, so a sequence + // violation here is a real error and must still be detected. + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["config.json"], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["config.json"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1, "task.inputs ordering violation must still be detected"); + assert.equal(results[0].blocking, true); + assert.ok(results[0].message.includes("T01")); + assert.ok(results[0].message.includes("T02")); + assert.ok(results[0].message.includes("sequence violation")); + }); + + test("mixed files and inputs — only inputs trigger ordering violation", () => { + // T01 will create "created.ts" (files) and also needs to READ "needed.json" (inputs). + // T02 creates both. Only the inputs dependency is a real violation. + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: ["created.ts"], + inputs: ["needed.json"], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["created.ts", "needed.json"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1, "Only the inputs entry should produce a violation, not files"); + assert.ok(results[0].target === "needed.json", "Violation target should be the input, not the file"); + }); + + test("task.files with normalized paths should not false-positive", () => { + // Path normalization (./src/new-file.ts → src/new-file.ts) should not cause + // task.files to match against expected_output and produce a false positive. + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: ["./src/new-file.ts"], + inputs: [], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["src/new-file.ts"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 0, "Normalized task.files path should not trigger a false positive"); + }); + + test("annotated inputs still trigger ordering violations against later plain outputs", () => { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["`later.ts` — needed first"], + expected_output: [], + }), + createTask({ + id: "T02", + sequence: 1, + files: [], + inputs: [], + expected_output: ["later.ts"], + }), + ]; + + const results = checkTaskOrdering(tasks, "/tmp"); + assert.equal(results.length, 1, "Annotated inputs should still match later plain expected_output entries"); + assert.equal(results[0].target, "`later.ts` — needed first"); + assert.ok(results[0].message.includes("sequence violation")); + }); + + test("existing on-disk files do not trigger ordering violations just because a later task modifies them", () => { + const tempDir = join(tmpdir(), `pre-exec-ordering-existing-file-${Date.now()}`); + const existingFile = "frontend/src/__tests__/ProcurementPage29.test.tsx"; + + mkdirSync(join(tempDir, "frontend", "src", "__tests__"), { recursive: true }); + writeFileSync(join(tempDir, existingFile), "// existing file"); + + try { + const tasks = [ + createTask({ + id: "T01", + sequence: 0, + files: [], + inputs: ["`frontend/src/__tests__/ProcurementPage29.test.tsx` — contains matchMedia stub to remove"], + expected_output: [], + }), + createTask({ + id: "T03", + sequence: 2, + files: [], + inputs: [], + expected_output: ["frontend/src/__tests__/ProcurementPage29.test.tsx"], + }), + ]; + + const results = checkTaskOrdering(tasks, tempDir); + assert.equal(results.length, 0, "Pre-existing files should not be treated as created by later tasks"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── checkFilePathConsistency additional edge cases ────────────────────────── + +describe("checkFilePathConsistency additional edge cases", () => { + test("annotated inputs match files that already exist on disk", () => { + const tempDir = join(tmpdir(), `pre-exec-test-annotated-input-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + writeFileSync(join(tempDir, "existing.ts"), "// content"); + + try { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: ["`existing.ts` — file already on disk"], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.equal(results.length, 0, "Annotated inputs should resolve to the on-disk file path"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("plain inputs match prior annotated expected outputs", () => { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: [], + expected_output: ["`generated.ts` — created earlier"], + }), + createTask({ + id: "T02", + files: [], + inputs: ["generated.ts"], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, "/tmp"); + assert.equal(results.length, 0, "Prior annotated expected_output entries should satisfy later plain inputs"); + }); + + test("inputs referencing glob-like patterns should not crash", () => { + // A glob pattern in inputs is unusual but should be handled gracefully. + // The file won't exist on disk, so it should produce a blocking result. + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: ["src/**/*.ts"], + expected_output: [], + }), + ]; + + // Should not throw + let results: ReturnType; + assert.doesNotThrow(() => { + results = checkFilePathConsistency(tasks, "/tmp"); + }); + assert.equal(results!.length, 1, "Glob-pattern input that doesn't exist should produce a blocking result"); + assert.equal(results![0].blocking, true); + }); + + test("multi-word prose inputs are ignored by path consistency checks", () => { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: [ + "Current WIZARD_PRODUCTS enum", + "Existing test patterns in wizard.test.ts", + ], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, "/tmp"); + assert.equal(results.length, 0, "Prose planning hints should not be treated as missing file paths"); + }); + + test("empty inputs array produces no results", () => { + // A task with no inputs and only files should produce zero results from + // consistency check — files are not checked (#3626). + const tasks = [ + createTask({ + id: "T01", + files: ["anything.ts"], + inputs: [], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, "/tmp"); + assert.equal(results.length, 0, "Empty inputs should produce no consistency check results"); + }); + + test("inputs with absolute paths are checked correctly", () => { + // An absolute path in inputs should resolve to itself and pass when the file exists. + const tempDir = join(tmpdir(), `pre-exec-test-abs-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + const absFilePath = join(tempDir, "real-file.ts"); + writeFileSync(absFilePath, "// content"); + + try { + const tasks = [ + createTask({ + id: "T01", + files: [], + inputs: [absFilePath], + expected_output: [], + }), + ]; + + const results = checkFilePathConsistency(tasks, tempDir); + assert.equal(results.length, 0, "Absolute path to an existing file should pass consistency check"); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); + +// ─── PreExecutionResult Type Tests ─────────────────────────────────────────── + +describe("PreExecutionResult type", () => { + test("status is one of pass, warn, fail", async () => { + const tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [createTask({ id: "T01" })]; + const result = await runPreExecutionChecks(tasks, tempDir); + + assert.ok(["pass", "warn", "fail"].includes(result.status)); + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); + + test("checks array matches PreExecutionCheckJSON schema", async () => { + const tempDir = join(tmpdir(), `pre-exec-test-${Date.now()}`); + mkdirSync(tempDir, { recursive: true }); + + try { + const tasks = [ + createTask({ + id: "T01", + files: ["missing.ts"], + }), + ]; + + const result = await runPreExecutionChecks(tasks, tempDir); + + for (const check of result.checks) { + assert.ok(["package", "file", "tool", "endpoint", "schema"].includes(check.category)); + assert.ok(typeof check.target === "string"); + assert.ok(typeof check.passed === "boolean"); + assert.ok(typeof check.message === "string"); + if (check.blocking !== undefined) { + assert.ok(typeof check.blocking === "boolean"); + } + } + } finally { + rmSync(tempDir, { recursive: true, force: true }); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/pre-execution-fail-closed.test.ts b/src/resources/extensions/gsd/tests/pre-execution-fail-closed.test.ts new file mode 100644 index 000000000..f2fec376d --- /dev/null +++ b/src/resources/extensions/gsd/tests/pre-execution-fail-closed.test.ts @@ -0,0 +1,266 @@ +/** + * pre-execution-fail-closed.test.ts — Tests for pre-execution check fail-closed behavior. + * + * Verifies that when runPreExecutionChecks throws an exception, auto-mode pauses + * instead of silently continuing. This is the "fail-closed" security pattern. + */ + +import { describe, test, mock, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { tmpdir } from "node:os"; +import { mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; + +import { postUnitPostVerification, type PostUnitContext } from "../auto-post-unit.ts"; +import { AutoSession } from "../auto/session.ts"; +import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts"; +import { invalidateAllCaches } from "../cache.ts"; +import { _clearGsdRootCache } from "../paths.ts"; + +// ─── Test Fixtures ─────────────────────────────────────────────────────────── + +let tempDir: string; +let dbPath: string; +let originalCwd: string; + +function makeMockCtx() { + return { + ui: { + notify: mock.fn(), + setStatus: () => {}, + setWidget: () => {}, + setFooter: () => {}, + }, + model: { id: "test-model" }, + } as any; +} + +function makeMockPi() { + return { + sendMessage: mock.fn(), + setModel: mock.fn(async () => true), + } as any; +} + +function makeMockSession(basePath: string, currentUnit?: { type: string; id: string }): AutoSession { + const s = new AutoSession(); + s.basePath = basePath; + s.active = true; + if (currentUnit) { + s.currentUnit = { + type: currentUnit.type, + id: currentUnit.id, + startedAt: Date.now(), + }; + } + return s; +} + +function makePostUnitContext( + s: AutoSession, + ctx: ReturnType, + pi: ReturnType, + pauseAutoMock: ReturnType, +): PostUnitContext { + return { + s, + ctx, + pi, + buildSnapshotOpts: () => ({}), + lockBase: () => tempDir, + stopAuto: mock.fn(async () => {}) as unknown as PostUnitContext["stopAuto"], + pauseAuto: pauseAutoMock as unknown as PostUnitContext["pauseAuto"], + updateProgressWidget: () => {}, + }; +} + +function setupTestEnvironment(): void { + originalCwd = process.cwd(); + tempDir = join(tmpdir(), `pre-exec-fail-closed-test-${Date.now()}-${Math.random().toString(36).slice(2)}`); + mkdirSync(tempDir, { recursive: true }); + + const gsdDir = join(tempDir, ".gsd"); + mkdirSync(gsdDir, { recursive: true }); + + const milestonesDir = join(gsdDir, "milestones", "M001", "slices", "S01", "tasks"); + mkdirSync(milestonesDir, { recursive: true }); + + process.chdir(tempDir); + _clearGsdRootCache(); + + dbPath = join(gsdDir, "gsd.db"); + openDatabase(dbPath); +} + +function cleanupTestEnvironment(): void { + try { + process.chdir(originalCwd); + } catch { + // Ignore + } + try { + closeDatabase(); + } catch { + // Ignore + } + try { + rmSync(tempDir, { recursive: true, force: true }); + } catch { + // Ignore + } +} + +function writePreferences(prefs: Record): void { + const yamlLines = Object.entries(prefs).map(([k, v]) => `${k}: ${JSON.stringify(v)}`); + const prefsContent = `--- +${yamlLines.join("\n")} +--- + +# GSD Preferences +`; + writeFileSync(join(tempDir, ".gsd", "PREFERENCES.md"), prefsContent); + invalidateAllCaches(); + _clearGsdRootCache(); +} + +/** + * Create tasks in DB with a malformed task that will cause processing errors. + * We insert a task with null/undefined fields that might cause issues during processing. + */ +function createTasksWithInvalidData(): void { + insertMilestone({ id: "M001" }); + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + + // Create a normal task - the pre-execution checks should work fine with this + // The throw test is more about verifying the try/catch structure exists + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Normal task", + status: "pending", + planning: { + description: "A normal task", + estimate: "1h", + files: [], + verify: "npm test", + inputs: [], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 0, + }); +} + +// ─── Tests ─────────────────────────────────────────────────────────────────── + +describe("Pre-execution fail-closed behavior", () => { + beforeEach(() => { + setupTestEnvironment(); + }); + + afterEach(() => { + cleanupTestEnvironment(); + }); + + test("pre-execution checks complete successfully with valid tasks", async () => { + // This test verifies the happy path still works with the new try/catch + writePreferences({ + enhanced_verification: true, + enhanced_verification_pre: true, + }); + + createTasksWithInvalidData(); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + const result = await postUnitPostVerification(pctx); + + // With valid tasks, pre-exec should pass and not pause + assert.equal( + pauseAutoMock.mock.callCount(), + 0, + "pauseAuto should NOT be called when pre-execution checks pass" + ); + + assert.equal( + result, + "continue", + "postUnitPostVerification should return 'continue' when checks pass" + ); + }); + + test("error notification includes error message when pre-execution throws", async () => { + // This test verifies the error handling path by checking the notify call structure + // The actual throw would require mocking runPreExecutionChecks, but we can verify + // the error handling code path exists by checking the notification pattern + writePreferences({ + enhanced_verification: true, + enhanced_verification_pre: true, + }); + + // Create tasks that will cause a blocking failure (missing file) + insertMilestone({ id: "M001" }); + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Task with missing file", + status: "pending", + planning: { + description: "References missing file", + estimate: "1h", + files: [], + verify: "npm test", + inputs: ["nonexistent-file.ts"], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 0, + }); + + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + const result = await postUnitPostVerification(pctx); + + // With a blocking failure, pauseAuto should be called + assert.equal( + pauseAutoMock.mock.callCount(), + 1, + "pauseAuto should be called when pre-execution checks fail" + ); + + assert.equal( + result, + "stopped", + "postUnitPostVerification should return 'stopped' when checks fail" + ); + + // Verify error notification was shown + const notifyCalls = ctx.ui.notify.mock.calls; + const errorNotify = notifyCalls.find( + (call: { arguments: unknown[] }) => + call.arguments[1] === "error" + ); + assert.ok(errorNotify, "Should show error notification when pre-execution checks fail"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/pre-execution-pause-wiring.test.ts b/src/resources/extensions/gsd/tests/pre-execution-pause-wiring.test.ts new file mode 100644 index 000000000..7a540d86b --- /dev/null +++ b/src/resources/extensions/gsd/tests/pre-execution-pause-wiring.test.ts @@ -0,0 +1,457 @@ +/** + * pre-execution-pause-wiring.test.ts — Integration tests for pre-execution check → pauseAuto wiring. + * + * Tests that verify the control flow from pre-execution checks through to pauseAuto: + * 1. When runPreExecutionChecks returns status: "fail" with blocking: true, pauseAuto is called + * 2. When enhanced_verification_strict: true and status: "warn", pauseAuto is also called + * + * These are integration-level tests that exercise the actual postUnitPostVerification function + * with controlled mocks for external dependencies. + */ + +import { describe, test, mock, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { tmpdir } from "node:os"; +import { mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; + +import { postUnitPostVerification, type PostUnitContext } from "../auto-post-unit.ts"; +import { AutoSession } from "../auto/session.ts"; +import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts"; +import { invalidateAllCaches } from "../cache.ts"; +import { _clearGsdRootCache } from "../paths.ts"; + +// ─── Test Fixtures ─────────────────────────────────────────────────────────── + +let tempDir: string; +let dbPath: string; +let originalCwd: string; + +/** + * Create a minimal mock ExtensionContext. + */ +function makeMockCtx() { + return { + ui: { + notify: mock.fn(), + setStatus: () => {}, + setWidget: () => {}, + setFooter: () => {}, + }, + model: { id: "test-model" }, + } as any; +} + +/** + * Create a minimal mock ExtensionAPI. + */ +function makeMockPi() { + return { + sendMessage: mock.fn(), + setModel: mock.fn(async () => true), + } as any; +} + +/** + * Create a minimal AutoSession for testing. + */ +function makeMockSession(basePath: string, currentUnit?: { type: string; id: string }): AutoSession { + const s = new AutoSession(); + s.basePath = basePath; + s.active = true; + if (currentUnit) { + s.currentUnit = { + type: currentUnit.type, + id: currentUnit.id, + startedAt: Date.now(), + }; + } + return s; +} + +/** + * Create a PostUnitContext with a mockable pauseAuto. + */ +function makePostUnitContext( + s: AutoSession, + ctx: ReturnType, + pi: ReturnType, + pauseAutoMock: ReturnType, +): PostUnitContext { + return { + s, + ctx, + pi, + buildSnapshotOpts: () => ({}), + lockBase: () => tempDir, + stopAuto: mock.fn(async () => {}) as unknown as PostUnitContext["stopAuto"], + pauseAuto: pauseAutoMock as unknown as PostUnitContext["pauseAuto"], + updateProgressWidget: () => {}, + }; +} + +/** + * Set up a temp directory with GSD structure and DB. + * Also changes cwd so preferences loading finds the right PREFERENCES.md. + */ +function setupTestEnvironment(): void { + // Save original cwd so we can restore it + originalCwd = process.cwd(); + + tempDir = join(tmpdir(), `pre-exec-pause-test-${Date.now()}-${Math.random().toString(36).slice(2)}`); + mkdirSync(tempDir, { recursive: true }); + + // Create .gsd directory structure + const gsdDir = join(tempDir, ".gsd"); + mkdirSync(gsdDir, { recursive: true }); + + // Create milestones directory structure + const milestonesDir = join(gsdDir, "milestones", "M001", "slices", "S01", "tasks"); + mkdirSync(milestonesDir, { recursive: true }); + + // Change cwd so loadEffectiveGSDPreferences finds our PREFERENCES.md + process.chdir(tempDir); + + // Clear gsdRoot cache so it finds the new .gsd directory + _clearGsdRootCache(); + + // Initialize DB + dbPath = join(gsdDir, "gsd.db"); + openDatabase(dbPath); +} + +/** + * Clean up test environment. + */ +function cleanupTestEnvironment(): void { + // Restore original cwd before cleanup + try { + process.chdir(originalCwd); + } catch { + // Ignore if original cwd doesn't exist + } + + try { + closeDatabase(); + } catch { + // Ignore close errors + } + try { + rmSync(tempDir, { recursive: true, force: true }); + } catch { + // Ignore cleanup errors + } +} + +/** + * Create a PREFERENCES.md file with specified preferences. + * Uses YAML frontmatter format (---\nkey: value\n---). + * Also invalidates caches so the preferences are re-read. + */ +function writePreferences(prefs: Record): void { + const yamlLines = Object.entries(prefs).map(([k, v]) => `${k}: ${JSON.stringify(v)}`); + const prefsContent = `--- +${yamlLines.join("\n")} +--- + +# GSD Preferences +`; + writeFileSync(join(tempDir, ".gsd", "PREFERENCES.md"), prefsContent); + // Invalidate caches so the new preferences file is found + invalidateAllCaches(); + _clearGsdRootCache(); +} + +/** + * Create tasks in DB that will cause pre-execution checks to fail. + * A task that references a non-existent file will produce a blocking failure. + */ +function createFailingTasks(): void { + // Insert milestone first + insertMilestone({ id: "M001" }); + + // Insert slice + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + + // Create a task that references a file that doesn't exist + // This will cause checkFilePathConsistency to produce a blocking failure + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Task with missing file", + status: "pending", + planning: { + description: "This task references a non-existent file", + estimate: "1h", + files: [], + verify: "npm test", + inputs: ["nonexistent-file-that-does-not-exist.ts"], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 0, + }); +} + +/** + * Create tasks in DB that will produce only warnings (non-blocking issues). + * Interface contract mismatches produce warnings, not blocking failures. + */ +function createWarningOnlyTasks(): void { + // Insert milestone first + insertMilestone({ id: "M001" }); + + // Insert slice + insertSlice({ + id: "S01", + milestoneId: "M001", + title: "Test Slice", + risk: "low", + }); + + // Create tasks with interface contract mismatch (produces warn, not fail) + insertTask({ + id: "T01", + sliceId: "S01", + milestoneId: "M001", + title: "Task 1 with function signature", + status: "pending", + planning: { + description: ` +\`\`\`typescript +function processData(input: string): boolean +\`\`\` + `.trim(), + estimate: "1h", + files: [], + verify: "npm test", + inputs: [], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 0, + }); + + insertTask({ + id: "T02", + sliceId: "S01", + milestoneId: "M001", + title: "Task 2 with mismatched signature", + status: "pending", + planning: { + description: ` +\`\`\`typescript +function processData(input: number): string +\`\`\` + `.trim(), + estimate: "1h", + files: [], + verify: "npm test", + inputs: [], + expectedOutput: [], + observabilityImpact: "", + }, + sequence: 1, + }); +} + +// ─── Tests ─────────────────────────────────────────────────────────────────── + +describe("Pre-execution checks → pauseAuto wiring", () => { + beforeEach(() => { + setupTestEnvironment(); + }); + + afterEach(() => { + cleanupTestEnvironment(); + }); + + test("pauseAuto is called when pre-execution checks return status: fail with blocking: true", async () => { + // Set up tasks that will cause a blocking failure + createFailingTasks(); + + // Create mocks + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + // Call postUnitPostVerification + const result = await postUnitPostVerification(pctx); + + // Verify pauseAuto was called + assert.equal( + pauseAutoMock.mock.callCount(), + 1, + "pauseAuto should be called exactly once when pre-execution checks fail with blocking issues" + ); + + // Verify return value is "stopped" + assert.equal( + result, + "stopped", + "postUnitPostVerification should return 'stopped' when pre-execution checks fail" + ); + + // Verify UI was notified of the failure + const notifyCalls = ctx.ui.notify.mock.calls; + const errorNotify = notifyCalls.find( + (call: { arguments: unknown[] }) => + call.arguments[1] === "error" && + String(call.arguments[0]).includes("Pre-execution checks failed") + ); + assert.ok(errorNotify, "Should show error notification about pre-execution check failure"); + }); + + test("pauseAuto is called when enhanced_verification_strict: true and pre-execution returns warn", async () => { + // Write preferences with strict mode enabled + writePreferences({ + enhanced_verification: true, + enhanced_verification_pre: true, + enhanced_verification_strict: true, + }); + + // Set up tasks that will produce only warnings (interface contract mismatch) + createWarningOnlyTasks(); + + // Create mocks + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + // Call postUnitPostVerification + const result = await postUnitPostVerification(pctx); + + // Verify pauseAuto was called (strict mode promotes warnings to blocking) + assert.equal( + pauseAutoMock.mock.callCount(), + 1, + "pauseAuto should be called when strict mode is enabled and pre-execution returns warn" + ); + + // Verify return value is "stopped" + assert.equal( + result, + "stopped", + "postUnitPostVerification should return 'stopped' when strict mode treats warnings as blocking" + ); + + // Verify UI was notified of the warning + const notifyCalls = ctx.ui.notify.mock.calls; + const warnNotify = notifyCalls.find( + (call: { arguments: unknown[] }) => + call.arguments[1] === "warning" && + String(call.arguments[0]).includes("Pre-execution checks passed with warnings") + ); + assert.ok(warnNotify, "Should show warning notification about pre-execution check warnings"); + }); + + test("pauseAuto is NOT called when enhanced_verification_strict: false and pre-execution returns warn", async () => { + // Write preferences with strict mode disabled (default behavior) + writePreferences({ + enhanced_verification: true, + enhanced_verification_pre: true, + enhanced_verification_strict: false, + }); + + // Set up tasks that will produce only warnings + createWarningOnlyTasks(); + + // Create mocks + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + // Call postUnitPostVerification + const result = await postUnitPostVerification(pctx); + + // Verify pauseAuto was NOT called (warnings don't block in non-strict mode) + assert.equal( + pauseAutoMock.mock.callCount(), + 0, + "pauseAuto should NOT be called when strict mode is disabled and only warnings exist" + ); + + // Verify return value is "continue" (not "stopped") + assert.equal( + result, + "continue", + "postUnitPostVerification should return 'continue' when warnings don't block in non-strict mode" + ); + }); + + test("pre-execution checks are skipped when unit type is not plan-slice", async () => { + // Set up tasks that would fail if checked + createFailingTasks(); + + // Create mocks with execute-task unit (not plan-slice) + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + // Call postUnitPostVerification + const result = await postUnitPostVerification(pctx); + + // Verify pauseAuto was NOT called (pre-execution checks only run for plan-slice) + assert.equal( + pauseAutoMock.mock.callCount(), + 0, + "pauseAuto should NOT be called for non-plan-slice unit types" + ); + + // Verify return value is "continue" + assert.equal( + result, + "continue", + "postUnitPostVerification should return 'continue' for non-plan-slice unit types" + ); + }); + + test("pre-execution checks are skipped when enhanced_verification_pre: false", async () => { + // Write preferences with pre-execution checks disabled + writePreferences({ + enhanced_verification: true, + enhanced_verification_pre: false, + }); + + // Set up tasks that would fail if checked + createFailingTasks(); + + // Create mocks + const ctx = makeMockCtx(); + const pi = makeMockPi(); + const pauseAutoMock = mock.fn(async () => {}); + const s = makeMockSession(tempDir, { type: "plan-slice", id: "M001/S01" }); + const pctx = makePostUnitContext(s, ctx, pi, pauseAutoMock); + + // Call postUnitPostVerification + const result = await postUnitPostVerification(pctx); + + // Verify pauseAuto was NOT called (pre-execution checks disabled) + assert.equal( + pauseAutoMock.mock.callCount(), + 0, + "pauseAuto should NOT be called when enhanced_verification_pre is disabled" + ); + + // Verify return value is "continue" + assert.equal( + result, + "continue", + "postUnitPostVerification should return 'continue' when pre-execution checks are disabled" + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/preferences.test.ts b/src/resources/extensions/gsd/tests/preferences.test.ts index ff150440d..7e5f4177e 100644 --- a/src/resources/extensions/gsd/tests/preferences.test.ts +++ b/src/resources/extensions/gsd/tests/preferences.test.ts @@ -17,6 +17,8 @@ import { parsePreferencesMarkdown, _resetParseWarningFlag, } from "../preferences.ts"; +import { formatConfiguredModel, toPersistedModelId } from "../commands-prefs-wizard.ts"; +import { _resetLogs, peekLogs } from "../workflow-logger.ts"; import type { GSDPreferences, GSDModelConfigV2, GSDPhaseModelConfig } from "../preferences.ts"; // ── Git preferences ────────────────────────────────────────────────────────── @@ -346,6 +348,22 @@ test("handles model config with explicit provider field", () => { assert.equal(execution.provider, "bedrock"); }); +test("formatConfiguredModel renders provider-qualified object config", () => { + assert.equal( + formatConfiguredModel({ model: "claude-opus-4-6", provider: "bedrock" }), + "bedrock/claude-opus-4-6", + ); +}); + +test("toPersistedModelId prefixes provider chosen in prefs wizard", () => { + assert.equal(toPersistedModelId("openai", "gpt-5.4"), "openai/gpt-5.4"); + assert.equal( + toPersistedModelId("openai", "openai/gpt-5.4"), + "openai/gpt-5.4", + "already-qualified IDs should be preserved", + ); +}); + test("handles empty models config", () => { const prefs = parsePreferencesMarkdown("---\nversion: 1\n---\n"); assert.notEqual(prefs, null); @@ -412,6 +430,35 @@ test("unrecognized format warning is emitted at most once (#2373)", () => { } }); +test("parsePreferencesMarkdown parses heading+list format without frontmatter (#2036)", () => { + // A GSD agent recovery session wrote preferences in markdown heading+list + // format instead of YAML frontmatter. Since the heading+list fallback parser + // was added, this format is now handled gracefully. + const content = "## Git\n\n- isolation: none\n"; + const result = parsePreferencesMarkdown(content); + assert.notEqual(result, null, "heading+list content should be parsed"); + assert.deepStrictEqual(result!.git, { isolation: "none" }); +}); + +test("section parse warning is emitted at most once for heading+list YAML failures (#3759)", () => { + _resetParseWarningFlag(); + _resetLogs(); + + const content = `## Git +bad: [ +`; + + parsePreferencesMarkdown(content); + parsePreferencesMarkdown(content); + parsePreferencesMarkdown(content); + + const warnings = peekLogs().filter((entry) => entry.component === "guided" && entry.message.includes("preferences section parse failed")); + assert.equal(warnings.length, 1, `expected exactly 1 guided warning, got ${warnings.length}`); + + _resetParseWarningFlag(); + _resetLogs(); +}); + // ── Experimental preferences ───────────────────────────────────────────────── test("experimental.rtk: true is accepted and stored", () => { @@ -461,3 +508,65 @@ test("experimental.rtk defaults to off in new project preferences", () => { assert.notEqual(prefs, null); assert.equal(prefs!.experimental?.rtk, undefined); }); + +// ── Codebase Map Preferences ───────────────────────────────────────────────── + +test("codebase preferences validate and pass through correctly", () => { + const result = validatePreferences({ + codebase: { + exclude_patterns: ["docs/", "fixtures/"], + max_files: 1000, + collapse_threshold: 15, + }, + }); + assert.equal(result.errors.length, 0); + assert.deepEqual(result.preferences.codebase?.exclude_patterns, ["docs/", "fixtures/"]); + assert.equal(result.preferences.codebase?.max_files, 1000); + assert.equal(result.preferences.codebase?.collapse_threshold, 15); +}); + +test("codebase preferences reject invalid types", () => { + const result = validatePreferences({ + codebase: { + exclude_patterns: "not-an-array" as any, + max_files: -5, + collapse_threshold: 0, + }, + }); + assert.ok(result.errors.some(e => e.includes("exclude_patterns must be an array"))); + assert.ok(result.errors.some(e => e.includes("max_files must be a positive"))); + assert.ok(result.errors.some(e => e.includes("collapse_threshold must be a positive"))); +}); + +test("codebase preferences warn on unknown keys", () => { + const result = validatePreferences({ + codebase: { + exclude_patterns: ["docs/"], + unknown_key: true, + } as any, + }); + assert.equal(result.errors.length, 0); + assert.ok(result.warnings.some(w => w.includes('unknown codebase key "unknown_key"'))); + assert.deepEqual(result.preferences.codebase?.exclude_patterns, ["docs/"]); +}); + +test("codebase preferences parse from markdown frontmatter", () => { + const content = [ + "---", + "version: 1", + "codebase:", + " exclude_patterns:", + ' - "docs/"', + ' - ".cache/"', + " max_files: 800", + " collapse_threshold: 10", + "---", + ].join("\n"); + const prefs = parsePreferencesMarkdown(content); + assert.notEqual(prefs, null); + const result = validatePreferences(prefs!); + assert.equal(result.errors.length, 0); + assert.deepEqual(result.preferences.codebase?.exclude_patterns, ["docs/", ".cache/"]); + assert.equal(result.preferences.codebase?.max_files, 800); + assert.equal(result.preferences.codebase?.collapse_threshold, 10); +}); diff --git a/src/resources/extensions/gsd/tests/project-relocation-recovery.test.ts b/src/resources/extensions/gsd/tests/project-relocation-recovery.test.ts new file mode 100644 index 000000000..22b451c4a --- /dev/null +++ b/src/resources/extensions/gsd/tests/project-relocation-recovery.test.ts @@ -0,0 +1,297 @@ +/** + * Project Relocation Recovery Tests (#2750) + * + * Verifies that moving/renaming a GSD project directory does not cause + * silent data loss. When a repo has a remote URL, the identity hash + * should be based solely on the remote — making moves transparent. + * + * For local-only repos (no remote), ensureGsdSymlink should detect + * orphaned state directories with a matching .gsd-id marker and + * recover them automatically. + */ + +import { describe, test, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + rmSync, + writeFileSync, + readFileSync, + existsSync, + realpathSync, + mkdirSync, + readdirSync, + renameSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execFileSync } from "node:child_process"; + +import { + repoIdentity, + externalGsdRoot, + ensureGsdSymlink, + readRepoMeta, + externalProjectsRoot, +} from "../repo-identity.ts"; + +function git(args: string[], cwd: string): string { + return execFileSync("git", args, { + cwd, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); +} + +function normalizePath(p: string): string { + const resolved = + process.platform === "win32" ? realpathSync.native(p) : realpathSync(p); + return process.platform === "win32" ? resolved.toLowerCase() : resolved; +} + +function initRepo(dir: string, remote?: string): void { + git(["init", "-b", "main"], dir); + git(["config", "user.name", "Test"], dir); + git(["config", "user.email", "test@example.com"], dir); + if (remote) { + git(["remote", "add", "origin", remote], dir); + } + writeFileSync(join(dir, "README.md"), "# Test\n", "utf-8"); + git(["add", "README.md"], dir); + git(["commit", "-m", "init"], dir); +} + +describe("project-relocation-recovery (#2750)", () => { + let stateDir: string; + let savedStateDir: string | undefined; + + before(() => { + savedStateDir = process.env.GSD_STATE_DIR; + stateDir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-state-"))); + process.env.GSD_STATE_DIR = stateDir; + }); + + after(() => { + if (savedStateDir !== undefined) { + process.env.GSD_STATE_DIR = savedStateDir; + } else { + delete process.env.GSD_STATE_DIR; + } + rmSync(stateDir, { recursive: true, force: true }); + }); + + // ── Remote repos: identity should be path-independent ───────────────── + + test("repoIdentity is stable across moves for repos with a remote URL", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-a-"))); + initRepo(repoA, "https://github.com/example/myrepo.git"); + + const identityBefore = repoIdentity(repoA); + + // Move the repo to a new location + const repoB = join( + tmpdir(), + `gsd-reloc-b-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + renameSync(repoA, repoB); + + const identityAfter = repoIdentity(repoB); + + assert.strictEqual( + identityAfter, + identityBefore, + "identity hash must be stable when a remote-enabled repo is moved", + ); + + rmSync(repoB, { recursive: true, force: true }); + }); + + test("ensureGsdSymlink reuses the same external dir after repo move (remote repo)", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-reuse-a-"))); + initRepo(repoA, "https://github.com/example/reloc-reuse.git"); + + // Initialize GSD state with some planning data + const externalA = ensureGsdSymlink(repoA); + const milestonesPath = join(externalA, "milestones"); + mkdirSync(milestonesPath, { recursive: true }); + writeFileSync( + join(milestonesPath, "M001.md"), + "# Milestone 1\nImportant planning data\n", + "utf-8", + ); + + // Move the repo + const repoB = join( + tmpdir(), + `gsd-reloc-reuse-b-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + renameSync(repoA, repoB); + + // ensureGsdSymlink at the new location should find the same external dir + const externalB = ensureGsdSymlink(repoB); + + assert.strictEqual( + normalizePath(externalB), + normalizePath(externalA), + "external state dir must be the same after move", + ); + + // Planning data must survive the move + assert.ok( + existsSync(join(externalB, "milestones", "M001.md")), + "milestone data must survive project relocation", + ); + + const content = readFileSync( + join(externalB, "milestones", "M001.md"), + "utf-8", + ); + assert.ok( + content.includes("Important planning data"), + "milestone content must be preserved", + ); + + rmSync(repoB, { recursive: true, force: true }); + }); + + test("repo-meta.json gitRoot is updated after move (remote repo)", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-meta-a-"))); + initRepo(repoA, "https://github.com/example/reloc-meta.git"); + + const externalA = ensureGsdSymlink(repoA); + const metaBefore = readRepoMeta(externalA); + assert.ok(metaBefore !== null, "metadata should exist before move"); + + // Move the repo + const repoB = join( + tmpdir(), + `gsd-reloc-meta-b-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + renameSync(repoA, repoB); + + const externalB = ensureGsdSymlink(repoB); + const metaAfter = readRepoMeta(externalB); + assert.ok(metaAfter !== null, "metadata should exist after move"); + assert.strictEqual( + normalizePath(metaAfter!.gitRoot), + normalizePath(repoB), + "repo-meta.json gitRoot must be updated to new location", + ); + assert.strictEqual( + metaAfter!.createdAt, + metaBefore!.createdAt, + "createdAt must be preserved across moves", + ); + + rmSync(repoB, { recursive: true, force: true }); + }); + + // ── Local-only repos: .gsd-id marker provides recovery ──────────────── + + test("ensureGsdSymlink writes a .gsd-id marker in the project root", () => { + const repo = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-marker-"))); + initRepo(repo); + + ensureGsdSymlink(repo); + + const markerPath = join(repo, ".gsd-id"); + assert.ok(existsSync(markerPath), ".gsd-id marker must be written by ensureGsdSymlink"); + + const markerId = readFileSync(markerPath, "utf-8").trim(); + const computedId = repoIdentity(repo); + assert.strictEqual(markerId, computedId, ".gsd-id must contain the repo identity hash"); + + rmSync(repo, { recursive: true, force: true }); + }); + + test("local-only repo recovers state via .gsd-id marker after move", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-local-a-"))); + initRepo(repoA); + // No remote — identity includes gitRoot + + // Initialize GSD state + const externalA = ensureGsdSymlink(repoA); + mkdirSync(join(externalA, "milestones"), { recursive: true }); + writeFileSync( + join(externalA, "milestones", "M001.md"), + "# Local Milestone\n", + "utf-8", + ); + + const identityBefore = repoIdentity(repoA); + + // Move the repo + const repoB = join( + tmpdir(), + `gsd-reloc-local-b-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + renameSync(repoA, repoB); + + // The identity WILL change (no remote, gitRoot changed) + const identityAfter = repoIdentity(repoB); + assert.notStrictEqual( + identityAfter, + identityBefore, + "local-only repo identity changes with move (expected)", + ); + + // But ensureGsdSymlink should detect .gsd-id marker and recover + const externalB = ensureGsdSymlink(repoB); + assert.ok( + existsSync(join(externalB, "milestones", "M001.md")), + "local-only repo must recover state via .gsd-id marker after move", + ); + + rmSync(repoB, { recursive: true, force: true }); + }); + + // ── Edge cases ──────────────────────────────────────────────────────── + + test("identity remains different for repos with different remotes", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-diff-a-"))); + initRepo(repoA, "https://github.com/example/repo-alpha.git"); + + const repoB = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-diff-b-"))); + initRepo(repoB, "https://github.com/example/repo-beta.git"); + + assert.notStrictEqual( + repoIdentity(repoA), + repoIdentity(repoB), + "repos with different remotes must have different identities", + ); + + rmSync(repoA, { recursive: true, force: true }); + rmSync(repoB, { recursive: true, force: true }); + }); + + test("no orphaned state dir created when remote repo is moved", () => { + const repoA = realpathSync(mkdtempSync(join(tmpdir(), "gsd-reloc-orphan-a-"))); + initRepo(repoA, "https://github.com/example/no-orphan.git"); + + ensureGsdSymlink(repoA); + + // Count project dirs before move + const projectsDir = externalProjectsRoot(); + const countBefore = existsSync(projectsDir) + ? readdirSync(projectsDir).length + : 0; + + // Move the repo + const repoB = join( + tmpdir(), + `gsd-reloc-orphan-b-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + renameSync(repoA, repoB); + + ensureGsdSymlink(repoB); + + const countAfter = readdirSync(projectsDir).length; + assert.strictEqual( + countAfter, + countBefore, + "moving a remote repo must not create a new orphaned state directory", + ); + + rmSync(repoB, { recursive: true, force: true }); + }); +}); diff --git a/src/resources/extensions/gsd/tests/project-root-cwd-crash.test.ts b/src/resources/extensions/gsd/tests/project-root-cwd-crash.test.ts new file mode 100644 index 000000000..a75d3f13f --- /dev/null +++ b/src/resources/extensions/gsd/tests/project-root-cwd-crash.test.ts @@ -0,0 +1,53 @@ +/** + * Regression test for #3598 — projectRoot ENOENT crash on deleted cwd + * + * When the working directory is deleted (e.g. worktree teardown), process.cwd() + * throws ENOENT. The fix wraps process.cwd() in a try/catch and falls back to + * process.env.HOME. + * + * Also verifies #3589 — nativeBranchExists validation for prefs.main_branch + * in auto-worktree.ts to prevent merge failures with stale preferences. + * + * Structural verification test — reads source to confirm the guards exist. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const contextSource = readFileSync(join(__dirname, '..', 'commands', 'context.ts'), 'utf-8'); +const worktreeSource = readFileSync(join(__dirname, '..', 'auto-worktree.ts'), 'utf-8'); + +describe('projectRoot cwd crash guard (#3598)', () => { + test('projectRoot wraps process.cwd() in try/catch', () => { + assert.match(contextSource, /try\s*\{[\s\S]*?process\.cwd\(\)/, + 'process.cwd() should be inside a try block'); + }); + + test('catch block falls back to process.env.HOME', () => { + assert.match(contextSource, /catch[\s\S]*?process\.env\.HOME/, + 'catch block should fall back to process.env.HOME'); + }); + + test('projectRoot function is exported', () => { + assert.match(contextSource, /export function projectRoot\(\)/, + 'projectRoot should be an exported function'); + }); +}); + +describe('main_branch nativeBranchExists validation (#3589)', () => { + test('prefs.main_branch is validated with nativeBranchExists', () => { + assert.match(worktreeSource, /nativeBranchExists\(.*prefs\.main_branch\)/, + 'nativeBranchExists should validate prefs.main_branch'); + }); + + test('validatedPrefBranch falls back to undefined when branch missing', () => { + assert.match(worktreeSource, /validatedPrefBranch[\s\S]*?:\s*undefined/, + 'validatedPrefBranch should fall back to undefined'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/projection-no-plan-overwrite.test.ts b/src/resources/extensions/gsd/tests/projection-no-plan-overwrite.test.ts new file mode 100644 index 000000000..e87c3a4ca --- /dev/null +++ b/src/resources/extensions/gsd/tests/projection-no-plan-overwrite.test.ts @@ -0,0 +1,83 @@ +/** + * Regression test for #3651 — renderAllProjections must NOT call renderPlanProjection + * + * renderAllProjections previously called renderPlanProjection inside the slice + * loop, which overwrote the authoritative PLAN.md (produced by markdown-renderer.js + * in plan-slice/replan-slice tools) with a simplified projection that was missing + * key sections (Must-Haves, Verification, Files Likely Touched) and corrupted + * multi-line task descriptions. + * + * The fix removes the renderPlanProjection call from the renderAllProjections + * loop. The renderIfMissing recovery path is preserved. + */ + +import { describe, it } from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' + +// Use process.cwd() based resolution instead of import.meta.url +// to avoid tsx test runner path resolution issues +const src = readFileSync( + resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'workflow-projections.ts'), + 'utf-8', +) + +describe('renderAllProjections must not overwrite PLAN.md (#3651)', () => { + it('renderAllProjections function body does NOT invoke renderPlanProjection', () => { + // Extract the renderAllProjections function body + const fnStart = src.indexOf('export async function renderAllProjections(') + assert.ok(fnStart !== -1, 'renderAllProjections function must exist') + + // Find the for-loop over sliceRows inside renderAllProjections + const loopStart = src.indexOf('for (const slice of sliceRows)', fnStart) + assert.ok(loopStart !== -1, 'slice loop must exist in renderAllProjections') + + // Find the closing of renderAllProjections (next section marker) + const fnEnd = src.indexOf('\n// ─── ', fnStart + 1) + assert.ok(fnEnd !== -1, 'section delimiter after renderAllProjections must exist') + + const fnBody = src.slice(loopStart, fnEnd) + + // The fix: renderPlanProjection must NOT appear as a function call. + // Strip comment lines before checking (comments may mention the function name). + const codeOnly = fnBody + .split('\n') + .filter(line => !line.trim().startsWith('//')) + .join('\n') + + const hasPlanCall = /renderPlanProjection\s*\(/.test(codeOnly) + assert.equal( + hasPlanCall, + false, + 'renderPlanProjection must not be called inside the renderAllProjections slice loop — ' + + 'authoritative PLAN.md is rendered only by plan-slice/replan-slice tools', + ) + }) + + it('renderPlanProjection is still defined (available for regenerateIfMissing)', () => { + assert.ok( + src.includes('function renderPlanProjection('), + 'renderPlanProjection function definition must still exist for on-demand recovery', + ) + }) + + it('renderAllProjections still renders ROADMAP, SUMMARY, and STATE projections', () => { + const fnStart = src.indexOf('export async function renderAllProjections(') + const fnEnd = src.indexOf('\n// ─── ', fnStart + 1) + const fnBody = src.slice(fnStart, fnEnd) + + assert.ok( + fnBody.includes('renderRoadmapProjection('), + 'renderRoadmapProjection must still be called', + ) + assert.ok( + fnBody.includes('renderSummaryProjection('), + 'renderSummaryProjection must still be called', + ) + assert.ok( + fnBody.includes('renderStateProjection('), + 'renderStateProjection must still be called', + ) + }) +}) diff --git a/src/resources/extensions/gsd/tests/prompt-contracts.test.ts b/src/resources/extensions/gsd/tests/prompt-contracts.test.ts index 2c52a1da5..1b19d356c 100644 --- a/src/resources/extensions/gsd/tests/prompt-contracts.test.ts +++ b/src/resources/extensions/gsd/tests/prompt-contracts.test.ts @@ -35,6 +35,13 @@ test("workflow-start prompt defaults to autonomy instead of per-phase confirmati assert.doesNotMatch(prompt, /Gate between phases/i); }); +test("system prompt references CODEBASE.md and /gsd codebase", () => { + const prompt = readPrompt("system"); + assert.match(prompt, /CODEBASE\.md/); + assert.match(prompt, /\/gsd codebase \[generate\|update\|stats\]/); + assert.match(prompt, /auto-refreshes it when tracked files change/i); +}); + test("discuss prompt allows implementation questions when they materially matter", () => { const prompt = readPrompt("discuss"); assert.match(prompt, /Lead with experience, but ask implementation when it materially matters/i); @@ -51,6 +58,12 @@ test("guided discussion prompts avoid wrap-up prompts after every round", () => assert.doesNotMatch(slicePrompt, /I think I have a solid picture of this slice\. Ready to wrap up/i); }); +test("guided milestone discussion scopes depth verification to the milestone id", () => { + const prompt = readPrompt("guided-discuss-milestone"); + assert.match(prompt, /depth_verification_\{\{milestoneId\}\}/, "depth verification id should include the milestone id"); + assert.doesNotMatch(prompt, /depth_verification_confirm" — this enables the write-gate downstream/i, "legacy global depth gate wording should be gone"); +}); + test("guided-resume-task prompt preserves recovery state until work is superseded", () => { const prompt = readPrompt("guided-resume-task"); assert.match(prompt, /Do \*\*not\*\* delete the continue file immediately/i); @@ -65,11 +78,13 @@ test("execute-task prompt references gsd_complete_task tool", () => { assert.match(prompt, /gsd_complete_task/); }); -test("execute-task prompt instructs writing task summary before tool call", () => { +test("execute-task prompt uses gsd_complete_task as canonical summary write path", () => { const prompt = readPrompt("execute-task"); - // The prompt instructs writing the summary file AND calling the tool assert.match(prompt, /\{\{taskSummaryPath\}\}/); assert.match(prompt, /gsd_complete_task/); + assert.match(prompt, /DB-backed tool is the canonical write path/i); + assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{taskSummaryPath\}\}`?/i); + assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{taskSummaryPath\}\}`?\s*$/m); }); test("execute-task prompt does not instruct LLM to toggle checkboxes manually", () => { @@ -113,10 +128,14 @@ test("guided-complete-slice prompt references gsd_slice_complete tool", () => { test("complete-slice prompt instructs writing summary and UAT files before tool call", () => { const prompt = readPrompt("complete-slice"); - // The prompt instructs writing the summary AND UAT files, then calling the tool assert.match(prompt, /\{\{sliceSummaryPath\}\}/); assert.match(prompt, /\{\{sliceUatPath\}\}/); assert.match(prompt, /gsd_complete_slice/); + assert.match(prompt, /DB-backed tool is the canonical write path/i); + assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{sliceSummaryPath\}\}`?/i); + assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{sliceUatPath\}\}`?/i); + assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{sliceSummaryPath\}\}`?.*$/m); + assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{sliceUatPath\}\}`?.*$/m); }); test("complete-slice prompt preserves decisions and knowledge review steps", () => { @@ -125,6 +144,15 @@ test("complete-slice prompt preserves decisions and knowledge review steps", () assert.match(prompt, /KNOWLEDGE\.md/); }); +test("validate-milestone prompt uses gsd_validate_milestone as canonical validation write path", () => { + const prompt = readPrompt("validate-milestone"); + assert.match(prompt, /gsd_validate_milestone/); + assert.match(prompt, /\{\{validationPath\}\}/); + assert.match(prompt, /DB-backed tool is the canonical write path/i); + assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{validationPath\}\}`?/i); + assert.doesNotMatch(prompt, /Write to `?\{\{validationPath\}\}`?:/i); +}); + test("complete-slice prompt still contains template variables for context", () => { const prompt = readPrompt("complete-slice"); assert.match(prompt, /\{\{sliceSummaryPath\}\}/); @@ -181,11 +209,15 @@ test("reassess-roadmap prompt references gsd_reassess_roadmap tool", () => { assert.match(prompt, /gsd_reassess_roadmap/); }); -test("validate-milestone prompt persists verification classes through gsd_validate_milestone", () => { +test("validate-milestone prompt dispatches parallel reviewers", () => { const prompt = readPrompt("validate-milestone"); - assert.match(prompt, /verification classes section/i); - assert.match(prompt, /verificationClasses/); - assert.match(prompt, /gsd_validate_milestone/); + assert.match(prompt, /Reviewer A/); + assert.match(prompt, /Reviewer B/); + assert.match(prompt, /Reviewer C/); + assert.match(prompt, /Requirements Coverage/); + assert.match(prompt, /Cross-Slice Integration/); + assert.match(prompt, /Assessment & Acceptance Criteria/); + assert.match(prompt, /assessment evidence/i); }); // ─── Prompt migration: replan-slice → gsd_replan_slice ──────────────── @@ -202,6 +234,60 @@ test("reassess-roadmap prompt names gsd_reassess_roadmap as the tool to use", () assert.match(prompt, /gsd_reassess_roadmap/); }); +// ─── Bug #2933: prompt parameter names must match camelCase TypeBox schema ─── + +test("execute-task prompt uses camelCase parameter names matching TypeBox schema", () => { + const prompt = readPrompt("execute-task"); + // The gsd_complete_task tool schema uses camelCase: milestoneId, sliceId, taskId + // Prompts must NOT tell the LLM to use snake_case (milestone_id, slice_id, task_id) + const toolCallLine = prompt.split("\n").find((l) => /gsd_complete_task/.test(l) || /gsd_task_complete/.test(l)); + assert.ok(toolCallLine, "prompt must contain a gsd_complete_task or gsd_task_complete tool call line"); + assert.doesNotMatch(toolCallLine!, /milestone_id/, "must use milestoneId, not milestone_id"); + assert.doesNotMatch(toolCallLine!, /slice_id/, "must use sliceId, not slice_id"); + assert.doesNotMatch(toolCallLine!, /task_id/, "must use taskId, not task_id"); + // Positive: must mention the camelCase names + assert.match(toolCallLine!, /milestoneId/); + assert.match(toolCallLine!, /sliceId/); + assert.match(toolCallLine!, /taskId/); +}); + +test("complete-slice prompt uses camelCase parameter names matching TypeBox schema", () => { + const prompt = readPrompt("complete-slice"); + // The gsd_complete_slice tool schema uses camelCase: milestoneId, sliceId + const toolCallLine = prompt.split("\n").find((l) => /gsd_complete_slice/.test(l) || /gsd_slice_complete/.test(l)); + assert.ok(toolCallLine, "prompt must contain a gsd_complete_slice or gsd_slice_complete tool call line"); + assert.doesNotMatch(toolCallLine!, /milestone_id/, "must use milestoneId, not milestone_id"); + assert.doesNotMatch(toolCallLine!, /slice_id/, "must use sliceId, not slice_id"); + // Positive: must mention the camelCase names + assert.match(toolCallLine!, /milestoneId/); + assert.match(toolCallLine!, /sliceId/); +}); + +// ─── File system safety: complete-slice parity with complete-milestone (#2935) ── + +test("complete-slice prompt includes filesystem safety guard against EISDIR", () => { + const prompt = readPrompt("complete-slice"); + assert.match( + prompt, + /File system safety/i, + "complete-slice.md must include a 'File system safety' instruction to prevent EISDIR errors when the LLM passes a directory path to the read tool" + ); + assert.match( + prompt, + /never pass.*directory path.*directly to the.*read.*tool/i, + "complete-slice.md must warn against passing directory paths to the read tool" + ); +}); + +test("complete-milestone prompt still has its filesystem safety guard (regression)", () => { + const prompt = readPrompt("complete-milestone"); + assert.match( + prompt, + /File system safety/i, + "complete-milestone.md must keep its filesystem safety guard" + ); +}); + test("reactive-execute prompt references tool calls instead of checkbox updates", () => { const prompt = readPrompt("reactive-execute"); assert.doesNotMatch(prompt, /checkbox updates/); diff --git a/src/resources/extensions/gsd/tests/prompt-loader-replacement.test.ts b/src/resources/extensions/gsd/tests/prompt-loader-replacement.test.ts new file mode 100644 index 000000000..fcfd923ea --- /dev/null +++ b/src/resources/extensions/gsd/tests/prompt-loader-replacement.test.ts @@ -0,0 +1,178 @@ +/** + * Regression test for #2968: loadPrompt replaceAll expands $' in replacement strings. + * + * JavaScript's String.replaceAll interprets special replacement patterns ($', $`, $&) + * in the replacement string. When a template variable value contains $' (common in + * bash commands like `grep -q '^0$'`), the replacement injects the entire remainder + * of the template, causing exponential prompt expansion. + * + * The fix: use split/join instead of replaceAll, which has no special pattern + * interpretation. + */ +import test from "node:test"; +import assert from "node:assert/strict"; + +/** + * Replicate the OLD (buggy) substitution logic from prompt-loader.ts. + * Uses replaceAll which interprets $' $` $& in the replacement string. + */ +function substituteBuggy(template: string, vars: Record): string { + let content = template; + for (const [key, value] of Object.entries(vars)) { + content = content.replaceAll(`{{${key}}}`, value); + } + return content.trim(); +} + +/** + * Replicate the FIXED substitution logic from prompt-loader.ts. + * Uses split/join which treats the replacement as a literal string. + */ +function substituteFixed(template: string, vars: Record): string { + let content = template; + for (const [key, value] of Object.entries(vars)) { + content = content.split(`{{${key}}}`).join(value); + } + return content.trim(); +} + +test("replaceAll $' expansion bug — demonstrates the problem", () => { + // This test shows the bug: replaceAll interprets $' as "insert portion after match" + const template = "Hello {{name}}, welcome to {{place}}!"; + const valueWithDollarQuote = "grep -q '^0$'"; + + // Using replaceAll (buggy approach) + const buggyResult = template.replaceAll("{{name}}", valueWithDollarQuote); + + // $' in the replacement string causes replaceAll to append the text after the match + // So it should NOT equal the expected result + const expected = "Hello grep -q '^0$', welcome to {{place}}!"; + + // The buggy result will contain extra text injected by $' expansion + assert.notEqual(buggyResult, expected, + "replaceAll should have expanded $' — if this fails, the JS engine changed behavior"); + assert.ok(buggyResult.length > expected.length, + `Buggy result should be longer due to $' expansion. Got length ${buggyResult.length} vs expected ${expected.length}`); +}); + +test("split/join replacement — safe from $' expansion", () => { + const template = "Hello {{name}}, welcome to {{place}}!"; + const valueWithDollarQuote = "grep -q '^0$'"; + + // Using split/join (safe approach) + const safeResult = template.split("{{name}}").join(valueWithDollarQuote); + const expected = "Hello grep -q '^0$', welcome to {{place}}!"; + + assert.equal(safeResult, expected, + "split/join should preserve $' literally without expansion"); +}); + +test("fixed substitution preserves $' literally in replacement values", () => { + const template = + "Task: {{taskDescription}}\n\nVerification:\n```bash\n{{verificationCommand}}\n```\n\nEnd of prompt."; + + const vars: Record = { + taskDescription: "Run tests", + verificationCommand: "grep -c 'foo' file.txt | grep -q '^0$' && echo 'PASS' || echo 'FAIL'", + }; + + const buggyResult = substituteBuggy(template, vars); + const fixedResult = substituteFixed(template, vars); + + // The $' in the verification command value should appear literally in fixed result + const expectedSnippet = "grep -q '^0$'"; + assert.ok(fixedResult.includes(expectedSnippet), + `Fixed result should contain the literal string: ${expectedSnippet}`); + + // The fixed result should NOT have blown up in size + const maxReasonableLength = 300; + assert.ok(fixedResult.length < maxReasonableLength, + `Fixed result length ${fixedResult.length} exceeds reasonable maximum ${maxReasonableLength} — prompt explosion detected!`); + + // The buggy result DOES blow up — it's larger than the fixed result + assert.ok(buggyResult.length > fixedResult.length, + `Buggy result (${buggyResult.length}) should be larger than fixed (${fixedResult.length}) due to $' expansion`); +}); + +test("multiple $-pattern values do not cause cascading expansion", () => { + const template = "A: {{a}}\nB: {{b}}\nC: {{c}}\nEnd."; + const vars: Record = { + a: "value with $' single quote pattern", + b: "value with $` backtick pattern", + c: "value with $& ampersand pattern", + }; + + const buggyResult = substituteBuggy(template, vars); + const fixedResult = substituteFixed(template, vars); + + // The fixed version should preserve all values literally + assert.ok(fixedResult.includes("$'"), "Fixed result should contain literal $'"); + assert.ok(fixedResult.includes("$`"), "Fixed result should contain literal $`"); + assert.ok(fixedResult.includes("$&"), "Fixed result should contain literal $&"); + + // The fixed version should be a reasonable size + assert.ok(fixedResult.length < 200, + `Fixed result length ${fixedResult.length} should be under 200`); + + // The buggy version will be larger due to expansion + assert.ok(buggyResult.length > fixedResult.length, + `Buggy result (${buggyResult.length}) should be larger than fixed (${fixedResult.length}) due to $-pattern expansion`); +}); + +test("realistic execute-task prompt does not explode with $' in slice plan", () => { + // Simulate a realistic execute-task template with multiple variables + const template = [ + "# Execute Task", + "", + "## Context", + "Working directory: {{workingDirectory}}", + "Milestone: {{milestoneId}}", + "Slice: {{sliceId}} — {{sliceTitle}}", + "", + "## Slice Plan Excerpt", + "{{slicePlanExcerpt}}", + "", + "## Instructions", + "Complete the task described above.", + "{{skillActivation}}", + "", + "## Verification", + "Run the verification commands to confirm success.", + ].join("\n"); + + const slicePlanWithDollarPatterns = [ + "### Step 1: Validate output", + "```bash", + "grep -c 'error' output.log | grep -q '^0$' && echo 'PASS' || echo 'FAIL'", + "```", + "", + "### Step 2: Check format", + "```bash", + "diff <(cat expected.txt) <(cat actual.txt) | grep -q '^$' && echo 'MATCH'", + "```", + ].join("\n"); + + const vars: Record = { + workingDirectory: "/home/user/project", + milestoneId: "M001", + sliceId: "S01", + sliceTitle: "Build pipeline", + slicePlanExcerpt: slicePlanWithDollarPatterns, + skillActivation: "Load relevant skills.", + }; + + const fixedResult = substituteFixed(template, vars); + + // Should contain the literal $' patterns + assert.ok(fixedResult.includes("'^0$'"), "Should preserve '^0$' literally"); + assert.ok(fixedResult.includes("'^$'"), "Should preserve '^$' literally"); + + // Result should be reasonable size (template ~300 chars + values ~400 chars) + assert.ok(fixedResult.length < 1000, + `Result length ${fixedResult.length} exceeds 1000 — prompt explosion detected!`); + + // Compare with buggy version to confirm it WOULD have exploded + const buggyResult = substituteBuggy(template, vars); + assert.ok(buggyResult.length > fixedResult.length * 1.5, + `Buggy result (${buggyResult.length}) should be significantly larger than fixed (${fixedResult.length})`); +}); diff --git a/src/resources/extensions/gsd/tests/prompt-step-ordering.test.ts b/src/resources/extensions/gsd/tests/prompt-step-ordering.test.ts new file mode 100644 index 000000000..9be886664 --- /dev/null +++ b/src/resources/extensions/gsd/tests/prompt-step-ordering.test.ts @@ -0,0 +1,85 @@ +/** + * Regression test for #3696 — prompt step ordering and runtime fixes + * + * 1. complete-milestone.md: gsd_requirement_update (step 9) before + * gsd_complete_milestone (step 10) + * 2. complete-slice.md: uses gsd_requirement_update + * 3. register-extension.ts: _gsdEpipeGuard logs instead of re-throwing + * 4. register-hooks.ts: session_before_compact only checks isAutoActive + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const completeMilestoneMd = readFileSync( + join(__dirname, '..', 'prompts', 'complete-milestone.md'), + 'utf-8', +); +const completeSliceMd = readFileSync( + join(__dirname, '..', 'prompts', 'complete-slice.md'), + 'utf-8', +); +const registerExtSrc = readFileSync( + join(__dirname, '..', 'bootstrap', 'register-extension.ts'), + 'utf-8', +); +const registerHooksSrc = readFileSync( + join(__dirname, '..', 'bootstrap', 'register-hooks.ts'), + 'utf-8', +); + +describe('prompt step ordering (#3696)', () => { + test('gsd_requirement_update step appears before gsd_complete_milestone step', () => { + // Search for the numbered step definitions, not early "Do NOT call" warnings + const reqUpdateMatch = completeMilestoneMd.match(/^\d+\.\s.*gsd_requirement_update/m); + const completeMilestoneMatch = completeMilestoneMd.match(/^\d+\.\s.*gsd_complete_milestone/m); + assert.ok(reqUpdateMatch, 'gsd_requirement_update should appear in a numbered step'); + assert.ok(completeMilestoneMatch, 'gsd_complete_milestone should appear in a numbered step'); + const reqUpdateIdx = completeMilestoneMd.indexOf(reqUpdateMatch![0]); + const completeMilestoneIdx = completeMilestoneMd.indexOf(completeMilestoneMatch![0]); + assert.ok( + reqUpdateIdx < completeMilestoneIdx, + 'gsd_requirement_update step must come before gsd_complete_milestone step', + ); + }); + + test('complete-slice.md uses gsd_requirement_update', () => { + assert.match(completeSliceMd, /gsd_requirement_update/, + 'complete-slice.md should reference gsd_requirement_update'); + }); +}); + +describe('register-extension _gsdEpipeGuard (#3696)', () => { + test('_gsdEpipeGuard exists and does not re-throw', () => { + assert.match(registerExtSrc, /_gsdEpipeGuard/, + '_gsdEpipeGuard should be defined in register-extension.ts'); + // After the fix, the handler logs instead of throwing + assert.ok( + !registerExtSrc.includes('throw err'), + '_gsdEpipeGuard should NOT contain "throw err"', + ); + }); +}); + +describe('register-hooks session_before_compact (#3696)', () => { + test('session_before_compact only checks isAutoActive', () => { + // Extract the session_before_compact handler + const compactIdx = registerHooksSrc.indexOf('session_before_compact'); + assert.ok(compactIdx > -1, 'session_before_compact hook should exist'); + // The first check in the handler should be isAutoActive(), not isAutoPaused() + const afterCompact = registerHooksSrc.slice(compactIdx, compactIdx + 300); + assert.match(afterCompact, /isAutoActive\(\)/, + 'session_before_compact should check isAutoActive()'); + // Should NOT block compaction when paused + assert.ok( + !afterCompact.includes('isAutoPaused()'), + 'session_before_compact should not check isAutoPaused', + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/prompt-tool-names.test.ts b/src/resources/extensions/gsd/tests/prompt-tool-names.test.ts new file mode 100644 index 000000000..5636c9a82 --- /dev/null +++ b/src/resources/extensions/gsd/tests/prompt-tool-names.test.ts @@ -0,0 +1,69 @@ +// prompt-tool-names — Ensures prompt files reference correct tool names. +// +// The registered GSD tool is `search-the-web`, not `web_search`. +// `web_search` is an Anthropic API implementation detail that should +// never appear in GSD prompts or agent frontmatter. +// See: https://github.com/gsd-build/gsd-2/issues/2920 + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, readdirSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const promptsDir = join(__dirname, "..", "prompts"); +const agentsDir = join(__dirname, "..", "..", "..", "agents"); + +/** Collect all .md files in a directory (non-recursive). */ +function mdFiles(dir: string): string[] { + return readdirSync(dir) + .filter((f) => f.endsWith(".md")) + .map((f) => join(dir, f)); +} + +const WRONG_TOOL = "web_search"; +const CORRECT_TOOL = "search-the-web"; + +test("prompt files must not reference `web_search` — use `search-the-web` instead", () => { + const files = mdFiles(promptsDir); + assert.ok(files.length > 0, "Expected at least one prompt file"); + + const violations: string[] = []; + for (const file of files) { + const content = readFileSync(file, "utf-8"); + if (content.includes(WRONG_TOOL)) { + violations.push(file); + } + } + + assert.deepStrictEqual( + violations, + [], + `These prompt files reference "${WRONG_TOOL}" instead of "${CORRECT_TOOL}":\n${violations.join("\n")}`, + ); +}); + +test("agent frontmatter must not reference `web_search` — use `search-the-web` instead", () => { + const files = mdFiles(agentsDir); + assert.ok(files.length > 0, "Expected at least one agent file"); + + const violations: string[] = []; + for (const file of files) { + const content = readFileSync(file, "utf-8"); + // Check frontmatter tools line specifically + const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (frontmatterMatch) { + const frontmatter = frontmatterMatch[1]; + if (frontmatter.includes(WRONG_TOOL)) { + violations.push(file); + } + } + } + + assert.deepStrictEqual( + violations, + [], + `These agent files reference "${WRONG_TOOL}" in frontmatter instead of "${CORRECT_TOOL}":\n${violations.join("\n")}`, + ); +}); diff --git a/src/resources/extensions/gsd/tests/provider-errors.test.ts b/src/resources/extensions/gsd/tests/provider-errors.test.ts index 832cea206..34c4ed824 100644 --- a/src/resources/extensions/gsd/tests/provider-errors.test.ts +++ b/src/resources/extensions/gsd/tests/provider-errors.test.ts @@ -118,6 +118,44 @@ test("classifyError: rate limit takes precedence over auth keywords", () => { assert.ok(isTransient(result)); }); +// ── STREAM_RE: V8 JSON parse error variants (#2916) ──────────────────────── + +test("classifyError: 'Expected comma/brace after property value in JSON' is transient stream", () => { + const result = classifyError( + "Expected ',' or '}' after property value in JSON at position 2056 (line 1 column 2057)" + ); + assert.equal(result.kind, "stream"); + assert.ok(isTransient(result)); + assert.ok("retryAfterMs" in result && result.retryAfterMs === 15_000); +}); + +test("classifyError: 'Expected colon after property name in JSON' is transient stream", () => { + const result = classifyError( + "Expected ':' after property name in JSON at position 500 (line 1 column 501)" + ); + assert.equal(result.kind, "stream"); + assert.ok(isTransient(result)); + assert.ok("retryAfterMs" in result && result.retryAfterMs === 15_000); +}); + +test("classifyError: 'Expected property name or brace in JSON' is transient stream", () => { + const result = classifyError( + "Expected property name or '}' in JSON at position 42 (line 1 column 43)" + ); + assert.equal(result.kind, "stream"); + assert.ok(isTransient(result)); + assert.ok("retryAfterMs" in result && result.retryAfterMs === 15_000); +}); + +test("classifyError: 'Unterminated string in JSON' is transient stream", () => { + const result = classifyError( + "Unterminated string in JSON at position 100 (line 1 column 101)" + ); + assert.equal(result.kind, "stream"); + assert.ok(isTransient(result)); + assert.ok("retryAfterMs" in result && result.retryAfterMs === 15_000); +}); + // ── isTransientNetworkError ────────────────────────────────────────────────── test("isTransientNetworkError detects ECONNRESET", () => { @@ -420,13 +458,74 @@ test("openai-codex-responses.ts extracts nested error fields", () => { ); }); +// ── Fix 1: resetTransientRetryState resets module-level singleton ──────────── + +test("resetTransientRetryState is exported from agent-end-recovery.ts", () => { + const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8"); + assert.ok( + src.includes("export function resetTransientRetryState"), + "agent-end-recovery.ts must export resetTransientRetryState for provider-error-resume.ts", + ); +}); + +test("provider-error-resume.ts calls resetTransientRetryState before startAuto", () => { + const src = readFileSync(join(__dirname, "..", "bootstrap", "provider-error-resume.ts"), "utf-8"); + assert.ok( + src.includes("resetTransientRetryState"), + "provider-error-resume.ts must import and call resetTransientRetryState", + ); + // Ensure reset is called BEFORE startAuto — order matters + const resetIdx = src.indexOf("resetTransientRetryState()"); + const startIdx = src.indexOf("await deps.startAuto("); + assert.ok( + resetIdx !== -1 && startIdx !== -1 && resetIdx < startIdx, + "resetTransientRetryState() must be called before deps.startAuto()", + ); +}); + +// ── Fix 2: Session creation timeout treated as transient in phases.ts ─────── + +test("phases.ts handles timeout session-creation failures with pause instead of stopAuto", () => { + const src = readFileSync(join(__dirname, "..", "auto", "phases.ts"), "utf-8"); + + // The cancelled + isTransient + category=timeout path must pause, not hard-stop + assert.ok( + src.includes('category === "timeout"'), + "phases.ts must check category === 'timeout' on transient cancelled unitResults", + ); + // Must call pauseAuto (not stopAuto) for timeout cancellations + assert.ok( + /category === "timeout"[\s\S]{0,300}pauseAuto/.test(src), + "phases.ts must call pauseAuto for session-timeout failures (not stopAuto or continue)", + ); + // Must NOT use action: "continue" for transient cancellations (causes infinite loops) + assert.ok( + !/isTransient[\s\S]{0,500}action:\s*"continue"/.test(src), + "phases.ts must NOT return action:continue for cancelled units — use break+pause instead", + ); +}); + +// ── Fix 3: MAX_TRANSIENT_AUTO_RESUMES raised to 8 ─────────────────────────── + +test("MAX_TRANSIENT_AUTO_RESUMES is at least 8 for sustained overload resilience", () => { + const src = readFileSync(join(__dirname, "..", "bootstrap", "agent-end-recovery.ts"), "utf-8"); + const match = src.match(/MAX_TRANSIENT_AUTO_RESUMES\s*=\s*(\d+)/); + assert.ok(match, "MAX_TRANSIENT_AUTO_RESUMES must be defined"); + const value = Number(match![1]); + assert.ok( + value >= 8, + `MAX_TRANSIENT_AUTO_RESUMES must be >= 8 for sustained overload resilience, got ${value}`, + ); +}); + // ── agent-session retryable regex handles server_error (#1166) ────────────── test("agent-session retryable error regex matches server_error (underscore)", () => { // This regex is extracted from _isRetryableError in agent-session.ts. // It must match both "server error" (space) and "server_error" (underscore) // to properly classify Codex streaming errors as retryable. - const retryableRegex = /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|temporarily backed off/i; + // "temporarily backed off" intentionally excluded — see #3429 + const retryableRegex = /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|extra usage is required/i; // server_error (with underscore — Codex streaming error format) assert.ok(retryableRegex.test("Codex server_error: An error occurred")); diff --git a/src/resources/extensions/gsd/tests/query-tools-db-open.test.ts b/src/resources/extensions/gsd/tests/query-tools-db-open.test.ts new file mode 100644 index 000000000..6795cbe6e --- /dev/null +++ b/src/resources/extensions/gsd/tests/query-tools-db-open.test.ts @@ -0,0 +1,47 @@ +/** + * Regression test for #3672 — query-tools uses ensureDbOpen + * + * gsd_milestone_status previously called isDbAvailable() but never + * ensureDbOpen(), making it always fail outside auto-mode sessions. + * The fix imports ensureDbOpen from dynamic-tools and calls it before + * querying the DB. + * + * This structural test verifies the ensureDbOpen import and usage exist + * in query-tools.ts. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'bootstrap', 'query-tools.ts'), 'utf-8'); + +describe('query-tools ensureDbOpen usage (#3672)', () => { + test('imports ensureDbOpen from dynamic-tools', () => { + assert.match(source, /ensureDbOpen.*import\(|import.*ensureDbOpen/, + 'query-tools should import ensureDbOpen'); + }); + + test('calls ensureDbOpen() before DB queries', () => { + assert.match(source, /await ensureDbOpen\(\)/, + 'query-tools should call await ensureDbOpen()'); + }); + + test('no longer imports isDbAvailable in the execute path', () => { + // The old code imported isDbAvailable and checked it; the fix removed that + // The execute function should not destructure isDbAvailable from gsd-db + const executeBlock = source.slice(source.indexOf('async execute(')); + assert.doesNotMatch(executeBlock, /isDbAvailable,/, + 'execute path should not destructure isDbAvailable (replaced by ensureDbOpen)'); + }); + + test('uses dbAvailable result from ensureDbOpen', () => { + assert.match(source, /dbAvailable\s*=\s*await ensureDbOpen\(\)/, + 'should store ensureDbOpen result in dbAvailable'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/queue-execution-guard.test.ts b/src/resources/extensions/gsd/tests/queue-execution-guard.test.ts new file mode 100644 index 000000000..62662db8a --- /dev/null +++ b/src/resources/extensions/gsd/tests/queue-execution-guard.test.ts @@ -0,0 +1,166 @@ +/** + * Unit tests for the queue-mode execution guard (#2545). + * + * When queue phase is active, the agent should only create milestones — + * not execute work. This guard blocks write/edit/bash tool calls that + * target source code (non-.gsd/ paths) during queue mode. + * + * Exercises shouldBlockQueueExecution() — a pure function that checks: + * (a) queuePhaseActive false → pass (not in queue mode) + * (b) toolName is read-only (read, grep, find, ls) → pass + * (c) toolName is ask_user_questions → pass (discussion tool) + * (d) write/edit to .gsd/ path → pass (planning artifacts) + * (e) write/edit to source path → block + * (f) bash command → block (could execute work) + * (g) registered GSD tools (gsd_milestone_generate_id, gsd_summary_save) → pass + * (h) unknown custom tools → block + */ + +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { shouldBlockQueueExecution } from '../bootstrap/write-gate.ts'; + +// ─── Scenario 1: Not in queue mode — all tools pass ── + +test('queue-guard: allows all tools when queue phase is not active', () => { + const r1 = shouldBlockQueueExecution('write', '/src/index.ts', false); + assert.strictEqual(r1.block, false, 'write should pass outside queue mode'); + + const r2 = shouldBlockQueueExecution('bash', 'npm test', false); + assert.strictEqual(r2.block, false, 'bash should pass outside queue mode'); + + const r3 = shouldBlockQueueExecution('edit', '/src/index.ts', false); + assert.strictEqual(r3.block, false, 'edit should pass outside queue mode'); +}); + +// ─── Scenario 2: Read-only tools always pass in queue mode ── + +test('queue-guard: allows read-only tools during queue mode', () => { + for (const tool of ['read', 'grep', 'find', 'ls', 'glob']) { + const result = shouldBlockQueueExecution(tool, '/src/index.ts', true); + assert.strictEqual(result.block, false, `${tool} should pass in queue mode`); + } +}); + +// ─── Scenario 3: Discussion/planning tools pass in queue mode ── + +test('queue-guard: allows discussion and planning tools during queue mode', () => { + const r1 = shouldBlockQueueExecution('ask_user_questions', '', true); + assert.strictEqual(r1.block, false, 'ask_user_questions should pass'); + + const r2 = shouldBlockQueueExecution('gsd_milestone_generate_id', '', true); + assert.strictEqual(r2.block, false, 'gsd_milestone_generate_id should pass'); + + const r3 = shouldBlockQueueExecution('gsd_summary_save', '', true); + assert.strictEqual(r3.block, false, 'gsd_summary_save should pass'); +}); + +// ─── Scenario 4: Write to .gsd/ paths passes (planning artifacts) ── + +test('queue-guard: allows writes to .gsd/ paths during queue mode', () => { + const r1 = shouldBlockQueueExecution('write', '.gsd/milestones/M001/M001-CONTEXT.md', true); + assert.strictEqual(r1.block, false, 'write to .gsd/ should pass'); + + const r2 = shouldBlockQueueExecution('write', '/project/.gsd/PROJECT.md', true); + assert.strictEqual(r2.block, false, 'write to .gsd/PROJECT.md should pass'); + + const r3 = shouldBlockQueueExecution('edit', '.gsd/QUEUE.md', true); + assert.strictEqual(r3.block, false, 'edit to .gsd/QUEUE.md should pass'); + + const r4 = shouldBlockQueueExecution('write', '.gsd/REQUIREMENTS.md', true); + assert.strictEqual(r4.block, false, 'write to .gsd/REQUIREMENTS.md should pass'); + + const r5 = shouldBlockQueueExecution('write', '.gsd/DECISIONS.md', true); + assert.strictEqual(r5.block, false, 'write to .gsd/DECISIONS.md should pass'); +}); + +// ─── Scenario 5: Write/edit to source code paths blocked ── + +test('queue-guard: blocks writes to source code during queue mode', () => { + const r1 = shouldBlockQueueExecution('write', 'src/index.ts', true); + assert.strictEqual(r1.block, true, 'write to src/ should be blocked'); + assert.ok(r1.reason, 'should provide a reason'); + assert.ok(r1.reason!.includes('queue'), 'reason should mention queue'); + + const r2 = shouldBlockQueueExecution('write', '/project/src/components/App.tsx', true); + assert.strictEqual(r2.block, true, 'write to component file should be blocked'); + + const r3 = shouldBlockQueueExecution('edit', 'package.json', true); + assert.strictEqual(r3.block, true, 'edit to package.json should be blocked'); + + const r4 = shouldBlockQueueExecution('edit', '/project/lib/utils.ts', true); + assert.strictEqual(r4.block, true, 'edit to lib/ should be blocked'); +}); + +// ─── Scenario 6: Bash commands blocked during queue mode ── + +test('queue-guard: blocks bash commands during queue mode', () => { + const r1 = shouldBlockQueueExecution('bash', 'npm install some-package', true); + assert.strictEqual(r1.block, true, 'npm install should be blocked'); + assert.ok(r1.reason, 'should provide a reason'); + + const r2 = shouldBlockQueueExecution('bash', 'node src/index.ts', true); + assert.strictEqual(r2.block, true, 'running node should be blocked'); +}); + +// ─── Scenario 7: Bash read-only commands pass during queue mode ── + +test('queue-guard: allows read-only bash commands during queue mode', () => { + const r1 = shouldBlockQueueExecution('bash', 'cat src/index.ts', true); + assert.strictEqual(r1.block, false, 'cat should pass'); + + const r2 = shouldBlockQueueExecution('bash', 'ls -la src/', true); + assert.strictEqual(r2.block, false, 'ls should pass'); + + const r3 = shouldBlockQueueExecution('bash', 'git log --oneline -10', true); + assert.strictEqual(r3.block, false, 'git log should pass'); + + const r4 = shouldBlockQueueExecution('bash', 'find . -name "*.ts"', true); + assert.strictEqual(r4.block, false, 'find should pass'); + + const r5 = shouldBlockQueueExecution('bash', 'grep -rn "TODO" src/', true); + assert.strictEqual(r5.block, false, 'grep should pass'); + + const r6 = shouldBlockQueueExecution('bash', 'head -20 src/index.ts', true); + assert.strictEqual(r6.block, false, 'head should pass'); + + const r7 = shouldBlockQueueExecution('bash', 'wc -l src/index.ts', true); + assert.strictEqual(r7.block, false, 'wc should pass'); + + const r8 = shouldBlockQueueExecution('bash', 'git diff HEAD~1', true); + assert.strictEqual(r8.block, false, 'git diff should pass'); + + const r9 = shouldBlockQueueExecution('bash', 'gh issue view 42', true); + assert.strictEqual(r9.block, false, 'gh issue view should pass'); +}); + +// ─── Scenario 8: mkdir for .gsd/ milestone directories passes ── + +test('queue-guard: allows mkdir for .gsd/ milestone directories', () => { + const r1 = shouldBlockQueueExecution('bash', 'mkdir -p .gsd/milestones/M010/slices', true); + assert.strictEqual(r1.block, false, 'mkdir -p .gsd/ should pass'); +}); + +// ─── Scenario 9: Web search and library tools pass ── + +test('queue-guard: allows web search and library tools during queue mode', () => { + const r1 = shouldBlockQueueExecution('search-the-web', '', true); + assert.strictEqual(r1.block, false, 'search-the-web should pass'); + + const r2 = shouldBlockQueueExecution('resolve_library', '', true); + assert.strictEqual(r2.block, false, 'resolve_library should pass'); + + const r3 = shouldBlockQueueExecution('get_library_docs', '', true); + assert.strictEqual(r3.block, false, 'get_library_docs should pass'); + + const r4 = shouldBlockQueueExecution('fetch_page', '', true); + assert.strictEqual(r4.block, false, 'fetch_page should pass'); +}); + +// ─── Scenario 10: Unknown custom tools are blocked during queue mode ── + +test('queue-guard: blocks unknown custom tools during queue mode', () => { + const result = shouldBlockQueueExecution('custom_codegen_tool', '', true); + assert.strictEqual(result.block, true, 'unknown custom tools should be blocked'); + assert.ok(result.reason, 'should explain the queue restriction'); +}); diff --git a/src/resources/extensions/gsd/tests/queued-discuss-fast-path.test.ts b/src/resources/extensions/gsd/tests/queued-discuss-fast-path.test.ts new file mode 100644 index 000000000..75b249485 --- /dev/null +++ b/src/resources/extensions/gsd/tests/queued-discuss-fast-path.test.ts @@ -0,0 +1,107 @@ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +function guidedFlowSrc(): string { + return readFileSync(join(__dirname, "..", "guided-flow.ts"), "utf-8"); +} + +function promptSrc(): string { + return readFileSync(join(__dirname, "..", "prompts", "guided-discuss-milestone.md"), "utf-8"); +} + +describe("queued-discuss-fast-path", () => { + test("1. guided-discuss-milestone.md contains {{fastPathInstruction}}", () => { + const prompt = promptSrc(); + assert.ok( + prompt.includes("{{fastPathInstruction}}"), + "guided-discuss-milestone.md must contain {{fastPathInstruction}} template variable", + ); + }); + + test("2. dispatchDiscussForMilestone computes fastPathInstruction and passes it to loadPrompt", () => { + const source = guidedFlowSrc(); + const fnStart = source.indexOf("async function dispatchDiscussForMilestone("); + assert.ok(fnStart > 0, "dispatchDiscussForMilestone must exist"); + const fnEnd = source.indexOf("\nasync function ", fnStart + 1); + const fnBody = fnEnd > 0 ? source.slice(fnStart, fnEnd) : source.slice(fnStart, fnStart + 2000); + assert.ok( + fnBody.includes("fastPathInstruction"), + "dispatchDiscussForMilestone must compute fastPathInstruction", + ); + assert.ok( + fnBody.includes("loadPrompt("), + "dispatchDiscussForMilestone must call loadPrompt", + ); + const loadPromptIdx = fnBody.indexOf("loadPrompt("); + const fastPathIdx = fnBody.indexOf("fastPathInstruction", loadPromptIdx); + assert.ok( + fastPathIdx > loadPromptIdx, + "fastPathInstruction must be passed to loadPrompt in dispatchDiscussForMilestone", + ); + }); + + test("3. fast path instruction mentions scouting and conflict checking", () => { + const source = guidedFlowSrc(); + assert.ok( + source.includes("scouting pass"), + "fast path instruction must mention scouting pass", + ); + assert.ok( + source.includes("conflicts with existing work"), + "fast path instruction must mention conflict checking", + ); + }); + + test("4. showDiscussQueuedMilestone shows a mode picker when no draft", () => { + const source = guidedFlowSrc(); + const fnStart = source.indexOf("async function showDiscussQueuedMilestone("); + assert.ok(fnStart > 0, "showDiscussQueuedMilestone must exist"); + const fnEnd = source.indexOf("\nasync function ", fnStart + 1); + const fnBody = fnEnd > 0 ? source.slice(fnStart, fnEnd) : source.slice(fnStart, fnStart + 3000); + assert.ok( + fnBody.includes("hasDraft"), + "showDiscussQueuedMilestone must check hasDraft", + ); + assert.ok( + fnBody.includes('"full"') || fnBody.includes("\"full\""), + "showDiscussQueuedMilestone must offer a 'full' discussion mode", + ); + assert.ok( + fnBody.includes('"fast"') || fnBody.includes("\"fast\""), + "showDiscussQueuedMilestone must offer a 'fast' path mode", + ); + }); + + test("5. showDiscussQueuedMilestone fast-paths automatically when draft exists", () => { + const source = guidedFlowSrc(); + const fnStart = source.indexOf("async function showDiscussQueuedMilestone("); + assert.ok(fnStart > 0, "showDiscussQueuedMilestone must exist"); + const fnEnd = source.indexOf("\nasync function ", fnStart + 1); + const fnBody = fnEnd > 0 ? source.slice(fnStart, fnEnd) : source.slice(fnStart, fnStart + 3000); + assert.ok( + fnBody.includes("let fastPath = hasDraft"), + "showDiscussQueuedMilestone must set fastPath = hasDraft so draft presence auto-enables fast path", + ); + assert.ok( + fnBody.includes("if (!hasDraft)"), + "showDiscussQueuedMilestone must skip the mode picker when hasDraft is true", + ); + }); + + test("6. dispatchDiscussForMilestone accepts opts with fastPath parameter", () => { + const source = guidedFlowSrc(); + const fnStart = source.indexOf("async function dispatchDiscussForMilestone("); + assert.ok(fnStart > 0, "dispatchDiscussForMilestone must exist"); + const signatureEnd = source.indexOf("): Promise", fnStart); + const signature = source.slice(fnStart, signatureEnd + 16); + assert.ok( + signature.includes("opts") && signature.includes("fastPath"), + "dispatchDiscussForMilestone must accept opts: { fastPath?: boolean } parameter", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/quick-turn-end-cleanup.test.ts b/src/resources/extensions/gsd/tests/quick-turn-end-cleanup.test.ts new file mode 100644 index 000000000..5051a8567 --- /dev/null +++ b/src/resources/extensions/gsd/tests/quick-turn-end-cleanup.test.ts @@ -0,0 +1,90 @@ +/** + * Tests that cleanupQuickBranch is called on turn_end to squash-merge the + * quick branch back to the original branch after the agent completes. + * + * Relates to #2668: /gsd quick does not squash-merge branch back after agent + * completes task. cleanupQuickBranch() exists but is never invoked. + * + * The fix registers a turn_end hook in register-hooks.ts that calls + * cleanupQuickBranch() after each turn, which is a no-op when no quick-task + * state is pending. + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +// ─── Structural test: verify turn_end hook exists in register-hooks.ts ────── + +describe("quick task turn_end cleanup (#2668)", () => { + const hooksSource = readFileSync( + join(import.meta.dirname, "..", "bootstrap", "register-hooks.ts"), + "utf-8", + ); + + it("register-hooks.ts imports cleanupQuickBranch from quick.ts", () => { + assert.ok( + hooksSource.includes("cleanupQuickBranch"), + "register-hooks.ts must reference cleanupQuickBranch", + ); + + // Verify it's imported (not just mentioned in a comment) + const importMatch = hooksSource.match( + /import\s*\{[^}]*cleanupQuickBranch[^}]*\}\s*from\s*["'][^"']*quick/, + ); + assert.ok( + importMatch, + "cleanupQuickBranch must be imported from quick module", + ); + }); + + it("registers a turn_end handler that calls cleanupQuickBranch", () => { + // Find the turn_end registration + const turnEndMatch = hooksSource.match( + /pi\.on\(\s*["']turn_end["']/, + ); + assert.ok( + turnEndMatch, + "register-hooks.ts must register a turn_end handler", + ); + + // Extract the turn_end handler body — find everything from the pi.on("turn_end" + // to the matching closing }); + const turnEndIdx = hooksSource.indexOf(turnEndMatch[0]); + assert.ok(turnEndIdx !== -1); + + // Get the rest of the source from that point + const rest = hooksSource.slice(turnEndIdx); + + // The handler must call cleanupQuickBranch + // Look for cleanupQuickBranch within the first handler body (up to first `});`) + const handlerEnd = rest.indexOf("});"); + assert.ok(handlerEnd !== -1, "turn_end handler has a closing });"); + + const handlerBody = rest.slice(0, handlerEnd); + assert.ok( + handlerBody.includes("cleanupQuickBranch"), + "turn_end handler must call cleanupQuickBranch", + ); + }); + + it("turn_end handler calls cleanupQuickBranch without arguments (uses cwd default)", () => { + // cleanupQuickBranch(basePath = process.cwd()) — calling without args is correct + // because the handler runs in the same process where handleQuick set up cwd + const turnEndIdx = hooksSource.indexOf('pi.on("turn_end"') !== -1 + ? hooksSource.indexOf('pi.on("turn_end"') + : hooksSource.indexOf("pi.on('turn_end'"); + assert.ok(turnEndIdx !== -1); + + const rest = hooksSource.slice(turnEndIdx); + const handlerEnd = rest.indexOf("});"); + const handlerBody = rest.slice(0, handlerEnd); + + // Should call cleanupQuickBranch() — either bare or with no-arg form + assert.ok( + handlerBody.includes("cleanupQuickBranch("), + "turn_end handler invokes cleanupQuickBranch()", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/reactive-graph.test.ts b/src/resources/extensions/gsd/tests/reactive-graph.test.ts index 4cf077056..6232dc6b0 100644 --- a/src/resources/extensions/gsd/tests/reactive-graph.test.ts +++ b/src/resources/extensions/gsd/tests/reactive-graph.test.ts @@ -5,6 +5,7 @@ import { getReadyTasks, chooseNonConflictingSubset, isGraphAmbiguous, + getMissingAnnotationTasks, detectDeadlock, graphMetrics, } from "../reactive-graph.ts"; @@ -100,6 +101,25 @@ test("parseTaskPlanIO handles multiple backtick tokens on one line", () => { assert.deepEqual(io.outputFiles, ["src/c.ts"]); }); +test("parseTaskPlanIO strips inline descriptions from backtick-wrapped file references", () => { + const content = `# T01: Described Paths + +## Inputs + +- \`src/config.ts — existing configuration\` +- \`src/flags.ts - feature flags\` + +## Expected Output + +- \`definitions/ac-audit.md — current state of AC CRM\` +- \`docs/runbook.md - update deployment notes\` +`; + + const io = parseTaskPlanIO(content); + assert.deepEqual(io.inputFiles, ["src/config.ts", "src/flags.ts"]); + assert.deepEqual(io.outputFiles, ["definitions/ac-audit.md", "docs/runbook.md"]); +}); + // ─── deriveTaskGraph ────────────────────────────────────────────────────── test("deriveTaskGraph: linear chain T01→T02→T03", () => { @@ -297,3 +317,47 @@ test("graphMetrics computes correct values", () => { assert.equal(metrics.readySetSize, 2); // T02 (T01 done) and T03 (no deps) assert.equal(metrics.ambiguous, false); }); + +// ─── getMissingAnnotationTasks ───────────────────────────────────────────── + +test("getMissingAnnotationTasks: returns empty array when all tasks have annotations", () => { + const graph: DerivedTaskNode[] = [ + { id: "T01", title: "A", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: [] }, + { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/c.ts"], done: false, dependsOn: [] }, + ]; + assert.deepEqual(getMissingAnnotationTasks(graph), []); +}); + +test("getMissingAnnotationTasks: returns tasks with missing annotations", () => { + const graph: DerivedTaskNode[] = [ + { id: "T01", title: "A", inputFiles: [], outputFiles: [], done: false, dependsOn: [] }, + { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: [] }, + { id: "T03", title: "C", inputFiles: [], outputFiles: [], done: false, dependsOn: [] }, + ]; + assert.deepEqual(getMissingAnnotationTasks(graph), [ + { id: "T01", title: "A" }, + { id: "T03", title: "C" }, + ]); +}); + +test("getMissingAnnotationTasks: skips done tasks", () => { + const graph: DerivedTaskNode[] = [ + { id: "T01", title: "A", inputFiles: [], outputFiles: [], done: true, dependsOn: [] }, + { id: "T02", title: "B", inputFiles: [], outputFiles: [], done: false, dependsOn: [] }, + ]; + assert.deepEqual(getMissingAnnotationTasks(graph), [ + { id: "T02", title: "B" }, + ]); +}); + +test("getMissingAnnotationTasks: returns only tasks missing BOTH inputFiles and outputFiles", () => { + const graph: DerivedTaskNode[] = [ + { id: "T01", title: "InputOnly", inputFiles: ["src/a.ts"], outputFiles: [], done: false, dependsOn: [] }, + { id: "T02", title: "OutputOnly", inputFiles: [], outputFiles: ["src/b.ts"], done: false, dependsOn: [] }, + { id: "T03", title: "Neither", inputFiles: [], outputFiles: [], done: false, dependsOn: [] }, + { id: "T04", title: "Both", inputFiles: ["src/c.ts"], outputFiles: ["src/d.ts"], done: false, dependsOn: [] }, + ]; + assert.deepEqual(getMissingAnnotationTasks(graph), [ + { id: "T03", title: "Neither" }, + ]); +}); diff --git a/src/resources/extensions/gsd/tests/reassess-handler.test.ts b/src/resources/extensions/gsd/tests/reassess-handler.test.ts index 38908433f..2f8e2aa36 100644 --- a/src/resources/extensions/gsd/tests/reassess-handler.test.ts +++ b/src/resources/extensions/gsd/tests/reassess-handler.test.ts @@ -9,6 +9,7 @@ import { closeDatabase, insertMilestone, insertSlice, + insertAssessment, getSlice, getMilestoneSlices, getAssessment, @@ -323,3 +324,119 @@ test('handleReassessRoadmap returns structured error payloads with actionable me cleanup(base); } }); + +// ─── Bug #2957: Stale VALIDATION survives roadmap remediation ──────────── + +test('handleReassessRoadmap invalidates stale milestone-validation when roadmap changes (#2957)', async () => { + const base = makeTmpBase(); + openDatabase(join(base, '.gsd', 'gsd.db')); + + try { + // Seed: M001 with S01-S04 all complete, plus a stale VALIDATION with needs-remediation + insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' }); + insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Slice One', status: 'complete', demo: 'Demo' }); + insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Slice Two', status: 'complete', demo: 'Demo' }); + insertSlice({ id: 'S03', milestoneId: 'M001', title: 'Slice Three', status: 'complete', demo: 'Demo' }); + insertSlice({ id: 'S04', milestoneId: 'M001', title: 'Slice Four', status: 'complete', demo: 'Demo' }); + + // Insert milestone-validation assessment with needs-remediation verdict (stale) + const validationPath = join('.gsd', 'milestones', 'M001', 'M001-VALIDATION.md'); + insertAssessment({ + path: validationPath, + milestoneId: 'M001', + sliceId: null, + taskId: null, + status: 'needs-remediation', + scope: 'milestone-validation', + fullContent: '---\nverdict: needs-remediation\nremediation_round: 0\n---\n\n# Validation\nNeeds remediation.', + }); + + // Verify the validation row exists before reassess + const adapter = _getAdapter()!; + const before = adapter.prepare( + `SELECT * FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`, + ).get() as Record | undefined; + assert.ok(before, 'milestone-validation row should exist before reassess'); + + // Now reassess the roadmap: add remediation slice S05 + // This simulates the scenario from #2957 where validation produced needs-remediation + // and then roadmap was reassessed to add a remediation slice + const result = await handleReassessRoadmap({ + milestoneId: 'M001', + completedSliceId: 'S04', + verdict: 'on-track', + assessment: 'S04 completed. Adding remediation slice S05.', + sliceChanges: { + modified: [], + added: [ + { + sliceId: 'S05', + title: 'Remediation Slice', + risk: 'low', + depends: ['S04'], + demo: 'Fix the issues found during validation.', + }, + ], + removed: [], + }, + }, base); + + assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`); + + // The stale milestone-validation row must be deleted after roadmap changes + const after = adapter.prepare( + `SELECT * FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`, + ).get() as Record | undefined; + assert.equal(after, undefined, 'milestone-validation row should be deleted after roadmap changes — stale validation must not survive remediation (#2957)'); + } finally { + cleanup(base); + } +}); + +test('handleReassessRoadmap does NOT invalidate validation when no roadmap structural changes (#2957)', async () => { + const base = makeTmpBase(); + openDatabase(join(base, '.gsd', 'gsd.db')); + + try { + // Seed: M001 with slices, plus a validation with pass verdict + insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' }); + insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Slice One', status: 'complete', demo: 'Demo' }); + insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Slice Two', status: 'pending', demo: 'Demo' }); + + // Insert milestone-validation assessment with pass verdict + const validationPath = join('.gsd', 'milestones', 'M001', 'M001-VALIDATION.md'); + insertAssessment({ + path: validationPath, + milestoneId: 'M001', + sliceId: null, + taskId: null, + status: 'pass', + scope: 'milestone-validation', + fullContent: '---\nverdict: pass\nremediation_round: 0\n---\n\n# Validation\nAll good.', + }); + + // Reassess with no structural changes (empty added/modified/removed) + const result = await handleReassessRoadmap({ + milestoneId: 'M001', + completedSliceId: 'S01', + verdict: 'confirmed', + assessment: 'S01 completed. No changes needed.', + sliceChanges: { + modified: [], + added: [], + removed: [], + }, + }, base); + + assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`); + + // Validation should still exist when no structural changes occurred + const adapter = _getAdapter()!; + const row = adapter.prepare( + `SELECT * FROM assessments WHERE milestone_id = 'M001' AND scope = 'milestone-validation'`, + ).get() as Record | undefined; + assert.ok(row, 'milestone-validation row should survive when no structural changes occurred'); + } finally { + cleanup(base); + } +}); diff --git a/src/resources/extensions/gsd/tests/reconciliation-edge-cases.test.ts b/src/resources/extensions/gsd/tests/reconciliation-edge-cases.test.ts new file mode 100644 index 000000000..0413859b6 --- /dev/null +++ b/src/resources/extensions/gsd/tests/reconciliation-edge-cases.test.ts @@ -0,0 +1,162 @@ +// GSD State Machine Regression Tests — Event Replay & Reconciliation (#3161) + +import { describe, test, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import * as os from "node:os"; +import { findForkPoint, readEvents, appendEvent } from "../workflow-events.ts"; +import type { WorkflowEvent } from "../workflow-events.ts"; +import { extractEntityKey, detectConflicts } from "../workflow-reconcile.ts"; + +// ─── Helper: build a full WorkflowEvent from cmd + params ──────────────────── + +function makeEvent(cmd: string, params: Record, ts?: string): WorkflowEvent { + const hash = createHash("sha256") + .update(JSON.stringify({ cmd, params })) + .digest("hex") + .slice(0, 16); + return { cmd, params, ts: ts ?? new Date().toISOString(), hash, actor: "agent", session_id: "test-session" }; +} + +// ─── Temp dir management ───────────────────────────────────────────────────── + +const tempDirs: string[] = []; + +function tempDir(): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-recon-test-")); + tempDirs.push(dir); + return dir; +} + +afterEach(() => { + for (const dir of tempDirs.splice(0)) { + try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } + } +}); + +// ─── Tests ──────────────────────────────────────────────────────────────────── + +describe("reconciliation-edge-cases", () => { + + // findForkPoint + test("findForkPoint returns -1 for completely diverged logs", () => { + const eA = makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }); + const eB = makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T02" }); + + const logA: WorkflowEvent[] = [eA]; + const logB: WorkflowEvent[] = [eB]; + + assert.equal(findForkPoint(logA, logB), -1, "completely diverged logs should return -1"); + }); + + test("findForkPoint returns last index when one log is prefix of another", () => { + const e1 = makeEvent("start_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }); + const e2 = makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }); + const e3 = makeEvent("complete_slice", { milestoneId: "M001", sliceId: "S01" }); + + const logA: WorkflowEvent[] = [e1, e2]; + const logB: WorkflowEvent[] = [e1, e2, e3]; + + assert.equal(findForkPoint(logA, logB), 1, "prefix log should fork at last shared index"); + }); + + test("findForkPoint returns -1 for empty logs", () => { + assert.equal(findForkPoint([], []), -1, "two empty logs should return -1"); + }); + + // extractEntityKey + test("extractEntityKey returns null for malformed events (missing taskId)", () => { + const event = makeEvent("complete_task", {}); + // params has no taskId — should return null rather than return a bad key + assert.equal(extractEntityKey(event), null, "missing taskId should yield null entity key"); + }); + + test("extractEntityKey returns null for unknown commands", () => { + const event = makeEvent("future_cmd", { foo: "bar" }); + assert.equal(extractEntityKey(event), null, "unknown command should yield null entity key"); + }); + + test("plan_slice and complete_slice use different entity types", () => { + const planEvent = makeEvent("plan_slice", { sliceId: "S01" }); + const completeEvent = makeEvent("complete_slice", { sliceId: "S01" }); + + const planKey = extractEntityKey(planEvent); + const completeKey = extractEntityKey(completeEvent); + + assert.ok(planKey !== null, "plan_slice should produce an entity key"); + assert.ok(completeKey !== null, "complete_slice should produce an entity key"); + assert.equal(planKey!.type, "slice_plan", "plan_slice entity type should be 'slice_plan'"); + assert.equal(completeKey!.type, "slice", "complete_slice entity type should be 'slice'"); + assert.notEqual( + planKey!.type, + completeKey!.type, + "plan_slice and complete_slice must map to different entity types", + ); + }); + + // detectConflicts + test("detectConflicts finds no conflicts when entities do not overlap", () => { + const mainDiverged: WorkflowEvent[] = [ + makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }), + ]; + const wtDiverged: WorkflowEvent[] = [ + makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T02" }), + ]; + + const conflicts = detectConflicts(mainDiverged, wtDiverged); + assert.equal(conflicts.length, 0, "non-overlapping task edits should produce no conflicts"); + }); + + test("detectConflicts flags conflict when both sides touch the same task", () => { + const mainDiverged: WorkflowEvent[] = [ + makeEvent("start_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }), + ]; + const wtDiverged: WorkflowEvent[] = [ + makeEvent("complete_task", { milestoneId: "M001", sliceId: "S01", taskId: "T01" }), + ]; + + const conflicts = detectConflicts(mainDiverged, wtDiverged); + assert.equal(conflicts.length, 1, "same task touched by both sides should produce exactly one conflict"); + + const conflict = conflicts[0]!; + assert.equal(conflict.entityType, "task", "conflict entityType should be 'task'"); + assert.equal(conflict.entityId, "T01", "conflict entityId should be 'T01'"); + }); + + test("detectConflicts ignores events with null entity keys", () => { + // Events with unknown commands produce null keys and must not cause false conflicts. + const mainDiverged: WorkflowEvent[] = [ + makeEvent("unknown_future_cmd", { milestoneId: "M001" }), + ]; + const wtDiverged: WorkflowEvent[] = [ + makeEvent("another_unknown_cmd", { milestoneId: "M001" }), + ]; + + const conflicts = detectConflicts(mainDiverged, wtDiverged); + assert.equal(conflicts.length, 0, "unknown commands with null entity keys should not produce conflicts"); + }); + + // appendEvent — filesystem creation + test("appendEvent creates event log if directory does not exist", () => { + const base = tempDir(); + // Remove the .gsd directory if it somehow exists — appendEvent should create it. + const gsdDir = path.join(base, ".gsd"); + if (fs.existsSync(gsdDir)) fs.rmSync(gsdDir, { recursive: true, force: true }); + + appendEvent(base, { + cmd: "complete_task", + params: { milestoneId: "M001", sliceId: "S01", taskId: "T01" }, + ts: new Date().toISOString(), + actor: "agent", + }); + + const logPath = path.join(base, ".gsd", "event-log.jsonl"); + assert.ok(fs.existsSync(logPath), "event-log.jsonl should be created by appendEvent"); + + const events = readEvents(logPath); + assert.equal(events.length, 1, "event log should contain exactly one event"); + assert.equal(events[0]!.cmd, "complete_task", "persisted event should have the correct cmd"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/register-shortcuts.test.ts b/src/resources/extensions/gsd/tests/register-shortcuts.test.ts new file mode 100644 index 000000000..e67902af2 --- /dev/null +++ b/src/resources/extensions/gsd/tests/register-shortcuts.test.ts @@ -0,0 +1,73 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { registerShortcuts } from "../bootstrap/register-shortcuts.ts"; + +function makeTempDir(prefix: string): string { + const dir = join( + tmpdir(), + `gsd-register-shortcuts-test-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, + ); + mkdirSync(dir, { recursive: true }); + return dir; +} + +function cleanup(dir: string): void { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // best-effort + } +} + +test("dashboard shortcut resolves the project root instead of the current worktree path", async (t) => { + const projectRoot = makeTempDir("project"); + const worktreeRoot = join(projectRoot, ".gsd", "worktrees", "M001"); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + mkdirSync(worktreeRoot, { recursive: true }); + + const originalCwd = process.cwd(); + process.chdir(worktreeRoot); + t.after(() => { + process.chdir(originalCwd); + cleanup(projectRoot); + }); + + let capturedHandler: ((ctx: any) => Promise) | null = null; + const shortcuts: Array<{ description: string; handler: (ctx: any) => Promise }> = []; + const pi = { + registerShortcut: (_key: unknown, shortcut: { description: string; handler: (ctx: any) => Promise }) => { + shortcuts.push(shortcut); + if (!capturedHandler) { + capturedHandler = shortcut.handler; + } + }, + } as any; + + registerShortcuts(pi); + assert.ok(capturedHandler, "dashboard shortcut is registered"); + const dashboardShortcut = shortcuts[0]; + assert.ok(dashboardShortcut, "dashboard shortcut is captured"); + + let customCalls = 0; + const notices: Array<{ message: string; type?: string }> = []; + await dashboardShortcut.handler({ + hasUI: true, + ui: { + custom: async () => { + customCalls++; + return true; + }, + notify: (message: string, type?: string) => { + notices.push({ message, type }); + }, + }, + }); + + assert.ok(customCalls > 0, "shortcut opens the dashboard overlay when project root is resolved"); + assert.equal(notices.length, 0, "shortcut does not fall back to the missing-.gsd warning"); + assert.equal(shortcuts.length, 3, "all GSD shortcuts are still registered"); +}); diff --git a/src/resources/extensions/gsd/tests/remote-questions.test.ts b/src/resources/extensions/gsd/tests/remote-questions.test.ts index 23432a2c0..c780e6ecc 100644 --- a/src/resources/extensions/gsd/tests/remote-questions.test.ts +++ b/src/resources/extensions/gsd/tests/remote-questions.test.ts @@ -739,6 +739,125 @@ test("config source-level: hydration skips api_key entries with empty keys", () ); }); +test("ask-user-questions source-level: tryRemoteQuestions is called before the hasUI guard", () => { + // Regression test for #3480 — remote questions were silently skipped in interactive + // mode because tryRemoteQuestions was gated behind `if (!ctx.hasUI)`. + // The fix moved the remote call before that guard so configured channels + // (Telegram/Slack/Discord) fire regardless of UI availability. + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + + const remoteCallIdx = src.indexOf("tryRemoteQuestions(params.questions"); + const hasUIGuardIdx = src.indexOf("if (!ctx.hasUI)"); + + assert.ok(remoteCallIdx !== -1, "tryRemoteQuestions call should exist in ask-user-questions.ts"); + assert.ok(hasUIGuardIdx !== -1, "!ctx.hasUI guard should exist in ask-user-questions.ts"); + assert.ok( + remoteCallIdx < hasUIGuardIdx, + "tryRemoteQuestions must be called before the !ctx.hasUI guard — otherwise remote questions are skipped in interactive mode", + ); +}); + +// ═══════════════════════════════════════════════════════════════════════════ +// Race model tests (#3810) — local TUI races against remote channel +// ═══════════════════════════════════════════════════════════════════════════ + +test("ask-user-questions source-level: raceRemoteAndLocal function exists", () => { + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + assert.ok( + src.includes("async function raceRemoteAndLocal("), + "raceRemoteAndLocal helper should exist for racing local TUI against remote channel", + ); +}); + +test("ask-user-questions source-level: race path uses isRemoteConfigured for routing", () => { + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + assert.ok( + src.includes("isRemoteConfigured()"), + "execute() should call isRemoteConfigured() for lightweight routing decision", + ); +}); + +test("ask-user-questions source-level: race path checks both hasRemote and ctx.hasUI", () => { + // Regression: #3810 — the race should only activate when BOTH remote and local UI + // are available. Headless mode should still use remote-only, and no-remote should + // use local-only. + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + assert.ok( + src.includes("hasRemote && ctx.hasUI"), + "Race path should require both remote configured and local UI available", + ); + assert.ok( + src.includes("hasRemote && !ctx.hasUI"), + "Headless path should handle remote-only when no local UI", + ); +}); + +test("ask-user-questions source-level: race treats remote timeout as non-win", () => { + // Regression: the whole point of the race is that a remote timeout should NOT + // block the local TUI. The race helper must filter out timed_out results. + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + const raceFnStart = src.indexOf("async function raceRemoteAndLocal("); + const raceFnEnd = src.indexOf("\n}", raceFnStart); + const raceFnBody = src.slice(raceFnStart, raceFnEnd); + assert.ok( + raceFnBody.includes("timed_out"), + "raceRemoteAndLocal should check for timed_out in remote results", + ); + assert.ok( + raceFnBody.includes("details?.error"), + "raceRemoteAndLocal should check for error in remote results", + ); +}); + +test("ask-user-questions source-level: race uses AbortController to cancel loser", () => { + const src = readFileSync( + join(__dirname, "..", "..", "ask-user-questions.ts"), + "utf-8", + ); + assert.ok( + src.includes("new AbortController()"), + "Race path should create an AbortController for cancellation", + ); + assert.ok( + src.includes("controller.abort()"), + "raceRemoteAndLocal should abort the controller to cancel the losing side", + ); +}); + +test("manager source-level: isRemoteConfigured export exists", () => { + const src = readFileSync( + join(__dirname, "..", "..", "remote-questions", "manager.ts"), + "utf-8", + ); + assert.ok( + src.includes("export function isRemoteConfigured()"), + "manager.ts should export isRemoteConfigured for lightweight config checking", + ); + // Must delegate to resolveRemoteConfig — no separate config parsing + const fnStart = src.indexOf("export function isRemoteConfigured()"); + const fnEnd = src.indexOf("\n}", fnStart); + const fnBody = src.slice(fnStart, fnEnd); + assert.ok( + fnBody.includes("resolveRemoteConfig()"), + "isRemoteConfigured should delegate to resolveRemoteConfig", + ); +}); + test("config source-level: removeProviderToken uses auth.remove not auth.set with empty key", () => { const commandSrc = readFileSync( join(__dirname, "..", "..", "remote-questions", "remote-command.ts"), diff --git a/src/resources/extensions/gsd/tests/resource-loader-import-path.test.ts b/src/resources/extensions/gsd/tests/resource-loader-import-path.test.ts new file mode 100644 index 000000000..0908d12d6 --- /dev/null +++ b/src/resources/extensions/gsd/tests/resource-loader-import-path.test.ts @@ -0,0 +1,38 @@ +// GSD2 — Regression test for broken resource-loader import path +// Ensures auto.ts imports resource-loader via package resolution, not a +// relative path that breaks when deployed to ~/.gsd/agent/extensions/gsd/. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8"); + +describe("resource-loader import path", () => { + test("must not use relative import reaching above extensions/", () => { + // The old broken pattern: import("../../../" + "resource-loader.js") + // This resolves to ~/.gsd/resource-loader.js from deployed location, which + // doesn't exist. Regression introduced in #3899. + const brokenPattern = /import\(\s*["']\.\.\/\.\.\/\.\..*resource-loader/; + assert.ok( + !brokenPattern.test(autoSrc), + "auto.ts must not import resource-loader via relative path above extensions/ — " + + "breaks when deployed to ~/.gsd/agent/extensions/gsd/ (see #3899)", + ); + }); + + test("uses GSD_PKG_ROOT to resolve resource-loader from package root", () => { + // The fix uses GSD_PKG_ROOT (set by loader.ts) to construct an absolute + // file URL to dist/resource-loader.js — works in both source and deployed, + // and on Windows where raw paths fail with ERR_UNSUPPORTED_ESM_URL_SCHEME. + assert.ok( + autoSrc.includes('process.env.GSD_PKG_ROOT'), + "auto.ts should use GSD_PKG_ROOT to resolve resource-loader", + ); + assert.ok( + autoSrc.includes('pathToFileURL'), + "auto.ts should convert path to file URL for cross-platform import()", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/restore-tools-after-discuss.test.ts b/src/resources/extensions/gsd/tests/restore-tools-after-discuss.test.ts new file mode 100644 index 000000000..a820125e9 --- /dev/null +++ b/src/resources/extensions/gsd/tests/restore-tools-after-discuss.test.ts @@ -0,0 +1,63 @@ +/** + * Regression test for #3628 — restore tool set after discuss flow scoping + * + * The discuss flow narrows the active tool set to avoid "grammar too complex" + * errors. Without restoring after sendMessage, the narrowed tools leaked into + * subsequent dispatches, breaking plan/execute flows. + * + * The fix saves the full tool set before scoping and restores it after + * sendMessage returns. + */ + +import { describe, it } from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' + +const src = readFileSync( + resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'guided-flow.ts'), + 'utf-8', +) + +describe('restore tools after discuss flow scoping (#3628)', () => { + it('savedTools is declared before the discuss scoping block', () => { + // savedTools must be declared before the discuss-* check + const savedToolsDecl = src.indexOf('let savedTools') + const discussCheck = src.indexOf('if (unitType?.startsWith("discuss-"))') + assert.ok(savedToolsDecl !== -1, 'savedTools variable must be declared') + assert.ok(discussCheck !== -1, 'discuss-* type check must exist') + assert.ok( + savedToolsDecl < discussCheck, + 'savedTools must be declared before the discuss scoping block', + ) + }) + + it('savedTools captures current tools inside the discuss block', () => { + const discussCheck = src.indexOf('if (unitType?.startsWith("discuss-"))') + assert.ok(discussCheck !== -1) + + // Look for savedTools assignment within the discuss block + const blockAfter = src.slice(discussCheck, discussCheck + 500) + assert.ok( + blockAfter.includes('savedTools = currentTools'), + 'savedTools must be assigned from currentTools inside the discuss block', + ) + }) + + it('savedTools is restored after sendMessage', () => { + // Find the sendMessage call + const sendMsg = src.indexOf('triggerTurn: true') + assert.ok(sendMsg !== -1, 'sendMessage with triggerTurn must exist') + + // After sendMessage, savedTools should be restored via setActiveTools + const afterSend = src.slice(sendMsg, sendMsg + 500) + assert.ok( + afterSend.includes('if (savedTools)'), + 'savedTools restoration guard must exist after sendMessage', + ) + assert.ok( + afterSend.includes('setActiveTools(savedTools)'), + 'setActiveTools(savedTools) must be called to restore the full tool set', + ) + }) +}) diff --git a/src/resources/extensions/gsd/tests/roadmap-slices.test.ts b/src/resources/extensions/gsd/tests/roadmap-slices.test.ts index 63f607683..662013ad6 100644 --- a/src/resources/extensions/gsd/tests/roadmap-slices.test.ts +++ b/src/resources/extensions/gsd/tests/roadmap-slices.test.ts @@ -133,6 +133,19 @@ test("parseRoadmapSlices: table with glyph completion markers (#2841)", () => { assert.equal(slices[3]?.done, true); }); +test("parseRoadmapSlices: table with heavy check mark U+2714 (#2940)", () => { + const tableContent = [ + "# M003: Heavy Check", "", "## Slices", "", + "| Slice | Title | Risk | Status |", "|---|---|---|---|", + "| S01 | First | Low | \u2714 |", + "| S02 | Second | High | Pending |", "", + ].join("\n"); + const slices = parseRoadmapSlices(tableContent); + assert.equal(slices.length, 2); + assert.equal(slices[0]?.done, true, "U+2714 heavy check mark should mark slice as done"); + assert.equal(slices[1]?.done, false); +}); + test("parseRoadmapSlices: table with dependencies column (#1736)", () => { const tableContent = [ "# M004: Deps", "", "## Slices", "", @@ -296,3 +309,156 @@ Do the second thing. assert.equal(slices[0]?.id, "S01"); assert.equal(slices[1]?.id, "S02"); }); + +// ── Regression tests for #2567 ───────────────────────────────────────────── +// Prose H3 parser fails on common LLM-generated patterns: numbered prefixes, +// parenthetical numbering, bracketed IDs, and indented headings. + +test("parseRoadmapSlices: numbered H3 headers under ## Slices (#2567)", () => { + const numberedContent = `# M002: My Milestone + +**Vision:** Ship the product. + +## Slices + +### 1. S01: Setup Environment +Set up the dev environment and tooling. + +### 2. S02: Build Core +Implement the core logic. +**Depends on:** S01 + +### 3. S03: Polish UI +Final polish and theming. +**Depends on:** S01, S02 +`; + const slices = parseRoadmapSlices(numberedContent); + assert.equal(slices.length, 3, "should parse 3 slices from numbered H3 headers"); + assert.equal(slices[0]?.id, "S01"); + assert.equal(slices[0]?.title, "Setup Environment"); + assert.equal(slices[1]?.id, "S02"); + assert.deepEqual(slices[1]?.depends, ["S01"]); + assert.equal(slices[2]?.id, "S03"); + assert.deepEqual(slices[2]?.depends, ["S01", "S02"]); +}); + +test("parseRoadmapSlices: parenthetical-numbered H3 headers (#2567)", () => { + const parenContent = `# M002: Milestone + +**Vision:** Ship. + +## Slices + +### (1) S01: Setup +Setup work. + +### (2) S02: Build +Build work. +**Depends on:** S01 +`; + const slices = parseRoadmapSlices(parenContent); + assert.equal(slices.length, 2, "should parse slices with parenthetical numbering"); + assert.equal(slices[0]?.id, "S01"); + assert.equal(slices[0]?.title, "Setup"); + assert.equal(slices[1]?.id, "S02"); + assert.deepEqual(slices[1]?.depends, ["S01"]); +}); + +test("parseRoadmapSlices: bracketed slice IDs in H3 headers (#2567)", () => { + const bracketContent = `# M002: Milestone + +**Vision:** Ship. + +## Slices + +### [S01] Setup Environment +Setup work. + +### [S02] Build Core +Build work. +**Depends on:** S01 +`; + const slices = parseRoadmapSlices(bracketContent); + assert.equal(slices.length, 2, "should parse slices with bracketed IDs"); + assert.equal(slices[0]?.id, "S01"); + assert.equal(slices[0]?.title, "Setup Environment"); + assert.equal(slices[1]?.id, "S02"); + assert.deepEqual(slices[1]?.depends, ["S01"]); +}); + +test("parseRoadmapSlices: indented H3 headers under ## Slices (#2567)", () => { + const indentedContent = `# M002: Milestone + +**Vision:** Ship. + +## Slices + + ### S01: Setup + Setup work. + + ### S02: Build + Build work. +`; + const slices = parseRoadmapSlices(indentedContent); + assert.equal(slices.length, 2, "should parse slices from indented H3 headers"); + assert.equal(slices[0]?.id, "S01"); + assert.equal(slices[0]?.title, "Setup"); + assert.equal(slices[1]?.id, "S02"); + assert.equal(slices[1]?.title, "Build"); +}); + +// ── Regression tests for #1884: ✅ (U+2705) completion marker ────────────── + +test("parseRoadmapSlices: prose headers with ✅ suffix detected as done (#1884)", () => { + const proseContent = `# M013: Prose Roadmap + +### S01: Plan Limits & Billing Foundation ✅ +All tasks done. + +### S02: Usage Tracking +Not done yet. + +### S03: Notification System ✅ +Also done. +`; + const slices = parseRoadmapSlices(proseContent); + assert.equal(slices.length, 3); + assert.equal(slices[0]?.id, "S01"); + assert.equal(slices[0]?.done, true, "S01 with trailing ✅ should be done"); + assert.equal(slices[0]?.title, "Plan Limits & Billing Foundation"); + assert.equal(slices[1]?.done, false); + assert.equal(slices[2]?.done, true, "S03 with trailing ✅ should be done"); + assert.equal(slices[2]?.title, "Notification System"); +}); + +test("parseRoadmapSlices: prose headers with ✅ prefix before title detected as done (#1884)", () => { + const proseContent = `# M014: Prose + +## ✅ S01: Done Slice +Complete. + +## S02: Pending Slice +Not done. +`; + const slices = parseRoadmapSlices(proseContent); + assert.equal(slices.length, 2); + assert.equal(slices[0]?.done, true, "prefix ✅ should mark as done"); + assert.equal(slices[0]?.title, "Done Slice"); + assert.equal(slices[1]?.done, false); +}); + +test("parseRoadmapSlices: prose headers with ✅ after separator detected as done (#1884)", () => { + const proseContent = `# M015: Prose + +## S01: ✅ First Feature +Done. + +## S02: Second Feature +Not done. +`; + const slices = parseRoadmapSlices(proseContent); + assert.equal(slices.length, 2); + assert.equal(slices[0]?.done, true, "✅ after colon should mark as done"); + assert.equal(slices[0]?.title, "First Feature"); + assert.equal(slices[1]?.done, false); +}); diff --git a/src/resources/extensions/gsd/tests/rogue-file-detection.test.ts b/src/resources/extensions/gsd/tests/rogue-file-detection.test.ts index e0fd6c00e..09110adf7 100644 --- a/src/resources/extensions/gsd/tests/rogue-file-detection.test.ts +++ b/src/resources/extensions/gsd/tests/rogue-file-detection.test.ts @@ -149,7 +149,7 @@ test("rogue detection: DB not available → returns empty array (graceful degrad } }); -test("rogue detection: slice summary on disk, no DB row → detected as rogue", () => { +test("rogue detection: slice summary on disk, no DB row → auto-remediated (not rogue)", () => { const basePath = createTmpBase(); const dbPath = join(basePath, ".gsd", "gsd.db"); mkdirSync(join(basePath, ".gsd"), { recursive: true }); @@ -160,11 +160,10 @@ test("rogue detection: slice summary on disk, no DB row → detected as rogue", const summaryPath = createSliceSummaryOnDisk(basePath, "M001", "S01"); assert.ok(existsSync(summaryPath), "Slice summary file should exist on disk"); + // Fix #3633: stale slice DB status is auto-remediated via updateSliceStatus() + // instead of being reported as rogue, so rogues array should be empty. const rogues = detectRogueFileWrites("complete-slice", "M001/S01", basePath); - assert.equal(rogues.length, 1, "Should detect one rogue slice file"); - assert.equal(rogues[0].path, summaryPath); - assert.equal(rogues[0].unitType, "complete-slice"); - assert.equal(rogues[0].unitId, "M001/S01"); + assert.equal(rogues.length, 0, "Should auto-remediate stale slice, not report as rogue"); } finally { closeDatabase(); rmSync(basePath, { recursive: true, force: true }); diff --git a/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts b/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts new file mode 100644 index 000000000..0d4b80b65 --- /dev/null +++ b/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts @@ -0,0 +1,51 @@ +/** + * Regression test for #3624 — cap run-uat dispatch attempts + * + * When verification commands fail before writing a verdict, the run-uat + * dispatch rule fires repeatedly in an infinite loop. The fix adds a + * MAX_UAT_ATTEMPTS constant and calls incrementUatCount before dispatch + * to cap the number of attempts. + * + * Structural verification test — reads source to confirm MAX_UAT_ATTEMPTS + * and incrementUatCount exist. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'auto-dispatch.ts'), 'utf-8'); + +describe('run-uat replay cap (#3624)', () => { + test('MAX_UAT_ATTEMPTS constant is defined', () => { + assert.match(source, /const MAX_UAT_ATTEMPTS\s*=\s*\d+/, + 'MAX_UAT_ATTEMPTS constant should be defined'); + }); + + test('incrementUatCount function is exported', () => { + assert.match(source, /export function incrementUatCount\(/, + 'incrementUatCount should be an exported function'); + }); + + test('getUatCount function is exported', () => { + assert.match(source, /export function getUatCount\(/, + 'getUatCount should be an exported function'); + }); + + test('incrementUatCount is called before dispatch in rule', () => { + // incrementUatCount should be called before the dispatch return + const ruleSection = source.slice(source.indexOf('checkNeedsRunUat')); + assert.match(ruleSection, /incrementUatCount\(/, + 'incrementUatCount should be called in the dispatch rule'); + }); + + test('attempts are compared against MAX_UAT_ATTEMPTS', () => { + assert.match(source, /attempts\s*>\s*MAX_UAT_ATTEMPTS/, + 'dispatch should check attempts > MAX_UAT_ATTEMPTS'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/secure-env-collect.test.ts b/src/resources/extensions/gsd/tests/secure-env-collect.test.ts index bd6096674..3e1a5e109 100644 --- a/src/resources/extensions/gsd/tests/secure-env-collect.test.ts +++ b/src/resources/extensions/gsd/tests/secure-env-collect.test.ts @@ -183,3 +183,182 @@ test("secure_env_collect: detectDestination — convex file (not dir) does not t rmSync(tmp, { recursive: true, force: true }); } }); + +// ─── Bug #2997: undefined vs null handling ────────────────────────────────── + +/** + * When ctx.ui.custom() returns undefined (e.g. noOpUIContext, component + * disposal, abort), the strict null checks (=== null / !== null) let + * undefined slip through as a "provided" value, crashing writeEnvKey + * which calls .replace() on it. + * + * These tests verify the fix: loose equality (== null / != null) so that + * both null AND undefined are treated as "skipped". + */ + +// Helper to dynamically load the orchestrator +async function loadOrchestrator(): Promise<{ + collectSecretsFromManifest: Function; +}> { + const mod = await import("../../get-secrets-from-user.ts"); + return { collectSecretsFromManifest: mod.collectSecretsFromManifest }; +} + +// Helper to dynamically load files.ts functions +async function loadFilesExports(): Promise<{ + formatSecretsManifest: (m: any) => string; +}> { + const mod = await import("../files.ts"); + return { formatSecretsManifest: mod.formatSecretsManifest }; +} + +function makeManifest(entries: Array<{ key: string; status?: string; formatHint?: string; guidance?: string[] }>): any { + return { + milestone: "M001", + generatedAt: "2026-03-12T00:00:00Z", + entries: entries.map((e) => ({ + key: e.key, + service: "TestService", + dashboardUrl: "", + guidance: e.guidance ?? [], + formatHint: e.formatHint ?? "", + status: e.status ?? "pending", + destination: "dotenv", + })), + }; +} + +async function writeManifestFile(dir: string, manifest: any): Promise { + const { formatSecretsManifest } = await loadFilesExports(); + const milestoneDir = join(dir, ".gsd", "milestones", "M001"); + mkdirSync(milestoneDir, { recursive: true }); + const filePath = join(milestoneDir, "M001-SECRETS.md"); + writeFileSync(filePath, formatSecretsManifest(manifest)); + return filePath; +} + +test("secure_env_collect #2997: undefined from ctx.ui.custom() is treated as skipped, not provided", async (t) => { + const { collectSecretsFromManifest } = await loadOrchestrator(); + + const tmp = makeTempDir("sec-undefined-test"); + t.after(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + const manifest = makeManifest([ + { key: "SECRET_THAT_RETURNS_UNDEFINED", status: "pending" }, + ]); + await writeManifestFile(tmp, manifest); + + let callIndex = 0; + const mockCtx = { + cwd: tmp, + hasUI: true, + ui: { + // First call is summary screen, second is collect — return undefined + // to simulate noOpUIContext or component disposal + custom: async (_factory: any) => { + callIndex++; + if (callIndex <= 1) return null; // summary screen dismiss + return undefined; // BUG TRIGGER: should be treated as skipped + }, + }, + }; + + // Before the fix, this crashes with: + // "Cannot read properties of undefined (reading 'replace')" + const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any); + + // The undefined-returning key must appear in skipped, not in applied + assert.ok( + result.skipped.includes("SECRET_THAT_RETURNS_UNDEFINED"), + "Key returning undefined should be in skipped list", + ); + assert.ok( + !result.applied.includes("SECRET_THAT_RETURNS_UNDEFINED"), + "Key returning undefined must NOT be in applied list", + ); +}); + +test("secure_env_collect #2997: null from ctx.ui.custom() is still treated as skipped (regression guard)", async (t) => { + const { collectSecretsFromManifest } = await loadOrchestrator(); + + const tmp = makeTempDir("sec-null-test"); + t.after(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + const manifest = makeManifest([ + { key: "SECRET_THAT_RETURNS_NULL", status: "pending" }, + ]); + await writeManifestFile(tmp, manifest); + + let callIndex = 0; + const mockCtx = { + cwd: tmp, + hasUI: true, + ui: { + custom: async (_factory: any) => { + callIndex++; + if (callIndex <= 1) return null; // summary screen dismiss + return null; // explicit null skip + }, + }, + }; + + const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any); + + assert.ok( + result.skipped.includes("SECRET_THAT_RETURNS_NULL"), + "Key returning null should be in skipped list", + ); + assert.ok( + !result.applied.includes("SECRET_THAT_RETURNS_NULL"), + "Key returning null must NOT be in applied list", + ); +}); + +test("secure_env_collect: falls back to secure input prompt when custom UI is unavailable", async (t) => { + const { collectSecretsFromManifest } = await loadOrchestrator(); + + const tmp = makeTempDir("sec-input-fallback-test"); + t.after(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + const manifest = makeManifest([ + { key: "SECRET_FROM_INPUT_FALLBACK", status: "pending", formatHint: "starts with sk-" }, + ]); + await writeManifestFile(tmp, manifest); + + let callIndex = 0; + const inputCalls: Array<{ title: string; placeholder?: string; opts?: { secure?: boolean } }> = []; + const mockCtx = { + cwd: tmp, + hasUI: true, + ui: { + custom: async (_factory: any) => { + callIndex++; + if (callIndex <= 1) return null; // summary screen dismiss + return undefined; // collect screen unavailable on this surface + }, + input: async (title: string, placeholder?: string, opts?: { secure?: boolean }) => { + inputCalls.push({ title, placeholder, opts }); + return " sk-test-fallback-value "; + }, + }, + }; + + const result = await collectSecretsFromManifest(tmp, "M001", mockCtx as any); + + assert.ok( + result.applied.includes("SECRET_FROM_INPUT_FALLBACK"), + "Fallback input should collect and apply the key", + ); + assert.ok( + !result.skipped.includes("SECRET_FROM_INPUT_FALLBACK"), + "Fallback input should not mark the key as skipped", + ); + assert.equal(inputCalls.length, 1, "Fallback input should be requested once"); + assert.equal(inputCalls[0]?.opts?.secure, true, "Fallback input should request secure entry when supported"); +}); diff --git a/src/resources/extensions/gsd/tests/shared-wal.test.ts b/src/resources/extensions/gsd/tests/shared-wal.test.ts index 6fb425854..8bf0972dd 100644 --- a/src/resources/extensions/gsd/tests/shared-wal.test.ts +++ b/src/resources/extensions/gsd/tests/shared-wal.test.ts @@ -68,6 +68,36 @@ describe('shared-wal', async () => { 'forward-slash worktree path resolves correctly'); } + // ─── Test (e1): external-state worktree resolves to project state DB (#2952) ─── + console.log('\n=== shared-wal: resolve external-state worktree path (#2952) ==='); + { + // External-state layout: ~/.gsd/projects//worktrees/ + // Should resolve to: ~/.gsd/projects//gsd.db + const stateRoot = '/home/user/.gsd/projects/a1b2c3d4'; + const worktreePath = join(stateRoot, 'worktrees', 'M002'); + const result = resolveProjectRootDbPath(worktreePath); + assert.deepStrictEqual(result, join(stateRoot, 'gsd.db'), + 'external-state worktree path resolves to project state DB (#2952)'); + } + + // ─── Test (e2): external-state worktree nested subdir (#2952) ───────── + console.log('\n=== shared-wal: resolve external-state worktree nested subdir (#2952) ==='); + { + const stateRoot = '/home/user/.gsd/projects/deadbeef42'; + const nestedPath = join(stateRoot, 'worktrees', 'M003', 'src', 'lib'); + const result = resolveProjectRootDbPath(nestedPath); + assert.deepStrictEqual(result, join(stateRoot, 'gsd.db'), + 'external-state nested worktree subdir resolves to project state DB (#2952)'); + } + + // ─── Test (e3): external-state worktree with forward slashes (#2952) ── + console.log('\n=== shared-wal: resolve external-state worktree forward-slash (#2952) ==='); + { + const result = resolveProjectRootDbPath('/Users/dev/.gsd/projects/cafe0123/worktrees/M001'); + assert.deepStrictEqual(result, join('/Users/dev/.gsd/projects/cafe0123', 'gsd.db'), + 'external-state forward-slash worktree path resolves correctly (#2952)'); + } + // ─── Test (e): Concurrent writes — 3 connections to same WAL DB ─────── console.log('\n=== shared-wal: concurrent writes via WAL ==='); { diff --git a/src/resources/extensions/gsd/tests/show-config-command.test.ts b/src/resources/extensions/gsd/tests/show-config-command.test.ts new file mode 100644 index 000000000..74fb3265e --- /dev/null +++ b/src/resources/extensions/gsd/tests/show-config-command.test.ts @@ -0,0 +1,56 @@ +/** + * /gsd show-config command — structural tests. + * + * Verifies the config overlay class and command handler exist + * with correct structure. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +const overlaySrc = readFileSync(join(__dirname, "..", "config-overlay.ts"), "utf-8"); +const coreSrc = readFileSync(join(__dirname, "..", "commands", "handlers", "core.ts"), "utf-8"); + +// ─── Config overlay ─────────────────────────────────────────────────────── + +test("GSDConfigOverlay class is exported", () => { + assert.ok( + overlaySrc.includes("export class GSDConfigOverlay"), + "GSDConfigOverlay should be exported", + ); +}); + +test("GSDConfigOverlay implements Component interface methods", () => { + assert.ok(overlaySrc.includes("render("), "should have render method"); + assert.ok(overlaySrc.includes("handleInput("), "should have handleInput method"); + assert.ok(overlaySrc.includes("invalidate("), "should have invalidate method"); + assert.ok(overlaySrc.includes("dispose("), "should have dispose method"); +}); + +test("formatConfigText function is exported", () => { + assert.ok( + overlaySrc.includes("export function formatConfigText"), + "formatConfigText should be exported for non-overlay fallback", + ); +}); + +// ─── Command handler ────────────────────────────────────────────────────── + +test("core handler routes show-config command", () => { + assert.ok( + coreSrc.includes('"show-config"'), + "core handler should match show-config command", + ); +}); + +test("show-config has text fallback via formatConfigText", () => { + assert.ok( + coreSrc.includes("formatConfigText"), + "show-config should use formatConfigText as fallback", + ); +}); diff --git a/src/resources/extensions/gsd/tests/silent-catch-diagnostics.test.ts b/src/resources/extensions/gsd/tests/silent-catch-diagnostics.test.ts new file mode 100644 index 000000000..87d626867 --- /dev/null +++ b/src/resources/extensions/gsd/tests/silent-catch-diagnostics.test.ts @@ -0,0 +1,284 @@ +/** + * Verify that catch blocks across GSD source files use the centralized + * workflow-logger (logWarning/logError) instead of raw process.stderr.write, + * console.error, or being completely empty (#3348, #3345). + * + * Two tests: + * 1. Auto-mode files must have zero empty catch blocks (fully migrated). + * 2. All GSD files must not use raw stderr/console in catch blocks. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync, readdirSync, statSync } from "node:fs"; +import { join, dirname, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const gsdDir = join(__dirname, ".."); + +/** Files exempt from the raw-stderr/console check */ +const EXEMPT_FILES = new Set([ + "workflow-logger.ts", // The logger itself + "debug-logger.ts", // Separate opt-in debug system +]); + +/** + * Files that have been fully migrated to workflow-logger and must not + * regress to empty catch blocks. Covers auto-mode, tools, bootstrap, + * and core infrastructure files. + */ +const MIGRATED_FILES = new Set([ + // auto-mode (detected dynamically below) + // tools/ + "tools/complete-task.ts", + "tools/complete-slice.ts", + "tools/complete-milestone.ts", + "tools/plan-milestone.ts", + "tools/plan-slice.ts", + "tools/plan-task.ts", + "tools/reassess-roadmap.ts", + "tools/reopen-task.ts", + "tools/reopen-slice.ts", + "tools/replan-slice.ts", + "tools/validate-milestone.ts", + // bootstrap/ + "bootstrap/agent-end-recovery.ts", + "bootstrap/system-context.ts", + "bootstrap/db-tools.ts", + "bootstrap/dynamic-tools.ts", + "bootstrap/journal-tools.ts", + // core infrastructure + "gsd-db.ts", + "workflow-logger.ts", + "workflow-reconcile.ts", + "workflow-migration.ts", + "workflow-projections.ts", + "workflow-events.ts", + "worktree-manager.ts", + "parallel-orchestrator.ts", + "parallel-merge.ts", + "guided-flow.ts", + "preferences.ts", + "commands-maintenance.ts", + "commands-inspect.ts", + "safe-fs.ts", + "markdown-renderer.ts", + "md-importer.ts", + "milestone-actions.ts", + "milestone-ids.ts", + "rule-registry.ts", + "custom-verification.ts", + "prompt-loader.ts", + "auto-verification.ts", +]); + +/** Patterns that indicate a catch block already uses workflow-logger */ +const LOGGER_PATTERNS = [ + /logWarning\s*\(/, + /logError\s*\(/, +]; + +function getAutoModeFiles(): string[] { + const files: string[] = []; + + // Top-level auto*.ts files + for (const f of readdirSync(gsdDir)) { + if (f.startsWith("auto") && f.endsWith(".ts") && !f.endsWith(".test.ts")) { + files.push(join(gsdDir, f)); + } + } + + // auto/ subdirectory + const autoSubDir = join(gsdDir, "auto"); + for (const f of readdirSync(autoSubDir)) { + if (f.endsWith(".ts") && !f.endsWith(".test.ts")) { + files.push(join(autoSubDir, f)); + } + } + + return files; +} + +function getGsdSourceFiles(): string[] { + const files: string[] = []; + + function walk(dir: string): void { + for (const entry of readdirSync(dir)) { + const full = join(dir, entry); + if (entry === "tests" || entry === "node_modules") continue; + try { + const st = statSync(full); + if (st.isDirectory()) { + walk(full); + } else if (entry.endsWith(".ts") && !entry.endsWith(".test.ts") && !entry.endsWith(".d.ts")) { + files.push(full); + } + } catch { + continue; + } + } + } + + walk(gsdDir); + return files; +} + +/** + * Scan a file for empty catch blocks — catches whose body contains + * only whitespace and/or comments but no executable statements. + */ +function findEmptyCatches(filePath: string): Array<{ line: number; text: string }> { + const content = readFileSync(filePath, "utf-8"); + const lines = content.split("\n"); + const results: Array<{ line: number; text: string }> = []; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + + // Match catch block opening + if (!/\}\s*catch\s*(\([^)]*\))?\s*\{/.test(line)) continue; + + // Inline single-line catch: } catch { ... } + const inlineMatch = line.match(/\}\s*catch\s*(\([^)]*\))?\s*\{(.*)\}\s*;?\s*$/); + if (inlineMatch) { + const body = inlineMatch[2].trim(); + const stripped = body.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*/g, "").trim(); + if (!stripped) { + results.push({ line: i + 1, text: line.trim() }); + } + continue; + } + + // Multi-line catch — scan until matching } + let j = i + 1; + let depth = 1; + const bodyLines: string[] = []; + while (j < lines.length && depth > 0) { + for (const ch of lines[j]) { + if (ch === "{") depth++; + else if (ch === "}") depth--; + } + bodyLines.push(lines[j].trim()); + j++; + } + + const meaningful = bodyLines.slice(0, -1).filter( + (l) => l && !l.startsWith("//") && !l.startsWith("/*") && !l.startsWith("*") && l !== "}", + ); + + if (meaningful.length === 0) { + results.push({ line: i + 1, text: line.trim() }); + } + } + + return results; +} + +/** + * Scan a file for catch blocks that use raw process.stderr.write or + * console.error/warn instead of workflow-logger. + */ +function findRawStderrCatches(filePath: string): Array<{ line: number; text: string }> { + const content = readFileSync(filePath, "utf-8"); + const lines = content.split("\n"); + const results: Array<{ line: number; text: string }> = []; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (!/\}\s*catch\s*(\([^)]*\))?\s*\{/.test(line)) continue; + + // Inline single-line catch + const inlineMatch = line.match(/\}\s*catch\s*(\([^)]*\))?\s*\{(.*)\}\s*;?\s*$/); + if (inlineMatch) { + const body = inlineMatch[2]; + if (!LOGGER_PATTERNS.some((p) => p.test(body))) { + if (/process\.stderr\.write/.test(body) || /console\.(error|warn)/.test(body)) { + results.push({ line: i + 1, text: line.trim() }); + } + } + continue; + } + + // Multi-line catch + let j = i + 1; + let depth = 1; + const bodyLines: string[] = []; + while (j < lines.length && depth > 0) { + for (const ch of lines[j]) { + if (ch === "{") depth++; + else if (ch === "}") depth--; + } + bodyLines.push(lines[j]); + j++; + } + + const bodyText = bodyLines.slice(0, -1).join("\n"); + if (!LOGGER_PATTERNS.some((p) => p.test(bodyText))) { + if (/process\.stderr\.write/.test(bodyText) || /console\.(error|warn)/.test(bodyText)) { + results.push({ line: i + 1, text: line.trim() }); + } + } + } + + return results; +} + +describe("workflow-logger coverage (#3348)", () => { + test("no empty catch blocks remain in migrated files", () => { + // Combine auto-mode files + explicitly migrated files + const autoFiles = getAutoModeFiles(); + const allFiles = getGsdSourceFiles(); + const migratedPaths = new Set(autoFiles); + for (const file of allFiles) { + const rel = relative(gsdDir, file); + if (MIGRATED_FILES.has(rel)) { + migratedPaths.add(file); + } + } + + assert.ok(migratedPaths.size > 0, "should find migrated source files"); + + const violations: string[] = []; + for (const file of migratedPaths) { + const rel = relative(gsdDir, file); + const basename = rel.split("/").pop()!; + // gsd-db.ts has intentionally silent provider probes + if (basename === "gsd-db.ts" || basename === "session-lock.ts") continue; + + const empties = findEmptyCatches(file); + for (const empty of empties) { + violations.push(`${rel}:${empty.line} — ${empty.text}`); + } + } + + assert.equal( + violations.length, + 0, + `Found ${violations.length} empty catch block(s) in migrated files:\n${violations.join("\n")}`, + ); + }); + + test("catch blocks use workflow-logger instead of raw stderr/console", () => { + const files = getGsdSourceFiles(); + assert.ok(files.length > 0, "should find GSD source files"); + + const violations: string[] = []; + for (const file of files) { + const rel = relative(gsdDir, file); + const basename = rel.split("/").pop()!; + if (EXEMPT_FILES.has(basename)) continue; + + const issues = findRawStderrCatches(file); + for (const issue of issues) { + violations.push(`${rel}:${issue.line} — ${issue.text}`); + } + } + + assert.equal( + violations.length, + 0, + `Found ${violations.length} catch block(s) using raw stderr/console instead of workflow-logger:\n${violations.join("\n")}`, + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/skip-slice-state-rebuild.test.ts b/src/resources/extensions/gsd/tests/skip-slice-state-rebuild.test.ts new file mode 100644 index 000000000..5a46cdf3c --- /dev/null +++ b/src/resources/extensions/gsd/tests/skip-slice-state-rebuild.test.ts @@ -0,0 +1,31 @@ +/** + * Regression test for #3477: gsd_skip_slice tool must rebuild STATE.md + * after updating the DB so auto-mode reads the correct state. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +test("gsd_skip_slice tool calls rebuildState after DB update (#3477)", () => { + const src = readFileSync( + join(import.meta.dirname, "..", "bootstrap", "db-tools.ts"), + "utf-8", + ); + // The fix adds a rebuildState call after updateSliceStatus in skip_slice + assert.ok( + src.includes("rebuildState"), + "gsd_skip_slice must call rebuildState after updating slice status", + ); +}); + +test("rethink prompt warns against markdown-only edits for skip (#3477)", () => { + const prompt = readFileSync( + join(import.meta.dirname, "..", "prompts", "rethink.md"), + "utf-8", + ); + assert.ok( + prompt.includes("MUST") && prompt.includes("gsd_skip_slice"), + "Rethink prompt must emphasize gsd_skip_slice tool requirement", + ); +}); diff --git a/src/resources/extensions/gsd/tests/skipped-validation-completion.test.ts b/src/resources/extensions/gsd/tests/skipped-validation-completion.test.ts new file mode 100644 index 000000000..927eb3a57 --- /dev/null +++ b/src/resources/extensions/gsd/tests/skipped-validation-completion.test.ts @@ -0,0 +1,39 @@ +/** + * Regression test for #3698 — allow milestone completion when validation + * was skipped by preference + * + * When validation is skipped due to user preference (e.g. budget profile), + * auto-dispatch should recognize the "skipped by preference" pattern and + * allow completion instead of treating it as a missing validation. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const autoDispatchSrc = readFileSync( + join(__dirname, '..', 'auto-dispatch.ts'), + 'utf-8', +); + +describe('skipped validation completion (#3698)', () => { + test('skippedByPreference regex detection exists', () => { + assert.match(autoDispatchSrc, /skippedByPreference/, + 'skippedByPreference variable should exist in auto-dispatch.ts'); + }); + + test('regex matches skip-by-preference patterns', () => { + assert.match(autoDispatchSrc, /skip\(\?:ped\)\?\[\\s\\-\]\+\(\?:by\|per\|due to\)/, + 'should have regex matching "skipped by/per/due to" patterns'); + }); + + test('skippedByPreference feeds into operational check', () => { + assert.match(autoDispatchSrc, /hasOperationalCheck\s*=\s*skippedByPreference/, + 'skippedByPreference should be part of hasOperationalCheck'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/slice-context-injection.test.ts b/src/resources/extensions/gsd/tests/slice-context-injection.test.ts new file mode 100644 index 000000000..bb7cd2005 --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-context-injection.test.ts @@ -0,0 +1,50 @@ +/** + * Regression test: S##-CONTEXT.md from slice discussion must be + * injected into all 5 downstream prompt builders (#3452). + * + * Scans auto-prompts.ts for the 5 builder functions and verifies + * each one resolves and inlines the slice-level CONTEXT file. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const autoPromptsPath = join(__dirname, "..", "auto-prompts.ts"); +const source = readFileSync(autoPromptsPath, "utf-8"); + +const BUILDERS = [ + "buildResearchSlicePrompt", + "buildPlanSlicePrompt", + "buildCompleteSlicePrompt", + "buildReplanSlicePrompt", + "buildReassessRoadmapPrompt", +]; + +describe("slice CONTEXT.md injection into prompt builders (#3452)", () => { + for (const builder of BUILDERS) { + test(`${builder} resolves slice CONTEXT file`, () => { + // Find the function body + const fnStart = source.indexOf(`export async function ${builder}`); + assert.ok(fnStart !== -1, `${builder} should exist in auto-prompts.ts`); + + // Get a reasonable chunk after the function start (enough to cover the inlining section) + const chunk = source.slice(fnStart, fnStart + 3000); + + // Must resolve the slice CONTEXT path + assert.ok( + chunk.includes('resolveSliceFile(base, mid,') && chunk.includes('"CONTEXT"'), + `${builder} should call resolveSliceFile with "CONTEXT"`, + ); + + // Must inline it with inlineFileOptional + assert.ok( + chunk.includes('Slice Context'), + `${builder} should inline slice CONTEXT with a "Slice Context" label`, + ); + }); + } +}); diff --git a/src/resources/extensions/gsd/tests/slice-disk-reconcile.test.ts b/src/resources/extensions/gsd/tests/slice-disk-reconcile.test.ts new file mode 100644 index 000000000..a40822d29 --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-disk-reconcile.test.ts @@ -0,0 +1,233 @@ +/** + * slice-disk-reconcile.test.ts — #2533 + * + * Slices that exist on disk (in ROADMAP.md) but are missing from the SQLite + * database cause permanent "No slice eligible — check dependency ordering" + * blocks. deriveStateFromDb must reconcile disk slices into the DB, just as + * it already does for milestones (#2416). + * + * Scenario: M001 has a ROADMAP with S01-S04. S01 and S02 have SUMMARY files + * (complete on disk). S03 depends on S01. Only S04 is in the DB (depends on + * S03). Without slice reconciliation, S01-S03 are invisible and S04 is + * permanently blocked. + */ + +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { deriveStateFromDb, invalidateStateCache } from "../state.ts"; +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + getMilestoneSlices, +} from "../gsd-db.ts"; +import { createTestContext } from "./test-helpers.ts"; + +const { assertEq, assertTrue, report } = createTestContext(); + +function createFixtureBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-slice-reconcile-")); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + return base; +} + +function writeFile(base: string, relativePath: string, content: string): void { + const full = join(base, ".gsd", relativePath); + mkdirSync(join(full, ".."), { recursive: true }); + writeFileSync(full, content); +} + +function cleanup(base: string): void { + rmSync(base, { recursive: true, force: true }); +} + +const CONTEXT_CONTENT = `# M001: Test Milestone + +This milestone tests slice reconciliation. + +## Must-Haves +- Something important +`; + +// Roadmap with 4 slices: S01 (no deps), S02 (no deps), S03 (depends S01), S04 (depends S03) +const ROADMAP_CONTENT = `# M001: Test Milestone + +**Vision:** Test slice disk→DB reconciliation. + +## Slices + +- [x] **S01: Foundation** \`risk:low\` \`depends:[]\` + > Set up project structure. +- [x] **S02: Core Utils** \`risk:low\` \`depends:[]\` + > Build utility functions. +- [ ] **S03: Integration** \`risk:medium\` \`depends:[S01]\` + > Integrate components. +- [ ] **S04: Final Assembly** \`risk:high\` \`depends:[S03]\` + > Assemble everything. +`; + +async function testMissingSlicesCauseBlock(): Promise { + console.log("\n--- Test: missing DB slices cause permanent block (pre-fix) ---"); + + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + + try { + openDatabase(dbPath); + + // M001 in DB + insertMilestone({ id: "M001", title: "M001: Test Milestone", status: "active", depends_on: [] }); + + // Only S04 is in the DB — S01-S03 are missing + insertSlice({ id: "S04", milestoneId: "M001", title: "S04: Final Assembly", status: "pending", risk: "high", depends: ["S03"] }); + + // Write disk files — S01 and S02 have SUMMARY (complete on disk) + writeFile(base, "milestones/M001/CONTEXT.md", CONTEXT_CONTENT); + writeFile(base, "milestones/M001/ROADMAP.md", ROADMAP_CONTENT); + writeFile(base, "milestones/M001/S01/PLAN.md", "# S01 Plan\n"); + writeFile(base, "milestones/M001/S01/SUMMARY.md", "# S01 Summary\nDone."); + writeFile(base, "milestones/M001/S02/PLAN.md", "# S02 Plan\n"); + writeFile(base, "milestones/M001/S02/SUMMARY.md", "# S02 Summary\nDone."); + writeFile(base, "milestones/M001/S03/PLAN.md", "# S03 Plan\n"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // After the fix, slices S01-S03 should be reconciled into DB + const dbSlices = getMilestoneSlices("M001"); + assertTrue( + dbSlices.length === 4, + `All 4 roadmap slices should be in DB after reconciliation, got ${dbSlices.length}`, + ); + + // S01 and S02 should be marked complete (have SUMMARY files) + const s01 = dbSlices.find(s => s.id === "S01"); + assertTrue(s01 !== undefined, "S01 should exist in DB after reconciliation"); + if (s01) { + assertEq(s01.status, "complete", "S01 should be 'complete' (has SUMMARY on disk)"); + } + + const s02 = dbSlices.find(s => s.id === "S02"); + assertTrue(s02 !== undefined, "S02 should exist in DB after reconciliation"); + if (s02) { + assertEq(s02.status, "complete", "S02 should be 'complete' (has SUMMARY on disk)"); + } + + // S03 should be pending (no SUMMARY) + const s03 = dbSlices.find(s => s.id === "S03"); + assertTrue(s03 !== undefined, "S03 should exist in DB after reconciliation"); + if (s03) { + assertEq(s03.status, "pending", "S03 should be 'pending' (no SUMMARY on disk)"); + } + + // The state should NOT be blocked — S03 should be eligible (S01 dep satisfied) + assertTrue( + state.phase !== "blocked", + `Phase should not be 'blocked' after reconciliation, got '${state.phase}'`, + ); + + // Active slice should be S03 (S01 dep met, S03 is first incomplete with satisfied deps) + assertTrue( + state.activeSlice !== null, + "There should be an active slice after reconciliation", + ); + if (state.activeSlice) { + assertEq( + state.activeSlice.id, + "S03", + "Active slice should be S03 (its dependency S01 is complete) (#2533)", + ); + } + } finally { + closeDatabase(); + cleanup(base); + } +} + +async function testSliceReconciliationIdempotent(): Promise { + console.log("\n--- Test: slice reconciliation is idempotent ---"); + + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + + try { + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active", depends_on: [] }); + // S01 already in DB with correct status + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Foundation", status: "complete", depends: [] }); + + writeFile(base, "milestones/M001/CONTEXT.md", CONTEXT_CONTENT); + writeFile(base, "milestones/M001/ROADMAP.md", ROADMAP_CONTENT); + writeFile(base, "milestones/M001/S01/PLAN.md", "# S01 Plan\n"); + writeFile(base, "milestones/M001/S01/SUMMARY.md", "# S01 Summary\nDone."); + writeFile(base, "milestones/M001/S02/PLAN.md", "# S02 Plan\n"); + writeFile(base, "milestones/M001/S02/SUMMARY.md", "# S02 Summary\nDone."); + + invalidateStateCache(); + await deriveStateFromDb(base); + + // S01 should still be complete (not overwritten) + const dbSlices = getMilestoneSlices("M001"); + const s01 = dbSlices.find(s => s.id === "S01"); + assertTrue(s01 !== undefined, "S01 should still exist in DB"); + if (s01) { + assertEq(s01.status, "complete", "S01 status should remain 'complete' (not overwritten)"); + } + + // S02-S04 should have been added + assertTrue( + dbSlices.length === 4, + `Should have 4 slices after reconciliation (existing + new), got ${dbSlices.length}`, + ); + } finally { + closeDatabase(); + cleanup(base); + } +} + +async function testNoRoadmapSkipsReconciliation(): Promise { + console.log("\n--- Test: no ROADMAP file skips slice reconciliation ---"); + + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + + try { + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: No Roadmap", status: "active", depends_on: [] }); + + // Only a CONTEXT file, no ROADMAP + writeFile(base, "milestones/M001/CONTEXT.md", CONTEXT_CONTENT); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + const dbSlices = getMilestoneSlices("M001"); + assertEq(dbSlices.length, 0, "No slices should be added when no ROADMAP exists"); + + // Should be in pre-planning (no roadmap) + assertEq(state.phase, "pre-planning", "Phase should be pre-planning with no roadmap"); + } finally { + closeDatabase(); + cleanup(base); + } +} + +async function main(): Promise { + console.log("\n=== #2533: deriveStateFromDb reconciles disk slices ==="); + + await testMissingSlicesCauseBlock(); + await testSliceReconciliationIdempotent(); + await testNoRoadmapSkipsReconciliation(); + + report(); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/src/resources/extensions/gsd/tests/slice-parallel-conflict.test.ts b/src/resources/extensions/gsd/tests/slice-parallel-conflict.test.ts new file mode 100644 index 000000000..375774215 --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-parallel-conflict.test.ts @@ -0,0 +1,92 @@ +/** + * Tests for slice-level parallel conflict detection. + * Verifies hasFileConflict() correctly identifies when two slices + * touch too many of the same files to safely run in parallel. + */ + +import { describe, it, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { hasFileConflict } from "../slice-parallel-conflict.js"; + +// ─── Helpers ────────────────────────────────────────────────────────────────── + +function makeTmpBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-slice-conflict-test-")); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function writeSlicePlan(base: string, mid: string, sid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid, sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "PLAN.md"), content, "utf-8"); +} + +describe("hasFileConflict", () => { + let base: string; + + beforeEach(() => { + base = makeTmpBase(); + }); + + afterEach(() => { + rmSync(base, { recursive: true, force: true }); + }); + + it("two slices with >5 overlapping file paths → blocked (true)", () => { + const planA = `# Plan S01 +## Tasks +- T01: Update src/auth/login.ts +- T02: Update src/auth/register.ts +- T03: Update src/auth/session.ts +- T04: Update src/auth/middleware.ts +- T05: Update src/auth/types.ts +- T06: Update src/auth/utils.ts +`; + const planB = `# Plan S02 +## Tasks +- T01: Refactor src/auth/login.ts +- T02: Refactor src/auth/register.ts +- T03: Refactor src/auth/session.ts +- T04: Refactor src/auth/middleware.ts +- T05: Refactor src/auth/types.ts +- T06: Refactor src/auth/utils.ts +`; + writeSlicePlan(base, "M001", "S01", planA); + writeSlicePlan(base, "M001", "S02", planB); + assert.equal(hasFileConflict(base, "M001", "S01", "S02"), true); + }); + + it("two slices with 0 overlapping paths → allowed (false)", () => { + const planA = `# Plan S01 +## Tasks +- T01: Create src/api/routes.ts +- T02: Create src/api/handlers.ts +`; + const planB = `# Plan S02 +## Tasks +- T01: Create src/ui/components.ts +- T02: Create src/ui/styles.ts +`; + writeSlicePlan(base, "M001", "S01", planA); + writeSlicePlan(base, "M001", "S02", planB); + assert.equal(hasFileConflict(base, "M001", "S01", "S02"), false); + }); + + it("missing PLAN.md → conservative block (true)", () => { + // Only create one slice's plan + writeSlicePlan(base, "M001", "S01", "# Plan\n- T01: src/foo.ts"); + // S02 has no plan at all + assert.equal(hasFileConflict(base, "M001", "S01", "S02"), true); + }); + + it("one slice empty plan → allowed (false)", () => { + writeSlicePlan(base, "M001", "S01", "# Plan S01\n## Tasks\n- T01: Create src/foo.ts"); + writeSlicePlan(base, "M001", "S02", "# Plan S02\n## Tasks\n(no tasks yet)"); + assert.equal(hasFileConflict(base, "M001", "S01", "S02"), false); + }); +}); diff --git a/src/resources/extensions/gsd/tests/slice-parallel-eligibility.test.ts b/src/resources/extensions/gsd/tests/slice-parallel-eligibility.test.ts new file mode 100644 index 000000000..9beded51e --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-parallel-eligibility.test.ts @@ -0,0 +1,95 @@ +/** + * Tests for slice-level parallel eligibility. + * Verifies getEligibleSlices() correctly determines which slices + * can run in parallel based on dependency satisfaction. + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +import { getEligibleSlices } from "../slice-parallel-eligibility.js"; + +describe("getEligibleSlices", () => { + it("diamond DAG: S01 done, S02 depends:[S01], S03 depends:[S01] → both eligible", () => { + const slices = [ + { id: "S01", done: true, depends: [] }, + { id: "S02", done: false, depends: ["S01"] }, + { id: "S03", done: false, depends: ["S01"] }, + ]; + const completed = new Set(["S01"]); + const result = getEligibleSlices(slices, completed); + const ids = result.map(s => s.id); + assert.deepStrictEqual(ids.sort(), ["S02", "S03"]); + }); + + it("linear chain: S01→S02→S03, only S01 done → only S02 eligible", () => { + const slices = [ + { id: "S01", done: true, depends: [] }, + { id: "S02", done: false, depends: ["S01"] }, + { id: "S03", done: false, depends: ["S02"] }, + ]; + const completed = new Set(["S01"]); + const result = getEligibleSlices(slices, completed); + assert.equal(result.length, 1); + assert.equal(result[0].id, "S02"); + }); + + it("no deps declared: S01 done, S02 no deps, S03 no deps → only S02 eligible (positional fallback)", () => { + const slices = [ + { id: "S01", done: true, depends: [] }, + { id: "S02", done: false, depends: [] }, + { id: "S03", done: false, depends: [] }, + ]; + const completed = new Set(["S01"]); + const result = getEligibleSlices(slices, completed); + // Positional fallback: when no deps declared, only the first non-done slice + // after all positionally-earlier slices are done is eligible + assert.equal(result.length, 1); + assert.equal(result[0].id, "S02"); + }); + + it("all done: empty result", () => { + const slices = [ + { id: "S01", done: true, depends: [] }, + { id: "S02", done: true, depends: ["S01"] }, + { id: "S03", done: true, depends: ["S02"] }, + ]; + const completed = new Set(["S01", "S02", "S03"]); + const result = getEligibleSlices(slices, completed); + assert.equal(result.length, 0); + }); + + it("empty input: empty result", () => { + const result = getEligibleSlices([], new Set()); + assert.equal(result.length, 0); + }); + + it("mixed deps and no-deps: only dep-satisfied slices with explicit deps are eligible alongside positional", () => { + const slices = [ + { id: "S01", done: true, depends: [] }, + { id: "S02", done: false, depends: ["S01"] }, // explicit dep satisfied + { id: "S03", done: false, depends: [] }, // no deps, positional fallback + { id: "S04", done: false, depends: ["S01"] }, // explicit dep satisfied + ]; + const completed = new Set(["S01"]); + const result = getEligibleSlices(slices, completed); + const ids = result.map(s => s.id); + // S02 and S04 have explicit deps satisfied; S03 has no deps but + // positionally S02 (before it) is not done, so S03 is blocked by positional rule + assert.ok(ids.includes("S02"), "S02 should be eligible (dep on S01 satisfied)"); + assert.ok(ids.includes("S04"), "S04 should be eligible (dep on S01 satisfied)"); + }); + + it("unsatisfied dependency blocks slice", () => { + const slices = [ + { id: "S01", done: false, depends: [] }, + { id: "S02", done: false, depends: ["S01"] }, + ]; + const completed = new Set(); + const result = getEligibleSlices(slices, completed); + // S01 has no deps and is first → eligible by positional + // S02 depends on S01 which is not completed → blocked + assert.equal(result.length, 1); + assert.equal(result[0].id, "S01"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/slice-parallel-orchestrator.test.ts b/src/resources/extensions/gsd/tests/slice-parallel-orchestrator.test.ts new file mode 100644 index 000000000..8592f2c39 --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-parallel-orchestrator.test.ts @@ -0,0 +1,83 @@ +/** + * Structural tests for slice-level parallel orchestrator. + * Verifies the orchestrator module exists and has the correct shape, + * env var usage, and preference gating. + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const gsdDir = join(__dirname, ".."); + +describe("slice-parallel-orchestrator structural tests", () => { + it("orchestrator uses GSD_SLICE_LOCK env var", () => { + const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8"); + assert.ok( + source.includes("GSD_SLICE_LOCK"), + "Orchestrator must use GSD_SLICE_LOCK env var to isolate slice workers", + ); + }); + + it("orchestrator sets GSD_PARALLEL_WORKER=1 to prevent nesting", () => { + const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8"); + assert.ok( + source.includes("GSD_PARALLEL_WORKER"), + "Orchestrator must set GSD_PARALLEL_WORKER to prevent nested parallel", + ); + }); + + it("maxWorkers default is 2", () => { + const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8"); + // Check that default max workers is 2 (in opts.maxWorkers ?? 2 or similar) + assert.ok( + source.includes("maxWorkers") && source.includes("2"), + "Default maxWorkers should be 2", + ); + }); + + it("orchestrator imports GSD_MILESTONE_LOCK for milestone isolation", () => { + const source = readFileSync(join(gsdDir, "slice-parallel-orchestrator.ts"), "utf-8"); + assert.ok( + source.includes("GSD_MILESTONE_LOCK"), + "Orchestrator must also pass GSD_MILESTONE_LOCK for milestone context", + ); + }); +}); + +describe("slice_parallel preference gating", () => { + it("preferences-types.ts includes slice_parallel in interface", () => { + const source = readFileSync(join(gsdDir, "preferences-types.ts"), "utf-8"); + assert.ok( + source.includes("slice_parallel"), + "GSDPreferences should have slice_parallel field", + ); + }); + + it("slice_parallel is in KNOWN_PREFERENCE_KEYS", () => { + const source = readFileSync(join(gsdDir, "preferences-types.ts"), "utf-8"); + assert.ok( + source.includes('"slice_parallel"'), + 'KNOWN_PREFERENCE_KEYS should include "slice_parallel"', + ); + }); + + it("state.ts checks GSD_SLICE_LOCK for slice isolation", () => { + const source = readFileSync(join(gsdDir, "state.ts"), "utf-8"); + assert.ok( + source.includes("GSD_SLICE_LOCK"), + "State derivation should check GSD_SLICE_LOCK for slice-level parallel isolation", + ); + }); + + it("auto.ts imports slice parallel orchestrator when enabled", () => { + const source = readFileSync(join(gsdDir, "auto.ts"), "utf-8"); + assert.ok( + source.includes("slice_parallel") || source.includes("slice-parallel"), + "auto.ts should reference slice_parallel for dispatch gating", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/slice-sequence-insert.test.ts b/src/resources/extensions/gsd/tests/slice-sequence-insert.test.ts new file mode 100644 index 000000000..e041811aa --- /dev/null +++ b/src/resources/extensions/gsd/tests/slice-sequence-insert.test.ts @@ -0,0 +1,51 @@ +/** + * Regression test for #3697 — set slice sequence on insert + * + * All three insertSlice call sites must pass a sequence value so slices + * are ordered correctly instead of defaulting to 0. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const planMilestoneSrc = readFileSync( + join(__dirname, '..', 'tools', 'plan-milestone.ts'), + 'utf-8', +); +const reassessRoadmapSrc = readFileSync( + join(__dirname, '..', 'tools', 'reassess-roadmap.ts'), + 'utf-8', +); +const mdImporterSrc = readFileSync( + join(__dirname, '..', 'md-importer.ts'), + 'utf-8', +); + +describe('slice sequence on insert (#3697)', () => { + test('plan-milestone.ts passes sequence to insertSlice', () => { + assert.match(planMilestoneSrc, /insertSlice\(/, + 'plan-milestone.ts should call insertSlice'); + assert.match(planMilestoneSrc, /sequence:\s*i\s*\+\s*1/, + 'plan-milestone.ts should pass sequence: i + 1'); + }); + + test('reassess-roadmap.ts passes sequence to insertSlice', () => { + assert.match(reassessRoadmapSrc, /insertSlice\(/, + 'reassess-roadmap.ts should call insertSlice'); + assert.match(reassessRoadmapSrc, /sequence:\s*existingCount\s*\+\s*i\s*\+\s*1/, + 'reassess-roadmap.ts should pass sequence: existingCount + i + 1'); + }); + + test('md-importer.ts passes sequence to insertSlice', () => { + assert.match(mdImporterSrc, /insertSlice\(/, + 'md-importer.ts should call insertSlice'); + assert.match(mdImporterSrc, /sequence:\s*si\s*\+\s*1/, + 'md-importer.ts should pass sequence: si + 1'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/smart-entry-complete.test.ts b/src/resources/extensions/gsd/tests/smart-entry-complete.test.ts index 6abb0e8e6..14a111479 100644 --- a/src/resources/extensions/gsd/tests/smart-entry-complete.test.ts +++ b/src/resources/extensions/gsd/tests/smart-entry-complete.test.ts @@ -6,7 +6,7 @@ import { tmpdir } from "node:os"; const { deriveState } = await import("../state.js"); -test("deriveState reports complete when all milestone slices are done", async () => { +test("deriveState reports the last completed milestone when all milestone slices are done", async () => { const base = mkdtempSync(join(tmpdir(), "gsd-smart-entry-complete-")); try { @@ -31,7 +31,7 @@ test("deriveState reports complete when all milestone slices are done", async () const state = await deriveState(base); assert.equal(state.phase, "complete"); - assert.equal(state.activeMilestone?.id, "M001"); + assert.equal(state.lastCompletedMilestone?.id, "M001"); } finally { rmSync(base, { recursive: true, force: true }); } @@ -49,5 +49,5 @@ test("guided-flow complete branch offers a chooser for next milestone or status" assert.match(branchChunk, /showNextAction\(/, "complete branch should present a chooser"); assert.match(branchChunk, /findMilestoneIds\(basePath\)/, "complete branch should compute the next milestone id"); assert.match(branchChunk, /nextMilestoneId(?:Reserved)?\(milestoneIds, uniqueMilestoneIds\)/, "complete branch should derive the next milestone id"); - assert.match(branchChunk, /dispatchWorkflow\(pi, buildDiscussPrompt\(/, "complete branch should dispatch the discuss prompt"); + assert.match(branchChunk, /dispatchWorkflow\(pi, await prepareAndBuildDiscussPrompt\(/, "complete branch should dispatch the prepared discuss prompt"); }); diff --git a/src/resources/extensions/gsd/tests/stale-lockfile-recovery.test.ts b/src/resources/extensions/gsd/tests/stale-lockfile-recovery.test.ts new file mode 100644 index 000000000..c7a4ab2ab --- /dev/null +++ b/src/resources/extensions/gsd/tests/stale-lockfile-recovery.test.ts @@ -0,0 +1,36 @@ +/** + * stale-lockfile-recovery.test.ts — #3668 + * + * Verify that session-lock.ts contains pre-flight stale lock cleanup logic + * that removes orphaned lock directories when the owning PID is dead, + * preventing the 30-min stale window from blocking /gsd after crashes. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const sourceFile = join(__dirname, "..", "session-lock.ts"); + +describe("stale lockfile auto-recovery (#3668)", () => { + const source = readFileSync(sourceFile, "utf-8"); + + test("checks for orphan lock with isPidAlive", () => { + assert.match(source, /isPidAlive\(existingData\.pid\)/); + }); + + test("removes stale lock directory with rmSync", () => { + assert.match(source, /rmSync\(lockDir,\s*\{\s*recursive:\s*true/); + }); + + test("references issue #3218 in pre-flight cleanup comment", () => { + assert.match(source, /#3218.*Pre-flight stale lock cleanup/); + }); + + test("provides actionable rm -rf workaround in error message", () => { + assert.match(source, /rm\s+-rf/); + }); +}); diff --git a/src/resources/extensions/gsd/tests/stale-queued-milestone.test.ts b/src/resources/extensions/gsd/tests/stale-queued-milestone.test.ts new file mode 100644 index 000000000..5d99b961e --- /dev/null +++ b/src/resources/extensions/gsd/tests/stale-queued-milestone.test.ts @@ -0,0 +1,147 @@ +/** + * Regression test for #3470: DB-backed active milestone selection must not + * prefer a stale queued shell over the real active milestone. + * + * Scenario: M068 is a queued placeholder (DB row, no files, no slices). + * M070 is the real active milestone (context, roadmap, slices, tasks). + * deriveStateFromDb() must select M070 as active, not M068. + */ + +import { describe, test, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { deriveStateFromDb, invalidateStateCache } from "../state.ts"; +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, +} from "../gsd-db.ts"; + +function createFixtureBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-stale-milestone-")); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + return base; +} + +function writeFile(base: string, relativePath: string, content: string): void { + const full = join(base, ".gsd", relativePath); + mkdirSync(join(full, ".."), { recursive: true }); + writeFileSync(full, content); +} + +describe("stale queued milestone selection (#3470)", () => { + let base: string; + + afterEach(() => { + closeDatabase(); + if (base) rmSync(base, { recursive: true, force: true }); + }); + + test("queued shell with no content does not block real active milestone", async () => { + base = createFixtureBase(); + openDatabase(":memory:"); + + // M068: queued shell — DB row exists, no files, no slices + insertMilestone({ id: "M068", title: "Queued Shell", status: "queued" }); + + // M070: real active milestone — context, roadmap, slices, tasks + insertMilestone({ id: "M070", title: "Real Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M070", title: "Slice One", status: "active", risk: "low", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M070", title: "Task One", status: "pending" }); + + writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Real Active\n\nThis is the real milestone."); + writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070: Real Active\n\n## Slices\n\n- [ ] **S01: Slice One**"); + writeFile(base, "milestones/M070/slices/S01/S01-PLAN.md", "# S01: Slice One\n\n## Tasks\n\n- [ ] **T01: Task One**"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.activeMilestone?.id, "M070", "Active milestone must be M070, not queued shell M068"); + + // M068 should appear as pending in registry, not active + const m068Entry = state.registry.find((e: any) => e.id === "M068"); + assert.ok(m068Entry, "M068 should still appear in registry"); + assert.equal(m068Entry!.status, "pending", "M068 should be pending, not active"); + + // M070 should be active in registry + const m070Entry = state.registry.find((e: any) => e.id === "M070"); + assert.ok(m070Entry, "M070 should appear in registry"); + assert.equal(m070Entry!.status, "active", "M070 should be active in registry"); + }); + + test("queued milestone WITH context file can still be selected as active", async () => { + base = createFixtureBase(); + openDatabase(":memory:"); + + // M068: queued but has context (discussion started) — should be activatable + insertMilestone({ id: "M068", title: "Queued With Context", status: "queued" }); + writeFile(base, "milestones/M068/M068-CONTEXT.md", "# M068: Queued With Context\n\nDiscussion started."); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.activeMilestone?.id, "M068", "Queued milestone with context should become active"); + }); + + test("queued milestone WITH context-draft can still be selected as active", async () => { + base = createFixtureBase(); + openDatabase(":memory:"); + + // M068: queued but has draft (discussion in progress) + insertMilestone({ id: "M068", title: "Queued With Draft", status: "queued" }); + writeFile(base, "milestones/M068/M068-CONTEXT-DRAFT.md", "# M068: Queued With Draft\n\nDraft in progress."); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.activeMilestone?.id, "M068", "Queued milestone with draft should become active"); + }); + + test("queued milestone WITH slices can still be selected as active", async () => { + base = createFixtureBase(); + openDatabase(":memory:"); + + // M068: queued but has slices (planning started) + insertMilestone({ id: "M068", title: "Queued With Slices", status: "queued" }); + insertSlice({ id: "S01", milestoneId: "M068", title: "Slice One", status: "pending", risk: "low", depends: [] }); + writeFile(base, "milestones/M068/M068-ROADMAP.md", "# M068\n\n## Slices\n\n- [ ] **S01: Slice One**"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.activeMilestone?.id, "M068", "Queued milestone with slices should become active"); + }); + + test("multiple queued shells all skipped in favor of real active", async () => { + base = createFixtureBase(); + openDatabase(":memory:"); + + // Three queued shells before the real milestone + insertMilestone({ id: "M065", title: "Shell 1", status: "queued" }); + insertMilestone({ id: "M066", title: "Shell 2", status: "queued" }); + insertMilestone({ id: "M068", title: "Shell 3", status: "queued" }); + + // M070: real active + insertMilestone({ id: "M070", title: "Real Active", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M070", title: "Slice One", status: "active", risk: "low", depends: [] }); + writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Real Active"); + writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070\n\n## Slices\n\n- [ ] **S01: Slice One**"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.activeMilestone?.id, "M070", "Must skip all queued shells to reach M070"); + + // All shells should be pending + for (const id of ["M065", "M066", "M068"]) { + const entry = state.registry.find((e: any) => e.id === id); + assert.ok(entry, `${id} should be in registry`); + assert.equal(entry!.status, "pending", `${id} should be pending, not active`); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/stale-worktree-cwd.test.ts b/src/resources/extensions/gsd/tests/stale-worktree-cwd.test.ts index 163b0a804..def9d7107 100644 --- a/src/resources/extensions/gsd/tests/stale-worktree-cwd.test.ts +++ b/src/resources/extensions/gsd/tests/stale-worktree-cwd.test.ts @@ -17,6 +17,8 @@ import { teardownAutoWorktree, mergeMilestoneToMain, } from "../auto-worktree.ts"; +import { _resetServiceCache } from "../worktree.ts"; +import { _clearGsdRootCache } from "../paths.ts"; function run(command: string, cwd: string): string { return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); @@ -62,6 +64,13 @@ test("mergeMilestoneToMain restores cwd to project root", () => { const savedCwd = process.cwd(); let tempDir = ""; + // Isolate from user's global preferences (which may have git.main_branch set) + const originalHome = process.env.HOME; + const fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-fake-home-"))); + process.env.HOME = fakeHome; + _clearGsdRootCache(); + _resetServiceCache(); + try { tempDir = createTempRepo(); @@ -97,9 +106,13 @@ test("mergeMilestoneToMain restores cwd to project root", () => { assert.ok(!existsSync(wtPath), "worktree directory removed after merge"); } finally { process.chdir(savedCwd); + process.env.HOME = originalHome; + _clearGsdRootCache(); + _resetServiceCache(); if (tempDir && existsSync(tempDir)) { rmSync(tempDir, { recursive: true, force: true }); } + rmSync(fakeHome, { recursive: true, force: true }); } }); diff --git a/src/resources/extensions/gsd/tests/stash-pop-gsd-conflict.test.ts b/src/resources/extensions/gsd/tests/stash-pop-gsd-conflict.test.ts index 89ad125ae..f295c8f0f 100644 --- a/src/resources/extensions/gsd/tests/stash-pop-gsd-conflict.test.ts +++ b/src/resources/extensions/gsd/tests/stash-pop-gsd-conflict.test.ts @@ -15,6 +15,27 @@ import { tmpdir } from "node:os"; import { execSync } from "node:child_process"; import { createAutoWorktree, mergeMilestoneToMain } from "../auto-worktree.ts"; +import { _resetServiceCache } from "../worktree.ts"; +import { _clearGsdRootCache } from "../paths.ts"; + +// Isolate from user's global preferences (which may have git.main_branch set) +let originalHome: string | undefined; +let fakeHome: string; + +test.before(() => { + originalHome = process.env.HOME; + fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-fake-home-"))); + process.env.HOME = fakeHome; + _clearGsdRootCache(); + _resetServiceCache(); +}); + +test.after(() => { + process.env.HOME = originalHome; + _clearGsdRootCache(); + _resetServiceCache(); + rmSync(fakeHome, { recursive: true, force: true }); +}); function run(cmd: string, cwd: string): string { return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); diff --git a/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts b/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts new file mode 100644 index 000000000..ad4591908 --- /dev/null +++ b/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts @@ -0,0 +1,326 @@ +/** + * stash-queued-context-files.test.ts — Regression test for #2505. + * + * When mergeMilestoneToMain runs `git stash push --include-untracked`, + * untracked `.gsd/milestones/M/` directories created by `/gsd queue` + * are swept into the stash. If stash pop fails (conflict on tracked files), + * the queued milestone CONTEXT files are permanently lost. + * + * The fix: drop `--include-untracked` from the stash push, since the stash + * only needs to handle tracked dirty files. Untracked `.gsd/` files are + * already handled separately by clearProjectRootStateFiles. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + rmSync, + existsSync, + readFileSync, + realpathSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execSync } from "node:child_process"; + +import { createAutoWorktree, mergeMilestoneToMain } from "../auto-worktree.ts"; +import { _resetServiceCache } from "../worktree.ts"; +import { _clearGsdRootCache } from "../paths.ts"; + +// Isolate from user's global preferences (which may have git.main_branch set) +let originalHome: string | undefined; +let fakeHome: string; + +test.before(() => { + originalHome = process.env.HOME; + fakeHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-fake-home-"))); + process.env.HOME = fakeHome; + _clearGsdRootCache(); + _resetServiceCache(); +}); + +test.after(() => { + process.env.HOME = originalHome; + _clearGsdRootCache(); + _resetServiceCache(); + rmSync(fakeHome, { recursive: true, force: true }); +}); + +function run(cmd: string, cwd: string): string { + return execSync(cmd, { + cwd, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); +} + +function createTempRepo(): string { + const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-ctx-stash-test-"))); + run("git init", dir); + run("git config user.email test@test.com", dir); + run("git config user.name Test", dir); + writeFileSync(join(dir, "README.md"), "# test\n"); + mkdirSync(join(dir, ".gsd"), { recursive: true }); + writeFileSync(join(dir, ".gsd", "STATE.md"), "version: 1\n"); + // In projects with tracked .gsd/ files (hasGitTrackedGsdFiles=true), + // .gsd is NOT added to .gitignore. This means untracked files under + // .gsd/ are visible to --include-untracked and get swept into the + // stash, destroying queued milestone CONTEXT files (#2505). + run("git add -f .gsd/STATE.md", dir); + run("git add .", dir); + run("git commit -m init", dir); + run("git branch -M main", dir); + return dir; +} + +function makeRoadmap( + milestoneId: string, + title: string, + slices: Array<{ id: string; title: string }>, +): string { + const sliceLines = slices + .map((s) => `- [x] **${s.id}: ${s.title}**`) + .join("\n"); + return `# ${milestoneId}: ${title}\n\n## Slices\n${sliceLines}\n`; +} + +/** + * Standalone test proving that --include-untracked sweeps queued + * milestone CONTEXT files into the git stash. This is a direct + * git-level test, not going through mergeMilestoneToMain. + */ +test("#2505: git stash --include-untracked sweeps queued CONTEXT files (demonstrates the bug)", () => { + const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-stash-bug-demo-"))); + try { + run("git init", dir); + run("git config user.email test@test.com", dir); + run("git config user.name Test", dir); + writeFileSync(join(dir, "README.md"), "# test\n"); + mkdirSync(join(dir, ".gsd"), { recursive: true }); + writeFileSync(join(dir, ".gsd", "STATE.md"), "version: 1\n"); + run("git add -f .gsd/STATE.md", dir); + run("git add .", dir); + run("git commit -m init", dir); + + // Create queued milestone CONTEXT files (untracked, not gitignored) + const m013Dir = join(dir, ".gsd", "milestones", "M013"); + mkdirSync(m013Dir, { recursive: true }); + writeFileSync( + join(m013Dir, "M013-CONTEXT.md"), + "# M013: Login Page Redesign\n", + ); + + // Dirty a tracked file + writeFileSync(join(dir, "README.md"), "# test\n\nDirty.\n"); + + // Verify the CONTEXT file is untracked + const status = run("git status --porcelain", dir); + assert.ok(status.includes("?? .gsd/milestones/"), "precondition: M013 dir is untracked"); + + // Stash WITH --include-untracked (the bug) + run('git stash push --include-untracked -m "test stash"', dir); + + // BUG: the queued CONTEXT file was swept into the stash + assert.ok( + !existsSync(join(m013Dir, "M013-CONTEXT.md")), + "BUG CONFIRMED: --include-untracked swept CONTEXT file into stash", + ); + + // Stash WITHOUT --include-untracked (the fix) + run("git stash pop", dir); + + // Recreate the scenario + mkdirSync(m013Dir, { recursive: true }); + writeFileSync( + join(m013Dir, "M013-CONTEXT.md"), + "# M013: Login Page Redesign\n", + ); + writeFileSync(join(dir, "README.md"), "# test\n\nDirty again.\n"); + + // Stash WITHOUT --include-untracked (the fix) + run('git stash push -m "test stash no untracked"', dir); + + // FIX: the queued CONTEXT file stays on disk + assert.ok( + existsSync(join(m013Dir, "M013-CONTEXT.md")), + "FIX CONFIRMED: without --include-untracked, CONTEXT file stays on disk", + ); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("#2505: mergeMilestoneToMain preserves queued CONTEXT files (not swept into stash)", () => { + const repo = createTempRepo(); + try { + const wtPath = createAutoWorktree(repo, "M015"); + const normalizedPath = wtPath.replaceAll("\\", "/"); + const worktreeName = normalizedPath.split("/").pop() || "M015"; + const sliceBranch = `slice/${worktreeName}/S01`; + run(`git checkout -b "${sliceBranch}"`, wtPath); + writeFileSync(join(wtPath, "app.ts"), "export const app = true;\n"); + run("git add .", wtPath); + run('git commit -m "add app feature"', wtPath); + run("git checkout milestone/M015", wtPath); + run(`git merge --no-ff "${sliceBranch}" -m "merge S01"`, wtPath); + + // Simulate `/gsd queue` creating queued milestone CONTEXT files at the + // project root. These are untracked, and in repos with tracked .gsd/ + // files they are NOT gitignored. + const m013Dir = join(repo, ".gsd", "milestones", "M013"); + const m014Dir = join(repo, ".gsd", "milestones", "M014"); + mkdirSync(m013Dir, { recursive: true }); + mkdirSync(m014Dir, { recursive: true }); + writeFileSync( + join(m013Dir, "M013-CONTEXT.md"), + "# M013: Login Page Redesign\n\nQueued milestone context.\n", + ); + writeFileSync( + join(m014Dir, "M014-CONTEXT.md"), + "# M014: Dashboard Redesign\n\nQueued milestone context.\n", + ); + + // Dirty a tracked file to trigger the pre-merge stash + writeFileSync(join(repo, "README.md"), "# test\n\nDirty change.\n"); + + // Verify M013 is untracked (precondition) + const statusBefore = run("git status --porcelain", repo); + assert.ok( + statusBefore.includes("?? .gsd/milestones/"), + "M013 directory is untracked before merge (precondition)", + ); + + const roadmap = makeRoadmap("M015", "App Feature", [ + { id: "S01", title: "Feature" }, + ]); + + const result = mergeMilestoneToMain(repo, "M015", roadmap); + assert.ok( + result.commitMessage.includes("GSD-Milestone: M015"), + "merge should succeed", + ); + + // CRITICAL: Queued milestone CONTEXT files must still exist on disk. + // With --include-untracked, these files get swept into the stash + // during the merge and are only restored if stash pop succeeds. + // Without --include-untracked, they are never touched. + assert.ok( + existsSync(join(m013Dir, "M013-CONTEXT.md")), + "M013-CONTEXT.md must survive the merge (not swept into stash)", + ); + assert.ok( + existsSync(join(m014Dir, "M014-CONTEXT.md")), + "M014-CONTEXT.md must survive the merge (not swept into stash)", + ); + assert.ok( + readFileSync(join(m013Dir, "M013-CONTEXT.md"), "utf-8").includes("Login Page Redesign"), + "M013 context content preserved", + ); + assert.ok( + readFileSync(join(m014Dir, "M014-CONTEXT.md"), "utf-8").includes("Dashboard Redesign"), + "M014 context content preserved", + ); + + // Verify milestone code merged correctly + assert.ok(existsSync(join(repo, "app.ts")), "milestone code merged to main"); + + // Verify no stash entry remains that could contain queued files. + // If --include-untracked is removed, the stash (if needed) should + // pop cleanly since it only contains tracked files. + let stashList: string; + try { + stashList = run("git stash list", repo); + } catch { + stashList = ""; + } + // A leftover stash after merge is acceptable (pop conflict on tracked + // files), but it must NOT contain queued milestone files. + if (stashList) { + // Verify the stash does not contain queued milestone entries + try { + const stashDiff = run("git diff stash@{0}^3 --name-only 2>/dev/null || true", repo); + assert.ok( + !stashDiff.includes("M013-CONTEXT"), + "stash must not contain queued milestone M013 files", + ); + assert.ok( + !stashDiff.includes("M014-CONTEXT"), + "stash must not contain queued milestone M014 files", + ); + } catch { + // No untracked tree in stash — that's the expected outcome with the fix + } + } + } finally { + rmSync(repo, { recursive: true, force: true }); + } +}); + +test("#2505: back-to-back merges preserve queued CONTEXT files", () => { + const repo = createTempRepo(); + try { + // ── First milestone: M015 ── + const wt1 = createAutoWorktree(repo, "M015"); + const wt1Name = wt1.replaceAll("\\", "/").split("/").pop() || "M015"; + const slice1 = `slice/${wt1Name}/S01`; + run(`git checkout -b "${slice1}"`, wt1); + writeFileSync(join(wt1, "feature1.ts"), "export const f1 = true;\n"); + run("git add .", wt1); + run('git commit -m "feature 1"', wt1); + run("git checkout milestone/M015", wt1); + run(`git merge --no-ff "${slice1}" -m "merge S01"`, wt1); + + // Create queued milestone CONTEXT file + const m013Dir = join(repo, ".gsd", "milestones", "M013"); + mkdirSync(m013Dir, { recursive: true }); + writeFileSync( + join(m013Dir, "M013-CONTEXT.md"), + "# M013: Login Page Redesign\n\nQueued milestone context.\n", + ); + + // Dirty tracked file to trigger stash + writeFileSync(join(repo, "README.md"), "# test\n\nDirty for M015.\n"); + + mergeMilestoneToMain(repo, "M015", makeRoadmap("M015", "Feature 1", [ + { id: "S01", title: "Feature 1" }, + ])); + + assert.ok( + existsSync(join(m013Dir, "M013-CONTEXT.md")), + "M013-CONTEXT.md survives first merge", + ); + + // ── Second milestone: M016 ── + const wt2 = createAutoWorktree(repo, "M016"); + const wt2Name = wt2.replaceAll("\\", "/").split("/").pop() || "M016"; + const slice2 = `slice/${wt2Name}/S01`; + run(`git checkout -b "${slice2}"`, wt2); + writeFileSync(join(wt2, "feature2.ts"), "export const f2 = true;\n"); + run("git add .", wt2); + run('git commit -m "feature 2"', wt2); + run("git checkout milestone/M016", wt2); + run(`git merge --no-ff "${slice2}" -m "merge S01"`, wt2); + + // Dirty tracked file again + writeFileSync(join(repo, "README.md"), "# test\n\nDirty for M016.\n"); + + mergeMilestoneToMain(repo, "M016", makeRoadmap("M016", "Feature 2", [ + { id: "S01", title: "Feature 2" }, + ])); + + // After two consecutive merges, queued M013 CONTEXT must still exist + assert.ok( + existsSync(join(m013Dir, "M013-CONTEXT.md")), + "M013-CONTEXT.md must survive two consecutive milestone merges", + ); + assert.ok( + readFileSync(join(m013Dir, "M013-CONTEXT.md"), "utf-8").includes("Login Page Redesign"), + "M013 context content preserved after back-to-back merges", + ); + } finally { + rmSync(repo, { recursive: true, force: true }); + } +}); diff --git a/src/resources/extensions/gsd/tests/state-corruption-2945.test.ts b/src/resources/extensions/gsd/tests/state-corruption-2945.test.ts new file mode 100644 index 000000000..a7da901bc --- /dev/null +++ b/src/resources/extensions/gsd/tests/state-corruption-2945.test.ts @@ -0,0 +1,405 @@ +/** + * Regression tests for issue #2945: State corruption in milestone/slice completion workflow. + * + * Covers all 4 sub-bugs: + * Bug 1: ROADMAP corrupted by inline UAT content in table rows + * Bug 2: complete-milestone event replay bypasses task validation + * Bug 3: Worktree directory not cleaned up after mergeAndExit + * Bug 4: Quality gate records not written by validate-milestone + */ + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, + getMilestoneSlices, + getSliceTasks, + getGateResults, +} from "../gsd-db.ts"; +import { renderRoadmapContent } from "../workflow-projections.ts"; +import type { MilestoneRow, SliceRow } from "../gsd-db.ts"; +import type { AutoSession } from "../auto/session.ts"; + +// ─── Fixture helpers ──────────────────────────────────────────────────────── + +function tempDbPath(): string { + const dir = mkdtempSync(join(tmpdir(), "gsd-2945-")); + return join(dir, "test.db"); +} + +function cleanupDb(dbPath: string): void { + closeDatabase(); + try { + const dir = join(dbPath, ".."); + rmSync(dir, { recursive: true, force: true }); + } catch { + // best effort + } +} + +function createTempProject(): { basePath: string } { + const basePath = mkdtempSync(join(tmpdir(), "gsd-2945-project-")); + mkdirSync(join(basePath, ".gsd", "milestones", "M001"), { recursive: true }); + return { basePath }; +} + +function makeMilestoneRow(overrides: Partial = {}): MilestoneRow { + return { + id: "M001", + title: "Test Milestone", + vision: "Build a test milestone", + status: "active", + depends_on: [], + created_at: new Date().toISOString(), + completed_at: null, + success_criteria: ["SC1", "SC2"], + key_risks: [], + proof_strategy: [], + verification_contract: "", + verification_integration: "", + verification_operational: "", + verification_uat: "", + definition_of_done: [], + requirement_coverage: "", + boundary_map_markdown: "", + ...overrides, + }; +} + +function makeSliceRow(id: string, overrides: Partial = {}): SliceRow { + return { + id, + milestone_id: "M001", + title: `Slice ${id}`, + goal: `Goal for ${id}`, + demo: `Demo for ${id}`, + risk: "medium", + status: "pending", + sequence: parseInt(id.replace("S", ""), 10) || 0, + depends: [], + created_at: new Date().toISOString(), + completed_at: null, + full_summary_md: "", + full_uat_md: "", + success_criteria: "", + proof_level: "", + integration_closure: "", + observability_impact: "", + replan_triggered_at: null, + ...overrides, + }; +} + +// ═══════════════════════════════════════════════════════════════════════════════ +// Bug 1: ROADMAP corrupted by inline UAT content +// ═══════════════════════════════════════════════════════════════════════════════ + +describe("#2945 Bug 1: ROADMAP table cell corruption by UAT content", () => { + + test("renderRoadmapContent does NOT inject full_uat_md into table rows when demo is empty", () => { + const milestone = makeMilestoneRow(); + + const longUatContent = `### Preconditions +- Database initialized +- Service running + +### Steps +1. Open the application +2. Navigate to settings +3. Enable dark mode + +### Expected +- Theme changes to dark +- All components update`; + + const slices: SliceRow[] = [ + makeSliceRow("S01", { + status: "complete", + demo: "", // empty demo + full_uat_md: longUatContent, // full UAT content in DB + }), + makeSliceRow("S02", { + status: "pending", + demo: "Advanced stuff works", + }), + ]; + + const content = renderRoadmapContent(milestone, slices); + + // The roadmap table row for S01 should NOT contain UAT content + assert.ok( + !content.includes("Preconditions"), + "roadmap table row must not contain UAT preconditions", + ); + assert.ok( + !content.includes("Navigate to settings"), + "roadmap table row must not contain UAT steps", + ); + + // Each table row should be a reasonable length (under 200 chars) + const lines = content.split("\n"); + const s01Row = lines.find(l => l.includes("| S01 |")); + assert.ok(s01Row, "S01 should appear as a table row"); + assert.ok( + s01Row!.length < 200, + `S01 row should be under 200 chars, got ${s01Row!.length}: ${s01Row!.slice(0, 100)}...`, + ); + + // S02 should still be visible + assert.ok(content.includes("| S02 |"), "S02 must still be visible in roadmap table"); + }); + + test("renderRoadmapContent uses 'TBD' fallback when demo is empty, not full_uat_md", () => { + const milestone = makeMilestoneRow(); + const slices: SliceRow[] = [ + makeSliceRow("S01", { demo: "", full_uat_md: "Long UAT content here" }), + ]; + + const content = renderRoadmapContent(milestone, slices); + assert.ok( + content.includes("TBD"), + "empty demo should fallback to 'TBD', not full_uat_md", + ); + assert.ok( + !content.includes("Long UAT content here"), + "full_uat_md should never appear in roadmap table", + ); + }); + + test("renderRoadmapContent preserves demo field when present", () => { + const milestone = makeMilestoneRow(); + const slices: SliceRow[] = [ + makeSliceRow("S01", { demo: "Basic functionality works", full_uat_md: "Full UAT" }), + ]; + + const content = renderRoadmapContent(milestone, slices); + assert.ok( + content.includes("Basic functionality works"), + "demo field should be used when present", + ); + assert.ok( + !content.includes("Full UAT"), + "full_uat_md should not be used when demo is present", + ); + }); +}); + +// ═══════════════════════════════════════════════════════════════════════════════ +// Bug 2: complete-milestone event replay bypasses task validation +// ═══════════════════════════════════════════════════════════════════════════════ + +describe("#2945 Bug 2: workflow-reconcile bypasses task validation for complete_slice", () => { + let dbPath: string; + + beforeEach(() => { + dbPath = tempDbPath(); + openDatabase(dbPath); + }); + + afterEach(() => { + cleanupDb(dbPath); + }); + + test("replaySliceComplete must not mark slice done when tasks are pending", async () => { + // Set up: M001 with S01 that has 2 tasks, one pending + insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete", title: "Done task" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending", title: "Pending task" }); + + // Import and call replaySliceComplete directly + const { replaySliceComplete } = await import("../workflow-reconcile.ts"); + replaySliceComplete("M001", "S01", new Date().toISOString()); + + // The slice should NOT be marked done because T02 is still pending + const slices = getMilestoneSlices("M001"); + const s01 = slices.find(s => s.id === "S01"); + assert.ok(s01, "S01 should exist"); + assert.notStrictEqual( + s01!.status, + "done", + "replaySliceComplete must not mark slice as done when tasks are pending", + ); + assert.notStrictEqual( + s01!.status, + "complete", + "replaySliceComplete must not mark slice as complete when tasks are pending", + ); + }); + + test("replaySliceComplete marks slice done when all tasks are complete", async () => { + insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete", title: "Done task" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "done", title: "Also done" }); + + const { replaySliceComplete } = await import("../workflow-reconcile.ts"); + replaySliceComplete("M001", "S01", new Date().toISOString()); + + const slices = getMilestoneSlices("M001"); + const s01 = slices.find(s => s.id === "S01"); + assert.ok(s01, "S01 should exist"); + assert.strictEqual( + s01!.status, + "done", + "replaySliceComplete should mark slice as done when all tasks are complete", + ); + }); +}); + +// ═══════════════════════════════════════════════════════════════════════════════ +// Bug 3: Worktree directory not cleaned up after mergeAndExit +// ═══════════════════════════════════════════════════════════════════════════════ + +describe("#2945 Bug 3: mergeAndExit must teardown worktree after successful merge", () => { + + test("_mergeWorktreeMode calls teardownAutoWorktree after successful merge", async () => { + // Test the WorktreeResolver to verify teardown is called after merge. + // We use a mock-based approach since actual worktrees require a git repo. + let teardownCalled = false; + let teardownMilestoneId = ""; + + const mockSession = { + basePath: "/mock/worktree/M001", + originalBasePath: "/mock/project", + isolationDegraded: false, + gitService: {} as unknown, + } as unknown as AutoSession; + + const mockDeps = { + isInAutoWorktree: () => true, + shouldUseWorktreeIsolation: () => true, + getIsolationMode: () => "worktree" as const, + mergeMilestoneToMain: () => ({ pushed: false, codeFilesChanged: true }), + syncWorktreeStateBack: () => ({ synced: [] }), + teardownAutoWorktree: (basePath: string, mid: string) => { + teardownCalled = true; + teardownMilestoneId = mid; + }, + createAutoWorktree: () => "", + enterAutoWorktree: () => "", + getAutoWorktreePath: () => null, + autoCommitCurrentBranch: () => {}, + getCurrentBranch: () => "main", + autoWorktreeBranch: () => "gsd/M001", + resolveMilestoneFile: () => "/mock/roadmap.md", + readFileSync: () => "# Roadmap content", + GitServiceImpl: class {} as unknown as new (p: string, c: unknown) => unknown, + loadEffectiveGSDPreferences: () => undefined, + invalidateAllCaches: () => {}, + captureIntegrationBranch: () => {}, + }; + + // Import and create resolver + // We test the behavior contract: after a successful merge, teardown must be called + const { WorktreeResolver } = await import("../worktree-resolver.ts"); + const resolver = new WorktreeResolver(mockSession, mockDeps); + + const ctx = { notify: () => {} }; + resolver.mergeAndExit("M001", ctx); + + assert.ok( + teardownCalled, + "teardownAutoWorktree must be called after successful merge in worktree mode", + ); + assert.strictEqual( + teardownMilestoneId, + "M001", + "teardown must be called with the correct milestone ID", + ); + }); +}); + +// ═══════════════════════════════════════════════════════════════════════════════ +// Bug 4: Quality gate records not written by validate-milestone +// ═══════════════════════════════════════════════════════════════════════════════ + +describe("#2945 Bug 4: validate-milestone must persist quality_gates records", () => { + let dbPath: string; + let basePath: string; + + beforeEach(() => { + dbPath = tempDbPath(); + openDatabase(dbPath); + const proj = createTempProject(); + basePath = proj.basePath; + }); + + afterEach(() => { + cleanupDb(dbPath); + try { rmSync(basePath, { recursive: true, force: true }); } catch {} + }); + + test("handleValidateMilestone persists quality_gates records in DB", async () => { + // Set up milestone with slices + insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); + + const { handleValidateMilestone } = await import("../tools/validate-milestone.ts"); + + const result = await handleValidateMilestone({ + milestoneId: "M001", + verdict: "pass", + remediationRound: 0, + successCriteriaChecklist: "- [x] SC1 met\n- [x] SC2 met", + sliceDeliveryAudit: "All slices delivered", + crossSliceIntegration: "Integration verified", + requirementCoverage: "100% coverage", + verdictRationale: "All checks pass", + }, basePath); + + assert.ok(!("error" in result), `handler should succeed, got: ${JSON.stringify(result)}`); + + // Quality gate records should exist in DB for this milestone + // Use a wildcard slice_id since milestone-level gates use a sentinel + const adapter = (await import("../gsd-db.ts"))._getAdapter()!; + const gates = adapter.prepare( + "SELECT * FROM quality_gates WHERE milestone_id = 'M001'" + ).all(); + + assert.ok( + gates.length > 0, + `validate-milestone must persist quality_gates records in DB, found ${gates.length}`, + ); + }); + + test("handleValidateMilestone records verdict correctly in quality_gates", async () => { + insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); + + const { handleValidateMilestone } = await import("../tools/validate-milestone.ts"); + + await handleValidateMilestone({ + milestoneId: "M001", + verdict: "needs-remediation", + remediationRound: 1, + successCriteriaChecklist: "- [ ] SC1 not met", + sliceDeliveryAudit: "S01 incomplete", + crossSliceIntegration: "Not tested", + requirementCoverage: "50% coverage", + verdictRationale: "Needs work", + remediationPlan: "Fix S01", + }, basePath); + + const adapter = (await import("../gsd-db.ts"))._getAdapter()!; + const gates = adapter.prepare( + "SELECT * FROM quality_gates WHERE milestone_id = 'M001'" + ).all(); + + assert.ok(gates.length > 0, "quality_gates records must exist"); + + // At least one gate should have a non-empty verdict + const withVerdict = gates.filter((g: Record) => g["verdict"] && g["verdict"] !== ""); + assert.ok( + withVerdict.length > 0, + "at least one quality_gate should have a recorded verdict", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/state-derivation-parity.test.ts b/src/resources/extensions/gsd/tests/state-derivation-parity.test.ts new file mode 100644 index 000000000..ff1dd1695 --- /dev/null +++ b/src/resources/extensions/gsd/tests/state-derivation-parity.test.ts @@ -0,0 +1,257 @@ +// GSD State Machine Regression Tests — Completion Hierarchy & State Derivation (#3161) + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { deriveState, isGhostMilestone, invalidateStateCache } from "../state.ts"; + +// ─── Fixture Helpers ─────────────────────────────────────────────────────── + +function createFixtureBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-parity-test-")); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + rmSync(base, { recursive: true, force: true }); +} + +function writeMilestoneFile(base: string, mid: string, suffix: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-${suffix}.md`), content); +} + +function writeMilestoneValidation(base: string, mid: string, verdict: string = "pass"): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, `${mid}-VALIDATION.md`), + `---\nverdict: ${verdict}\nremediation_round: 0\n---\n\n# Validation\nValidated.`, + ); +} + +// ─── Setup / Teardown ────────────────────────────────────────────────────── + +beforeEach(() => { + invalidateStateCache(); +}); + +afterEach(() => { + invalidateStateCache(); +}); + +// ═══════════════════════════════════════════════════════════════════════════ +// Tests +// ═══════════════════════════════════════════════════════════════════════════ + +describe("state-derivation-parity", () => { + + // ─── Test 1: ghost milestone with only META.json ───────────────────────── + test("ghost milestone with only META.json is correctly detected", () => { + const base = createFixtureBase(); + try { + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + // Write only META.json — no CONTEXT, CONTEXT-DRAFT, ROADMAP, or SUMMARY + writeFileSync(join(dir, "META.json"), JSON.stringify({ id: "M001", createdAt: new Date().toISOString() })); + + assert.ok( + isGhostMilestone(base, "M001"), + "milestone with only META.json is a ghost", + ); + } finally { + cleanup(base); + } + }); + + // ─── Test 2: non-ghost milestone with CONTEXT is not ghost ─────────────── + test("non-ghost milestone with CONTEXT is not ghost", () => { + const base = createFixtureBase(); + try { + writeMilestoneFile(base, "M001", "CONTEXT", "# M001 Context\n\nThis milestone has real content."); + + assert.ok( + !isGhostMilestone(base, "M001"), + "milestone with CONTEXT.md is not a ghost", + ); + } finally { + cleanup(base); + } + }); + + // ─── Test 3: empty milestones dir derives pre-planning phase ───────────── + test("empty milestones dir derives pre-planning phase", async () => { + const base = createFixtureBase(); + try { + const state = await deriveState(base); + assert.equal(state.phase, "pre-planning", "empty milestones dir yields pre-planning phase"); + assert.equal(state.activeMilestone, null, "no active milestone for empty dir"); + assert.equal(state.activeSlice, null, "no active slice for empty dir"); + assert.deepEqual(state.registry, [], "registry is empty for empty dir"); + } finally { + cleanup(base); + } + }); + + // ─── Test 4: state includes blockers field for future blocked-phase detection ── + test("deriveState result always includes a defined phase and nextAction", async () => { + // Document that the state shape includes a `phase` string and `nextAction` string. + // Triggering "blocked" via filesystem alone requires circular dep setup which + // is outside the scope of these parity tests. Instead we verify the shape. + const base = createFixtureBase(); + try { + // Provide a milestone with a ROADMAP that has a single incomplete slice + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, "M001-ROADMAP.md"), + `# M001: Test\n\n**Vision:** Parity check.\n\n## Slices\n\n- [ ] **S01: First Slice** \`risk:low\` \`depends:[]\`\n > After this: First slice done.\n`, + ); + + const state = await deriveState(base); + + assert.ok(typeof state.phase === "string", "state.phase is a string"); + assert.ok(typeof state.nextAction === "string", "state.nextAction is a string"); + // The state object is the same shape regardless of phase — blockers would + // appear when the phase is "blocked". We document that the field may exist. + assert.ok("activeMilestone" in state, "state has activeMilestone field"); + assert.ok("registry" in state, "state has registry field"); + } finally { + cleanup(base); + } + }); + + // ─── Test 5: CONTEXT-DRAFT but no CONTEXT returns needs-discussion ──────── + test("deriveState with CONTEXT-DRAFT but no CONTEXT returns needs-discussion", async () => { + const base = createFixtureBase(); + try { + writeMilestoneFile( + base, + "M001", + "CONTEXT-DRAFT", + "# Draft Context\n\nSeed discussion material for M001.", + ); + + const state = await deriveState(base); + assert.equal( + state.phase, + "needs-discussion", + "CONTEXT-DRAFT with no CONTEXT yields needs-discussion phase", + ); + assert.equal(state.activeMilestone?.id, "M001", "active milestone is M001"); + assert.equal(state.activeSlice, null, "no active slice in needs-discussion phase"); + } finally { + cleanup(base); + } + }); + + // ─── Test 6: deriveState skips ghost milestones when finding active milestone ── + test("deriveState skips ghost milestones when finding active milestone", async () => { + const base = createFixtureBase(); + try { + // M001: ghost — just an empty directory + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + + // M002: has CONTEXT-DRAFT — should become active + writeMilestoneFile( + base, + "M002", + "CONTEXT-DRAFT", + "# Draft for M002\n\nThis is the real milestone.", + ); + + const state = await deriveState(base); + + // M001 is a ghost so it is skipped; M002 becomes the active milestone + assert.equal( + state.activeMilestone?.id, + "M002", + "ghost M001 is skipped; M002 is the active milestone", + ); + assert.equal( + state.phase, + "needs-discussion", + "phase is needs-discussion because M002 has only CONTEXT-DRAFT", + ); + } finally { + cleanup(base); + } + }); + + // ─── Bonus: isGhostMilestone returns true for fully empty directory ─────── + test("isGhostMilestone returns true for milestone directory with no files", () => { + const base = createFixtureBase(); + try { + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + // No files at all in the directory + assert.ok( + isGhostMilestone(base, "M001"), + "milestone directory with no files is a ghost", + ); + } finally { + cleanup(base); + } + }); + + // ─── Bonus: isGhostMilestone returns false when ROADMAP exists ──────────── + test("isGhostMilestone returns false when ROADMAP exists", () => { + const base = createFixtureBase(); + try { + writeMilestoneFile(base, "M001", "ROADMAP", "# M001\n\n## Slices\n\n- [ ] **S01: First** `risk:low` `depends:[]`\n > After this: done.\n"); + assert.ok( + !isGhostMilestone(base, "M001"), + "milestone with ROADMAP is not a ghost", + ); + } finally { + cleanup(base); + } + }); + + // ─── Bonus: isGhostMilestone returns false when CONTEXT-DRAFT exists ────── + test("isGhostMilestone returns false when CONTEXT-DRAFT exists", () => { + const base = createFixtureBase(); + try { + writeMilestoneFile(base, "M001", "CONTEXT-DRAFT", "# Draft\n\nSeed material."); + assert.ok( + !isGhostMilestone(base, "M001"), + "milestone with CONTEXT-DRAFT is not a ghost", + ); + } finally { + cleanup(base); + } + }); + + // ─── Bonus: multiple ghost milestones before a real one are all skipped ─── + test("deriveState skips multiple ghost milestones to find the first real one", async () => { + const base = createFixtureBase(); + try { + // M001 and M002: ghosts + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + mkdirSync(join(base, ".gsd", "milestones", "M002"), { recursive: true }); + + // M003: has CONTEXT-DRAFT — first real milestone + writeMilestoneFile(base, "M003", "CONTEXT-DRAFT", "# M003 Draft\n\nFirst substantive milestone."); + + const state = await deriveState(base); + + assert.equal( + state.activeMilestone?.id, + "M003", + "both ghost milestones skipped; M003 is active", + ); + assert.equal( + state.phase, + "needs-discussion", + "phase is needs-discussion for M003 with CONTEXT-DRAFT", + ); + } finally { + cleanup(base); + } + }); + +}); diff --git a/src/resources/extensions/gsd/tests/state-machine-full-walkthrough.test.ts b/src/resources/extensions/gsd/tests/state-machine-full-walkthrough.test.ts new file mode 100644 index 000000000..f1b66acb9 --- /dev/null +++ b/src/resources/extensions/gsd/tests/state-machine-full-walkthrough.test.ts @@ -0,0 +1,1627 @@ +// GSD State Machine — Comprehensive Phase-by-Phase Walkthrough Tests +// Verifies all 16 phases, reconciliation, edge cases, and cross-validation. + +import { describe, test, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + deriveState, + deriveStateFromDb, + isValidationTerminal, + isGhostMilestone, + invalidateStateCache, +} from "../state.ts"; +import { + openDatabase, + closeDatabase, + insertMilestone, + insertSlice, + insertTask, + updateTaskStatus, + getAllMilestones, + insertGateRow, + getPendingSliceGateCount, +} from "../gsd-db.ts"; +import { isClosedStatus } from "../status-guards.ts"; +import { clearPathCache } from "../paths.ts"; + +// ─── Fixture Helpers ───────────────────────────────────────────────────────── + +const tempDirs: string[] = []; + +function createFixtureBase(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-walkthrough-")); + mkdirSync(join(base, ".gsd", "milestones"), { recursive: true }); + tempDirs.push(base); + return base; +} + +afterEach(() => { + for (const dir of tempDirs.splice(0)) { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { /* best effort */ } + } + try { closeDatabase(); } catch { /* may not be open */ } +}); + +function writeContext(base: string, mid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-CONTEXT.md`), content); +} + +function writeContextDraft(base: string, mid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-CONTEXT-DRAFT.md`), content); +} + +function writeRoadmap(base: string, mid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-ROADMAP.md`), content); +} + +function writePlan(base: string, mid: string, sid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + const tasksDir = join(dir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(dir, `${sid}-PLAN.md`), content); + // Create stub task plan files so deriveState doesn't fall back to planning + const taskMatches = content.matchAll(/\*\*(T\d+):/g); + for (const m of taskMatches) { + const tid = m[1]; + writeFileSync(join(tasksDir, `${tid}-PLAN.md`), `# ${tid} Plan\n\nStub.\n`); + } +} + +function writeTaskSummary(base: string, mid: string, sid: string, tid: string): void { + const tasksDir = join(base, ".gsd", "milestones", mid, "slices", sid, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(tasksDir, `${tid}-SUMMARY.md`), [ + `# ${tid} Summary`, + "", + "Task completed successfully.", + ].join("\n")); +} + +function writeTaskSummaryWithBlocker(base: string, mid: string, sid: string, tid: string): void { + const tasksDir = join(base, ".gsd", "milestones", mid, "slices", sid, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(tasksDir, `${tid}-SUMMARY.md`), [ + "---", + "blocker_discovered: true", + "---", + "", + `# ${tid} Summary`, + "", + "Blocker found during execution.", + ].join("\n")); +} + +function writeSliceSummary(base: string, mid: string, sid: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${sid}-SUMMARY.md`), `# ${sid} Summary\n\nSlice done.\n`); +} + +function writeMilestoneSummary(base: string, mid: string): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-SUMMARY.md`), `# ${mid} Summary\n\nMilestone complete.\n`); +} + +function writeMilestoneValidation(base: string, mid: string, verdict: string = "pass"): void { + const dir = join(base, ".gsd", "milestones", mid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${mid}-VALIDATION.md`), [ + "---", + `verdict: ${verdict}`, + "remediation_round: 0", + "---", + "", + "# Validation", + "Validated.", + ].join("\n")); +} + +function writeReplanTrigger(base: string, mid: string, sid: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${sid}-REPLAN-TRIGGER.md`), "Triage replan triggered.\n"); +} + +function writeReplan(base: string, mid: string, sid: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${sid}-REPLAN.md`), "# Replan\n\nReplan completed.\n"); +} + +function writeContinue(base: string, mid: string, sid: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${sid}-CONTINUE.md`), [ + "---", + "milestone: " + mid, + "slice: " + sid, + "task: T01", + "status: interrupted", + "---", + "", + "# Continue", + "Resume from step 2.", + ].join("\n")); +} + +/** Standard roadmap with one incomplete slice */ +function standardRoadmap(): string { + return [ + "# M001: Test Milestone", + "", + "**Vision:** Test state machine.", + "", + "## Slices", + "", + "- [ ] **S01: First Slice** `risk:low` `depends:[]`", + " > After this: slice done.", + ].join("\n"); +} + +/** Roadmap with one done slice */ +function doneSliceRoadmap(): string { + return [ + "# M001: Test Milestone", + "", + "**Vision:** Test state machine.", + "", + "## Slices", + "", + "- [x] **S01: Done Slice** `risk:low` `depends:[]`", + " > After this: slice done.", + ].join("\n"); +} + +/** Standard plan with two incomplete tasks */ +function standardPlan(): string { + return [ + "# S01: First Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "- [ ] **T01: First Task** `est:10m`", + " First task description.", + "", + "- [ ] **T02: Second Task** `est:10m`", + " Second task description.", + ].join("\n"); +} + +/** Plan with all tasks done */ +function allDonePlan(): string { + return [ + "# S01: First Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "- [x] **T01: First Task** `est:10m`", + " First task done.", + "", + "- [x] **T02: Second Task** `est:10m`", + " Second task done.", + ].join("\n"); +} + +/** Plan with one done, one incomplete task */ +function partialDonePlan(): string { + return [ + "# S01: First Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "- [x] **T01: First Task** `est:10m`", + " First task done.", + "", + "- [ ] **T02: Second Task** `est:10m`", + " Second task pending.", + ].join("\n"); +} + +// ═══════════════════════════════════════════════════════════════════════════════ +// PHASE 1: pre-planning +// ═══════════════════════════════════════════════════════════════════════════════ + +describe("state-machine-full-walkthrough", () => { + + describe("Phase 1: pre-planning", () => { + test("empty milestones dir → pre-planning", async () => { + const base = createFixtureBase(); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "pre-planning"); + assert.equal(state.activeMilestone, null); + assert.equal(state.activeSlice, null); + assert.equal(state.activeTask, null); + assert.deepStrictEqual(state.registry, []); + }); + + test("milestone with CONTEXT but no ROADMAP → pre-planning", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "# M001: Test\n\nSome context."); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "pre-planning"); + assert.ok(state.activeMilestone !== null, "activeMilestone should be set"); + assert.equal(state.activeMilestone?.id, "M001"); + }); + + test("roadmap with zero slices → pre-planning (not validating-milestone)", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "# M001: Test\n\nContext."); + // Roadmap exists but has no slice entries + writeRoadmap(base, "M001", [ + "# M001: Test Milestone", + "", + "**Vision:** Test.", + "", + "## Slices", + "", + "No slices defined yet.", + ].join("\n")); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "pre-planning", "zero slices must NOT trigger validating-milestone (#2667)"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 2: needs-discussion + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 2: needs-discussion", () => { + test("CONTEXT-DRAFT exists, no CONTEXT → needs-discussion", async () => { + const base = createFixtureBase(); + writeContextDraft(base, "M001", "# M001: Draft\n\nDraft context."); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "needs-discussion"); + assert.ok(state.activeMilestone !== null); + assert.equal(state.activeMilestone?.id, "M001"); + }); + + test("both CONTEXT-DRAFT and CONTEXT exist → NOT needs-discussion", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "# M001: Real\n\nReal context."); + writeContextDraft(base, "M001", "# M001: Draft\n\nDraft context."); + invalidateStateCache(); + const state = await deriveState(base); + + assert.notEqual(state.phase, "needs-discussion", "CONTEXT should win over CONTEXT-DRAFT"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 3: discussing (auto-mode only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 3: discussing (auto-mode only)", () => { + test("discussing is NOT reachable from deriveState", async () => { + // discussing is set only by auto-mode, never by state derivation. + // Verify that CONTEXT-DRAFT → needs-discussion (not discussing). + const base = createFixtureBase(); + writeContextDraft(base, "M001", "# M001: Draft\n\nDraft."); + invalidateStateCache(); + const state = await deriveState(base); + assert.notEqual(state.phase, "discussing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 4: researching (auto-mode only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 4: researching (auto-mode only)", () => { + test("researching is NOT reachable from deriveState", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "# M001: Test\n\nContext."); + writeRoadmap(base, "M001", standardRoadmap()); + invalidateStateCache(); + const state = await deriveState(base); + assert.notEqual(state.phase, "researching"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 5: planning + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 5: planning", () => { + test("roadmap with slice, no PLAN file → planning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "planning"); + assert.ok(state.activeSlice !== null); + assert.equal(state.activeSlice?.id, "S01"); + }); + + test("PLAN exists but zero tasks → planning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + // Plan file with no task entries + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), [ + "# S01: First Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "No tasks defined yet.", + ].join("\n")); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "planning", "plan with zero tasks should remain in planning"); + }); + + test("PLAN with tasks but missing T##-PLAN.md files → planning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + // Write plan file WITH tasks but WITHOUT stub T##-PLAN.md files + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(join(dir, "tasks"), { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), standardPlan()); + // Intentionally do NOT create T01-PLAN.md or T02-PLAN.md + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "planning", "missing task plan files should stay in planning"); + }); + + test("PLAN with all task plan files → NOT planning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.notEqual(state.phase, "planning", "complete plan should advance past planning"); + // Should be executing since there are incomplete tasks + assert.equal(state.phase, "executing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 6: evaluating-gates (DB path only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 6: evaluating-gates", () => { + test("DB path: pending quality gates → evaluating-gates", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + // Set up milestone + slice + task in DB + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + + // Write plan on disk (needed for state derivation) + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + // Insert a pending quality gate + insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice", status: "pending" }); + + const pending = getPendingSliceGateCount("M001", "S01"); + assert.ok(pending > 0, "should have pending gates"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.phase, "evaluating-gates"); + }); + + test("DB path: no pending gates → NOT evaluating-gates", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + // No gate rows → getPendingSliceGateCount returns 0 + const pending = getPendingSliceGateCount("M001", "S01"); + assert.equal(pending, 0, "should have no pending gates"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.notEqual(state.phase, "evaluating-gates"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 7: executing + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 7: executing", () => { + test("active task, no blockers → executing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "executing"); + assert.ok(state.activeTask !== null); + assert.equal(state.activeTask?.id, "T01"); + }); + + test("active task with CONTINUE.md → executing with resume message", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + writeContinue(base, "M001", "S01"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "executing"); + assert.ok( + state.nextAction.toLowerCase().includes("resume") || state.nextAction.toLowerCase().includes("continue"), + "nextAction should mention resume/continue", + ); + }); + + test("one task remaining among completed → executing (not summarizing)", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", partialDonePlan()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "executing", "should be executing while tasks remain"); + assert.equal(state.activeTask?.id, "T02", "active task should be T02"); + assert.equal(state.progress?.tasks?.done, 1); + assert.equal(state.progress?.tasks?.total, 2); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 8: verifying (auto-mode only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 8: verifying (auto-mode only)", () => { + test("verifying is NOT reachable from deriveState", async () => { + // verifying is set only by auto-mode verification gates. + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", allDonePlan()); + invalidateStateCache(); + const state = await deriveState(base); + assert.notEqual(state.phase, "verifying"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 9: summarizing + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 9: summarizing", () => { + test("all tasks done, slice not complete → summarizing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", allDonePlan()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "summarizing"); + assert.ok(state.activeSlice !== null); + assert.equal(state.activeSlice?.id, "S01"); + assert.equal(state.activeTask, null, "no active task when all done"); + assert.equal(state.progress?.tasks?.done, 2); + assert.equal(state.progress?.tasks?.total, 2); + }); + + test("tasks reconciled via SUMMARY on disk → summarizing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + // Plan says tasks incomplete (headings, no checkboxes) ... + const planContent = [ + "# S01: First Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "### T01: First Task", + "First task.", + "", + "### T02: Second Task", + "Second task.", + ].join("\n"); + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(dir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), planContent); + writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\nStub.\n"); + writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan\nStub.\n"); + + // ... but SUMMARY files exist on disk (reconciliation trigger) + writeTaskSummary(base, "M001", "S01", "T01"); + writeTaskSummary(base, "M001", "S01", "T02"); + + invalidateStateCache(); + const state = await deriveState(base); + + // Reconciliation should mark both tasks done → summarizing + assert.equal(state.phase, "summarizing", "SUMMARY reconciliation should advance to summarizing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 10: advancing (auto-mode only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 10: advancing (auto-mode only)", () => { + test("advancing is NOT reachable from deriveState", async () => { + // advancing is an internal auto-mode transition marker + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + invalidateStateCache(); + const state = await deriveState(base); + assert.notEqual(state.phase, "advancing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 11: validating-milestone + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 11: validating-milestone", () => { + test("all slices done, no VALIDATION file → validating-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "validating-milestone"); + assert.ok(state.activeMilestone !== null); + }); + + test("all slices done, VALIDATION with unparseable verdict → validating-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + // Write a validation file with no parseable verdict + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "M001-VALIDATION.md"), "Just some text with no frontmatter verdict."); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "validating-milestone", "unparseable verdict should stay in validating"); + }); + + test("all slices done, terminal verdict → NOT validating-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.notEqual(state.phase, "validating-milestone"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 12: completing-milestone + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 12: completing-milestone", () => { + test("all slices done, validation terminal, no SUMMARY → completing-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "completing-milestone"); + assert.ok(state.activeMilestone !== null); + }); + + test("all slices done, validation terminal, SUMMARY exists → NOT completing-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + writeMilestoneSummary(base, "M001"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.notEqual(state.phase, "completing-milestone", "should be complete, not completing"); + assert.equal(state.phase, "complete"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 13: replanning-slice + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 13: replanning-slice", () => { + test("filesystem: task with blocker_discovered, no REPLAN.md → replanning-slice", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + // T01 is done with blocker, T02 is pending + writePlan(base, "M001", "S01", partialDonePlan()); + writeTaskSummaryWithBlocker(base, "M001", "S01", "T01"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "replanning-slice"); + assert.ok(state.blockers.length > 0, "should have blocker details"); + }); + + test("filesystem: REPLAN-TRIGGER.md exists, no REPLAN.md → replanning-slice", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + writeReplanTrigger(base, "M001", "S01"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "replanning-slice"); + }); + + test("filesystem: REPLAN-TRIGGER + REPLAN.md exists → NOT replanning-slice (loop guard)", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + writeReplanTrigger(base, "M001", "S01"); + writeReplan(base, "M001", "S01"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.notEqual(state.phase, "replanning-slice", "REPLAN.md loop guard should prevent re-entering replanning"); + // Should fall through to executing + assert.equal(state.phase, "executing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 14: complete + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 14: complete", () => { + test("single milestone with SUMMARY + VALIDATION → complete", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + writeMilestoneSummary(base, "M001"); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "complete"); + assert.equal(state.registry.length, 1); + assert.equal(state.registry[0]?.status, "complete"); + }); + + test("all milestones complete → complete", async () => { + const base = createFixtureBase(); + // M001: complete + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + writeMilestoneSummary(base, "M001"); + + // M002: also complete + writeRoadmap(base, "M002", [ + "# M002: Second Milestone", + "", + "**Vision:** Test.", + "", + "## Slices", + "", + "- [x] **S01: Done** `risk:low` `depends:[]`", + " > After this: done.", + ].join("\n")); + writeMilestoneValidation(base, "M002", "pass"); + writeMilestoneSummary(base, "M002"); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "complete"); + assert.equal(state.registry.length, 2); + assert.ok(state.registry.every(e => e.status === "complete"), "all registry entries should be complete"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 15: paused (auto-mode only) + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 15: paused (auto-mode only)", () => { + test("paused is NOT reachable from deriveState", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + invalidateStateCache(); + const state = await deriveState(base); + assert.notEqual(state.phase, "paused"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // PHASE 16: blocked + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Phase 16: blocked", () => { + test("milestone with unmet dependency → blocked", async () => { + const base = createFixtureBase(); + // M001 depends on M000 which doesn't exist — uses YAML frontmatter + writeContext(base, "M001", [ + "---", + "depends_on:", + " - M000", + "---", + "", + "# M001: Test", + "", + "Context.", + ].join("\n")); + writeRoadmap(base, "M001", [ + "# M001: Test Milestone", + "", + "**Vision:** Test blocked.", + "", + "## Slices", + "", + "- [ ] **S01: Slice** `risk:low` `depends:[]`", + " > After this: done.", + ].join("\n")); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "blocked"); + assert.ok(state.blockers.length > 0, "should have blockers"); + }); + + test("no eligible slice (all deps unmet) → blocked at slice level", async () => { + const base = createFixtureBase(); + // S01 depends on S00 which doesn't exist + writeRoadmap(base, "M001", [ + "# M001: Test Milestone", + "", + "**Vision:** Test blocked slices.", + "", + "## Slices", + "", + "- [ ] **S01: First** `risk:low` `depends:[S00]`", + " > After this: done.", + ].join("\n")); + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "blocked"); + assert.ok( + state.blockers.some(b => b.includes("dependency") || b.includes("eligible")), + "blockers should mention dependency or eligibility", + ); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // RECONCILIATION + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Reconciliation", () => { + test("DB: task with SUMMARY on disk but DB says pending → reconciliation fixes status (#2514)", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02: Task", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + // Write SUMMARY files on disk for both tasks (simulating session disconnect) + writeTaskSummary(base, "M001", "S01", "T01"); + writeTaskSummary(base, "M001", "S01", "T02"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // Reconciliation should detect SUMMARY→DB mismatch and update + // All tasks done → summarizing (not executing) + assert.equal(state.phase, "summarizing", "reconciliation should advance past pending tasks"); + }); + + test("empty DB with disk milestones → disk-to-DB sync (#2631)", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "# M001: Test\n\nContext."); + + // Open DB — milestones table starts empty + openDatabase(":memory:"); + const before = getAllMilestones(); + assert.equal(before.length, 0, "DB should start empty"); + + invalidateStateCache(); + const state = await deriveState(base); + + // After deriveState, DB should have the disk milestone + const after = getAllMilestones(); + assert.ok(after.length > 0, "DB should have milestones after reconciliation"); + assert.equal(after[0]!.id, "M001"); + assert.ok(state.activeMilestone !== null); + }); + + test("ghost milestone (empty dir) → NOT in registry", async () => { + const base = createFixtureBase(); + // Create empty milestone dir (ghost — no CONTEXT, ROADMAP, SUMMARY) + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + // Create a real milestone too + writeContext(base, "M002", "# M002: Real\n\nContext."); + invalidateStateCache(); + const state = await deriveState(base); + + // M001 (ghost) should not appear in registry + const m001 = state.registry.find(e => e.id === "M001"); + assert.equal(m001, undefined, "ghost milestone should not appear in registry"); + // M002 should be there + const m002 = state.registry.find(e => e.id === "M002"); + assert.ok(m002 !== undefined, "real milestone should appear in registry"); + }); + + test("ghost milestone detection helper", () => { + const base = createFixtureBase(); + // Ghost: empty dir + mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true }); + clearPathCache(); + assert.equal(isGhostMilestone(base, "M001"), true, "empty dir is ghost"); + + // Not ghost: has CONTEXT + writeContext(base, "M002", "# M002\n\nContext."); + clearPathCache(); + assert.equal(isGhostMilestone(base, "M002"), false, "dir with CONTEXT is not ghost"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // CROSS-VALIDATION + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Cross-validation: DB vs filesystem", () => { + test("executing scenario produces same phase on both paths", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: First", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02: Second", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + invalidateStateCache(); + const dbState = await deriveStateFromDb(base); + + closeDatabase(); + + invalidateStateCache(); + const fsState = await deriveState(base); + + assert.equal(dbState.phase, "executing", "DB path should produce executing"); + assert.equal(fsState.phase, "executing", "filesystem path should produce executing"); + assert.equal(dbState.activeTask?.id, fsState.activeTask?.id, "active task should match"); + }); + + test("summarizing scenario produces same phase on both paths", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: First", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02: Second", status: "complete" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", allDonePlan()); + + invalidateStateCache(); + const dbState = await deriveStateFromDb(base); + + closeDatabase(); + + invalidateStateCache(); + const fsState = await deriveState(base); + + assert.equal(dbState.phase, "summarizing", "DB path should produce summarizing"); + assert.equal(fsState.phase, "summarizing", "filesystem path should produce summarizing"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // EDGE CASES + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Edge cases", () => { + test("isValidationTerminal: terminal verdicts", () => { + assert.equal(isValidationTerminal("---\nverdict: pass\n---\n"), true, "pass is terminal"); + assert.equal(isValidationTerminal("---\nverdict: fail\n---\n"), true, "fail is terminal"); + assert.equal(isValidationTerminal("---\nverdict: needs-remediation\n---\n"), true, "needs-remediation is terminal"); + assert.equal(isValidationTerminal("---\nverdict: needs-attention\n---\n"), true, "needs-attention is terminal"); + }); + + test("isValidationTerminal: non-terminal content", () => { + assert.equal(isValidationTerminal("No frontmatter at all"), false, "no frontmatter is not terminal"); + assert.equal(isValidationTerminal(""), false, "empty string is not terminal"); + assert.equal(isValidationTerminal("---\n---\n"), false, "empty frontmatter is not terminal"); + }); + + test("isClosedStatus boundary", () => { + assert.equal(isClosedStatus("complete"), true); + assert.equal(isClosedStatus("done"), true); + assert.equal(isClosedStatus("pending"), false); + assert.equal(isClosedStatus("in-progress"), false); + assert.equal(isClosedStatus("blocked"), false); + assert.equal(isClosedStatus("active"), false); + assert.equal(isClosedStatus(""), false); + }); + + test("multiple milestones: M001 complete, M002 active → M002 is activeMilestone", async () => { + const base = createFixtureBase(); + // M001: complete + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + writeMilestoneSummary(base, "M001"); + + // M002: active, in planning phase + writeContext(base, "M002", "# M002: Next Milestone\n\nContext for M002."); + writeRoadmap(base, "M002", [ + "# M002: Next Milestone", + "", + "**Vision:** Next phase.", + "", + "## Slices", + "", + "- [ ] **S01: New Slice** `risk:low` `depends:[]`", + " > After this: done.", + ].join("\n")); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.activeMilestone?.id, "M002", "active milestone should be M002"); + assert.notEqual(state.phase, "complete", "should not be complete while M002 is active"); + // M001 in registry as complete + const m001 = state.registry.find(e => e.id === "M001"); + assert.ok(m001 !== undefined, "M001 should be in registry"); + assert.equal(m001?.status, "complete", "M001 should be complete"); + // M002 in registry as active + const m002 = state.registry.find(e => e.id === "M002"); + assert.ok(m002 !== undefined, "M002 should be in registry"); + assert.equal(m002?.status, "active", "M002 should be active"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // FAILURE MODES: What happens when things go wrong + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Recovery: DB has slice but no task rows (partial migration)", () => { + test("DB tasks empty but PLAN on disk has tasks → reconciles to executing", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + // NO insertTask() — simulates partial migration / failed write + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // FIX (#3600): plan-file tasks are now reconciled into the DB, + // so the phase correctly advances to executing instead of planning. + assert.equal(state.phase, "executing", + "reconciled plan-file tasks → executing (not stuck in planning)"); + }); + }); + + describe("Failure: partial SUMMARY reconciliation", () => { + test("only one task has SUMMARY, other still pending → executing next task", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02: Task", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + // Only T01 has SUMMARY, T02 does not + writeTaskSummary(base, "M001", "S01", "T01"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // T01 reconciled to complete, T02 still pending → executing T02 + assert.equal(state.phase, "executing"); + assert.equal(state.activeTask?.id, "T02", "should advance to next pending task"); + }); + }); + + describe("Failure: 0-byte files", () => { + test("0-byte SUMMARY file triggers reconciliation (existsSync-only check)", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + // Write 0-byte SUMMARY — existsSync returns true for empty files + const tasksDir = join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(tasksDir, "T01-SUMMARY.md"), ""); + + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // The reconciler checks existsSync(summaryPath) at line 1328 + // — it does NOT read content. So 0-byte file counts as "done". + // This is a known gap: empty SUMMARY treated as completion. + assert.equal(state.phase, "executing", + "0-byte SUMMARY marks T01 done via reconciliation, T02 becomes active"); + assert.equal(state.activeTask?.id, "T02"); + }); + + test("0-byte VALIDATION file → stays in validating-milestone", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "M001-VALIDATION.md"), ""); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "validating-milestone", + "0-byte VALIDATION should not be treated as terminal"); + }); + + test("0-byte PLAN file → planning phase", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), ""); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "planning", "0-byte PLAN should stay in planning"); + }); + }); + + describe("Failure: DB/filesystem divergence", () => { + test("DB says slice complete, no milestone VALIDATION → validating-milestone", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "complete", depends: [] }); + + writeRoadmap(base, "M001", doneSliceRoadmap()); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.phase, "validating-milestone", + "DB-complete slice should trigger milestone validation"); + }); + + test("DB says task complete but SUMMARY missing → no crash, advances to next", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "complete" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02: Task", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.phase, "executing"); + assert.equal(state.activeTask?.id, "T02"); + }); + + test("milestone in DB but directory missing from disk → no crash", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.ok(state.phase !== undefined, "should produce a valid phase"); + }); + }); + + describe("Failure: corrupt frontmatter", () => { + test("VALIDATION with broken frontmatter → stays in validating", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "M001-VALIDATION.md"), [ + "---", + "this is not: valid: yaml: {{{}}}", + "---", + "", + "Some content.", + ].join("\n")); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "validating-milestone", + "corrupt frontmatter should keep milestone in validating phase"); + }); + + test("CONTEXT with broken depends_on → no crash, deps empty", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", [ + "---", + "depends_on: {{{invalid}}}", + "---", + "", + "# M001: Test", + ].join("\n")); + writeRoadmap(base, "M001", standardRoadmap()); + + invalidateStateCache(); + const state = await deriveState(base); + + assert.ok(state.phase !== undefined, "should not crash on corrupt depends_on"); + // With corrupt deps, parseContextDependsOn returns [] → no blocking + assert.notEqual(state.phase, "blocked", + "corrupt deps should not falsely block milestone"); + }); + }); + + describe("Failure: missing task plan files in DB path", () => { + test("DB has tasks but no T##-PLAN.md files → planning phase", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + + writeRoadmap(base, "M001", standardRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(join(dir, "tasks"), { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), standardPlan()); + // NO T01-PLAN.md + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + assert.equal(state.phase, "planning", + "missing T##-PLAN.md files should keep state in planning"); + }); + }); + + describe("Failure: stale path cache", () => { + test("file created after cache populated → must clear path cache", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + + invalidateStateCache(); + clearPathCache(); + const state1 = await deriveState(base); + assert.equal(state1.phase, "planning"); + + // Write PLAN AFTER first derivation cached paths + writePlan(base, "M001", "S01", standardPlan()); + + // Without clearPathCache, stale cache may miss the new file + invalidateStateCache(); + clearPathCache(); + const state2 = await deriveState(base); + + assert.equal(state2.phase, "executing", + "after cache clear, should see the new PLAN file"); + }); + }); + + describe("Failure: blocker detection edge cases", () => { + test("filesystem: blocker in SUMMARY but task not marked [x] → still detected", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + // T01 marked done in plan, T02 pending + writePlan(base, "M001", "S01", partialDonePlan()); + // T01 SUMMARY has blocker_discovered in frontmatter + writeTaskSummaryWithBlocker(base, "M001", "S01", "T01"); + + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "replanning-slice", + "blocker_discovered in SUMMARY frontmatter should trigger replanning"); + }); + }); + + // ═══════════════════════════════════════════════════════════════════════════ + // FAILURE AT EVERY PHASE: What breaks mid-transition + // ═══════════════════════════════════════════════════════════════════════════ + + describe("Failure at pre-planning: CONTEXT file half-written", () => { + test("CONTEXT exists but is garbage → still enters pre-planning (no roadmap)", async () => { + const base = createFixtureBase(); + writeContext(base, "M001", "\x00\x00\x00binary garbage\xff\xfe"); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // File exists so milestone is not ghost, but no roadmap → pre-planning + assert.equal(state.phase, "pre-planning"); + assert.ok(state.activeMilestone !== null); + }); + }); + + describe("Failure at needs-discussion: CONTEXT-DRAFT is empty", () => { + test("0-byte CONTEXT-DRAFT → should still trigger needs-discussion", async () => { + const base = createFixtureBase(); + const dir = join(base, ".gsd", "milestones", "M001"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "M001-CONTEXT-DRAFT.md"), ""); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // File exists (even empty) → not a ghost, has draft → needs-discussion + assert.equal(state.phase, "needs-discussion", + "0-byte draft should still trigger discussion phase"); + }); + }); + + describe("Failure at planning: ROADMAP exists but is unparseable", () => { + test("ROADMAP with no slices section → pre-planning (zero slices)", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", "# M001: Test\n\nJust some text, no ## Slices section."); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // parseRoadmap finds no slices → empty array → pre-planning + assert.equal(state.phase, "pre-planning", + "unparseable roadmap with no slices should fall to pre-planning"); + }); + + test("ROADMAP with broken slice syntax → treats as zero slices", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", [ + "# M001: Test", + "", + "**Vision:** Test.", + "", + "## Slices", + "", + "This is not a valid slice entry at all.", + "Neither is this.", + ].join("\n")); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // No parseable slice entries → zero slices → pre-planning + assert.equal(state.phase, "pre-planning", + "broken slice syntax should result in zero slices"); + }); + }); + + describe("Failure at planning: PLAN file is corrupt", () => { + test("PLAN exists but tasks section is garbage → zero tasks → planning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), [ + "# S01: Slice", + "", + "## Tasks", + "", + "random garbage with no task markers", + "more garbage", + ].join("\n")); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "planning", + "PLAN with unparseable tasks should stay in planning"); + }); + }); + + describe("Failure at executing: task plan file is empty", () => { + test("T01-PLAN.md exists but is 0-byte → still enters executing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + const dir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + const tasksDir = join(dir, "tasks"); + mkdirSync(tasksDir, { recursive: true }); + writeFileSync(join(dir, "S01-PLAN.md"), standardPlan()); + // Create task plan files but make them 0-byte + writeFileSync(join(tasksDir, "T01-PLAN.md"), ""); + writeFileSync(join(tasksDir, "T02-PLAN.md"), ""); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // Task plan file existence check at line 718-730 uses readdirSync + // to count .md files. 0-byte files still count. + assert.equal(state.phase, "executing", + "0-byte task plan files still pass the existence check"); + }); + }); + + describe("Failure at executing: DB has task but wrong status string", () => { + test("task with unexpected status string → not treated as closed", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01: Task", status: "pending" }); + + // Set a garbage status that isn't "complete" or "done" + updateTaskStatus("M001", "S01", "T01", "finished"); + + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", standardPlan()); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // isClosedStatus("finished") → false → task treated as active + assert.equal(state.phase, "executing"); + assert.equal(state.activeTask?.id, "T01", + "non-standard status 'finished' is NOT treated as closed"); + }); + }); + + describe("Failure at summarizing: slice SUMMARY write fails (file missing)", () => { + test("all tasks [x] but no slice SUMMARY → stays in summarizing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", allDonePlan()); + // All tasks done but no S01-SUMMARY.md written + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + assert.equal(state.phase, "summarizing"); + // Next derivation still returns summarizing — no infinite loop + invalidateStateCache(); + const state2 = await deriveState(base); + assert.equal(state2.phase, "summarizing", "stays in summarizing until SUMMARY written"); + }); + }); + + describe("Failure at validating-milestone: VALIDATION write crashes", () => { + test("all slices done, validation never written → stuck in validating", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + // No VALIDATION file at all + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + assert.equal(state.phase, "validating-milestone"); + + // Call again — still validating (idempotent, not looping) + invalidateStateCache(); + const state2 = await deriveState(base); + assert.equal(state2.phase, "validating-milestone", + "stays in validating until VALIDATION file appears"); + }); + }); + + describe("Failure at completing-milestone: SUMMARY write fails", () => { + test("validation terminal but SUMMARY never written → stuck in completing", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + writeMilestoneValidation(base, "M001", "pass"); + // No milestone SUMMARY + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + assert.equal(state.phase, "completing-milestone"); + + // Repeated calls stay in completing + invalidateStateCache(); + const state2 = await deriveState(base); + assert.equal(state2.phase, "completing-milestone", + "stays in completing until SUMMARY written"); + }); + }); + + describe("Failure at replanning: REPLAN.md never written (loop risk)", () => { + test("blocker detected, replan dispatched but REPLAN.md not created → re-enters replanning", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", standardRoadmap()); + writePlan(base, "M001", "S01", partialDonePlan()); + writeTaskSummaryWithBlocker(base, "M001", "S01", "T01"); + // No REPLAN.md — simulates failed replan execution + + invalidateStateCache(); + clearPathCache(); + const state1 = await deriveState(base); + assert.equal(state1.phase, "replanning-slice"); + + // Call again — same result, stuck in replanning until REPLAN.md appears + invalidateStateCache(); + const state2 = await deriveState(base); + assert.equal(state2.phase, "replanning-slice", + "without REPLAN.md, state stays in replanning (dispatch will retry)"); + }); + }); + + describe("Failure at complete: SUMMARY exists but VALIDATION missing", () => { + test("milestone SUMMARY without VALIDATION → still complete (SUMMARY is terminal artifact)", async () => { + const base = createFixtureBase(); + writeRoadmap(base, "M001", doneSliceRoadmap()); + // SUMMARY exists but NO VALIDATION + writeMilestoneSummary(base, "M001"); + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // Per #864: SUMMARY is the terminal artifact, validation optional + assert.equal(state.phase, "complete", + "SUMMARY alone should mark milestone complete per #864"); + }); + }); + + describe("Failure at blocked: dependency milestone partially complete", () => { + test("M001 has slices done but no SUMMARY → M002 (depends on M001) is blocked", async () => { + const base = createFixtureBase(); + // M001: all slices done but no SUMMARY/VALIDATION + writeRoadmap(base, "M001", doneSliceRoadmap()); + // M001 has no SUMMARY → it's in validating/completing, NOT complete + + // M002: depends on M001 + writeContext(base, "M002", [ + "---", + "depends_on:", + " - M001", + "---", + "", + "# M002: Dependent", + ].join("\n")); + writeRoadmap(base, "M002", [ + "# M002: Dependent", + "", + "**Vision:** Test.", + "", + "## Slices", + "", + "- [ ] **S01: Slice** `risk:low` `depends:[]`", + " > After this: done.", + ].join("\n")); + + invalidateStateCache(); + clearPathCache(); + const state = await deriveState(base); + + // M001 is active (not yet complete), M002 should wait + assert.equal(state.activeMilestone?.id, "M001", + "M001 should be active (not complete without SUMMARY)"); + assert.notEqual(state.activeMilestone?.id, "M002", + "M002 should not be active while M001 is incomplete"); + }); + }); + + describe("Failure: multiple reconciliation in single derivation", () => { + test("DB has 3 stale tasks, all with SUMMARY on disk → all reconciled in one pass", async () => { + const base = createFixtureBase(); + const dbPath = join(base, ".gsd", "gsd.db"); + openDatabase(dbPath); + + insertMilestone({ id: "M001", title: "M001: Test", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "S01: Slice", status: "active", depends: [] }); + insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "T01", status: "pending" }); + insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "T02", status: "in-progress" }); + insertTask({ id: "T03", sliceId: "S01", milestoneId: "M001", title: "T03", status: "pending" }); + + const threeTaskRoadmap = [ + "# M001: Test", + "", + "**Vision:** Test.", + "", + "## Slices", + "", + "- [ ] **S01: Slice** `risk:low` `depends:[]`", + " > After this: done.", + ].join("\n"); + writeRoadmap(base, "M001", threeTaskRoadmap); + + const threeTaskPlan = [ + "# S01: Slice", + "", + "**Goal:** Test.", + "**Demo:** Tests pass.", + "", + "## Tasks", + "", + "- [ ] **T01: First** `est:10m`", + " First.", + "", + "- [ ] **T02: Second** `est:10m`", + " Second.", + "", + "- [ ] **T03: Third** `est:10m`", + " Third.", + ].join("\n"); + writePlan(base, "M001", "S01", threeTaskPlan); + + // All 3 tasks have SUMMARY on disk + writeTaskSummary(base, "M001", "S01", "T01"); + writeTaskSummary(base, "M001", "S01", "T02"); + writeTaskSummary(base, "M001", "S01", "T03"); + + invalidateStateCache(); + const state = await deriveStateFromDb(base); + + // All 3 should be reconciled in one pass → summarizing + assert.equal(state.phase, "summarizing", + "all 3 stale tasks should be reconciled to complete in one derivation"); + }); + }); +}); diff --git a/src/resources/extensions/gsd/tests/status-db-open.test.ts b/src/resources/extensions/gsd/tests/status-db-open.test.ts new file mode 100644 index 000000000..1fbd1aeb4 --- /dev/null +++ b/src/resources/extensions/gsd/tests/status-db-open.test.ts @@ -0,0 +1,47 @@ +/** + * Regression test for #3691 — /gsd status opens DB before deriveState + * + * In cold sessions the DB was not opened before deriveState, causing + * status to fall back to filesystem-only state. The fix adds an + * ensureDbOpen() call before deriveState in handleStatus. + * + * Also verifies that quick.ts checks getIsolationMode before branching. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const coreSrc = readFileSync( + join(__dirname, '..', 'commands', 'handlers', 'core.ts'), + 'utf-8', +); +const quickSrc = readFileSync( + join(__dirname, '..', 'quick.ts'), + 'utf-8', +); + +describe('status opens DB before deriveState (#3691)', () => { + test('handleStatus calls ensureDbOpen before deriveState', () => { + const ensureIdx = coreSrc.indexOf('ensureDbOpen'); + const deriveIdx = coreSrc.indexOf('deriveState(basePath)'); + assert.ok(ensureIdx > -1, 'ensureDbOpen call should exist in core.ts'); + assert.ok(deriveIdx > -1, 'deriveState(basePath) call should exist in core.ts'); + assert.ok( + ensureIdx < deriveIdx, + 'ensureDbOpen must appear before deriveState so DB is ready', + ); + }); + + test('quick.ts checks getIsolationMode before branching', () => { + assert.match(quickSrc, /getIsolationMode\(\)/, + 'quick.ts should call getIsolationMode()'); + assert.match(quickSrc, /getIsolationMode\(\)\s*!==\s*"none"/, + 'quick.ts should compare isolation mode against "none"'); + }); +}); diff --git a/src/resources/extensions/gsd/tests/status-guards.test.ts b/src/resources/extensions/gsd/tests/status-guards.test.ts index 44ab72bfc..03bbd23de 100644 --- a/src/resources/extensions/gsd/tests/status-guards.test.ts +++ b/src/resources/extensions/gsd/tests/status-guards.test.ts @@ -13,6 +13,10 @@ test('isClosedStatus: "done" returns true', () => { assert.equal(isClosedStatus('done'), true); }); +test('isClosedStatus: "skipped" returns true', () => { + assert.equal(isClosedStatus('skipped'), true); +}); + test('isClosedStatus: "pending" returns false', () => { assert.equal(isClosedStatus('pending'), false); }); diff --git a/src/resources/extensions/gsd/tests/steer-worktree-path.test.ts b/src/resources/extensions/gsd/tests/steer-worktree-path.test.ts new file mode 100644 index 000000000..137eb6cd6 --- /dev/null +++ b/src/resources/extensions/gsd/tests/steer-worktree-path.test.ts @@ -0,0 +1,108 @@ +// GSD Extension - Steer Worktree Path Resolution Test +// Regression test for #3476: /gsd steer must write overrides to the worktree .gsd/, +// not the project root .gsd/, when a worktree is active. + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, existsSync, readFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { appendOverride, loadActiveOverrides } from "../files.ts"; +import { getAutoWorktreePath } from "../auto-worktree.ts"; + +describe("steer worktree path resolution (#3476)", () => { + let projectRoot: string; + let worktreePath: string; + + beforeEach(() => { + projectRoot = mkdtempSync(join(tmpdir(), "gsd-steer-wt-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + + // Simulate a worktree with its own .gsd directory + worktreePath = join(projectRoot, ".gsd", "worktrees", "M001"); + mkdirSync(join(worktreePath, ".gsd"), { recursive: true }); + }); + + afterEach(() => { + rmSync(projectRoot, { recursive: true, force: true }); + }); + + test("appendOverride writes to worktree .gsd/ when worktree path is used", async () => { + await appendOverride(worktreePath, "Use Postgres instead of SQLite", "M001/S01/T01"); + + // Override should be in the worktree .gsd/ + const wtOverrides = join(worktreePath, ".gsd", "OVERRIDES.md"); + assert.ok(existsSync(wtOverrides), "override file exists in worktree .gsd/"); + + const content = readFileSync(wtOverrides, "utf-8"); + assert.ok(content.includes("Use Postgres instead of SQLite"), "override content is correct"); + + // Override should NOT be in the project root .gsd/ + const rootOverrides = join(projectRoot, ".gsd", "OVERRIDES.md"); + assert.ok(!existsSync(rootOverrides), "no override file in project root .gsd/"); + }); + + test("loadActiveOverrides reads from worktree .gsd/ when worktree path is used", async () => { + await appendOverride(worktreePath, "Switch to JWT auth", "M001/S02/T01"); + + // Loading from worktree should find the override + const wtOverrides = await loadActiveOverrides(worktreePath); + assert.equal(wtOverrides.length, 1, "one active override in worktree"); + assert.equal(wtOverrides[0].change, "Switch to JWT auth"); + + // Loading from project root should find nothing + const rootOverrides = await loadActiveOverrides(projectRoot); + assert.equal(rootOverrides.length, 0, "no overrides in project root"); + }); + + test("appendOverride falls back to project root when no worktree exists", async () => { + await appendOverride(projectRoot, "Use Redis cache", "M001/S01/T01"); + + const rootOverrides = join(projectRoot, ".gsd", "OVERRIDES.md"); + assert.ok(existsSync(rootOverrides), "override file exists in project root .gsd/"); + + const content = readFileSync(rootOverrides, "utf-8"); + assert.ok(content.includes("Use Redis cache"), "override content is correct"); + }); + + test("getAutoWorktreePath returns null for worktree without valid .git file", () => { + // The worktree directory exists but has no .git file — this is an inactive/ + // leftover worktree. getAutoWorktreePath must return null so handleSteer + // does not route overrides to a dead worktree. + const result = getAutoWorktreePath(projectRoot, "M001"); + assert.equal(result, null, "returns null for worktree without .git file"); + }); + + test("override routing: inactive worktree directory should not receive overrides", async () => { + // Simulate the handleSteer path-resolution logic: + // When no auto-mode is running, even if a worktree dir exists, + // overrides must go to the project root. + const autoRunning = false; // no live session + const wtPath = autoRunning ? getAutoWorktreePath(projectRoot, "M001") : null; + const targetPath = wtPath ?? projectRoot; + + await appendOverride(targetPath, "Should go to project root", "M001/S01/T01"); + + const rootOverrides = join(projectRoot, ".gsd", "OVERRIDES.md"); + const wtOverrides = join(worktreePath, ".gsd", "OVERRIDES.md"); + + assert.ok(existsSync(rootOverrides), "override written to project root"); + assert.ok(!existsSync(wtOverrides), "override NOT written to inactive worktree"); + }); + + test("override routing: active worktree with valid .git should receive overrides", async () => { + // Simulate the handleSteer path-resolution logic with active auto-mode. + // getAutoWorktreePath requires a valid .git file, so even with autoRunning=true, + // it returns null for our test worktree (no real .git). This confirms the + // double-gate: both autoRunning AND valid worktree must be true. + const autoRunning = true; + const wtPath = autoRunning ? getAutoWorktreePath(projectRoot, "M001") : null; + const targetPath = wtPath ?? projectRoot; + + // Without a valid .git file, falls back to project root + await appendOverride(targetPath, "Falls back without .git", "M001/S01/T01"); + + const rootOverrides = join(projectRoot, ".gsd", "OVERRIDES.md"); + assert.ok(existsSync(rootOverrides), "override written to project root (no valid .git in worktree)"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/stop-auto-race-null-unit.test.ts b/src/resources/extensions/gsd/tests/stop-auto-race-null-unit.test.ts new file mode 100644 index 000000000..d5883a14b --- /dev/null +++ b/src/resources/extensions/gsd/tests/stop-auto-race-null-unit.test.ts @@ -0,0 +1,106 @@ +/** + * stop-auto-race-null-unit.test.ts — Regression test for #2939. + * + * When the user stops auto-mode while a unit is executing, stopAuto() + * calls s.reset() which sets s.currentUnit = null. The resumed + * runUnitPhase() then hits s.currentUnit.startedAt on the closeout + * line and throws a TypeError. + * + * The fix adds null guards (matching the existing pattern at lines 136 + * and 344) so that closeout and subsequent accesses are skipped when + * s.currentUnit has been nulled by a concurrent stopAuto(). + */ + +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { createTestContext } from "./test-helpers.ts"; + +const { assertTrue, report } = createTestContext(); + +const phasesPath = join(import.meta.dirname, "..", "auto", "phases.ts"); +const phasesSrc = readFileSync(phasesPath, "utf-8"); + +console.log("\n=== #2939: stopAuto race — null guard on s.currentUnit in closeout ==="); + +// ── Test 1: closeoutUnit call is guarded by if (s.currentUnit) ────────── +// The closeout block starting around the "Immediate unit closeout" comment +// must be wrapped in an `if (s.currentUnit)` guard, matching the pattern +// already used at lines 136 and 344. + +const closeoutComment = "Immediate unit closeout"; +const closeoutIdx = phasesSrc.indexOf(closeoutComment); +assertTrue( + closeoutIdx > 0, + "phases.ts contains the 'Immediate unit closeout' comment block", +); + +// Extract the region from the closeout comment to the next section comment +const closeoutRegion = phasesSrc.slice(closeoutIdx, closeoutIdx + 500); +assertTrue( + closeoutRegion.includes("if (s.currentUnit)"), + "closeoutUnit call is guarded by `if (s.currentUnit)` check (#2939)", +); + +// ── Test 2: zero-tool-call guard uses s.currentUnit?.startedAt ────────── +// The zero-tool-call section accesses s.currentUnit!.startedAt (non-null +// assertion) which will throw if currentUnit is null. + +const zeroToolComment = "Zero tool-call guard"; +const zeroToolIdx = phasesSrc.indexOf(zeroToolComment); +assertTrue( + zeroToolIdx > 0, + "phases.ts contains the 'Zero tool-call guard' comment block", +); + +const zeroToolRegion = phasesSrc.slice(zeroToolIdx, zeroToolIdx + 600); + +// The non-null assertion `s.currentUnit!.startedAt` must be replaced with +// optional chaining `s.currentUnit?.startedAt` +assertTrue( + !zeroToolRegion.includes("s.currentUnit!.startedAt"), + "zero-tool-call guard no longer uses non-null assertion on s.currentUnit (#2939)", +); + +// ── Test 3: return value uses optional chaining for startedAt ─────────── +// The final return at the end of runUnitPhase uses s.currentUnit.startedAt +// which will throw if currentUnit was nulled. It must use optional chaining. + +// Find the last return statement in runUnitPhase that references startedAt. +// There are two: one inside the zero-tool-call block and one at the end. +// Both must use s.currentUnit?.startedAt + +// Count unguarded s.currentUnit.startedAt (without optional chaining) +// after the "Immediate unit closeout" comment. All of them should use +// optional chaining or be inside a guard. +const afterCloseout = phasesSrc.slice(closeoutIdx); + +// Count s.currentUnit!.startedAt (non-null assertion — always unsafe) +const nonNullPattern = /s\.currentUnit!\.startedAt/g; +const nonNullAfterCloseout = [...afterCloseout.matchAll(nonNullPattern)]; +assertTrue( + nonNullAfterCloseout.length === 0, + `no non-null assertions s.currentUnit!.startedAt after closeout comment (found ${nonNullAfterCloseout.length}, expected 0) (#2939)`, +); + +// Count bare s.currentUnit.startedAt that are NOT inside an if (s.currentUnit) guard. +// The closeout block itself uses s.currentUnit.startedAt inside a guard — that's fine. +// But any usage outside a guard block (e.g. in a return statement) must use optional chaining. +// We check that all return statements use optional chaining. +const returnWithBareAccess = /return\s*\{[^}]*s\.currentUnit\.startedAt/g; +const bareReturnCount = [...afterCloseout.matchAll(returnWithBareAccess)].length; +assertTrue( + bareReturnCount === 0, + `no return statements use bare s.currentUnit.startedAt (found ${bareReturnCount}, expected 0) (#2939)`, +); + +// ── Test 4: the return at end of runUnitPhase uses optional chaining ──── +// The final `return { action: "next", data: { unitStartedAt: s.currentUnit?.startedAt } }` +// must use optional chaining. + +const finalReturnPattern = /unitStartedAt:\s*s\.currentUnit\?\.startedAt/; +assertTrue( + finalReturnPattern.test(afterCloseout), + "final return uses s.currentUnit?.startedAt with optional chaining (#2939)", +); + +report(); diff --git a/src/resources/extensions/gsd/tests/stop-backtrack.test.ts b/src/resources/extensions/gsd/tests/stop-backtrack.test.ts new file mode 100644 index 000000000..8773ed236 --- /dev/null +++ b/src/resources/extensions/gsd/tests/stop-backtrack.test.ts @@ -0,0 +1,216 @@ +/** + * Unit tests for stop/backtrack capture classifications and milestone regression (#3487). + * + * Tests: + * - "stop" and "backtrack" are valid classification types + * - loadStopCaptures returns unexecuted stop+backtrack captures + * - loadBacktrackCaptures returns only backtrack captures + * - revertExecutorResolvedCaptures reverts silenced captures + * - executeBacktrack writes trigger and regression markers + * - readBacktrackTrigger parses trigger file + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { isClosedStatus } from "../status-guards.ts"; +import { + appendCapture, + loadAllCaptures, + loadStopCaptures, + loadBacktrackCaptures, + markCaptureResolved, + revertExecutorResolvedCaptures, + hasPendingCaptures, +} from "../captures.ts"; +import { + executeBacktrack, + readBacktrackTrigger, +} from "../triage-resolution.ts"; + +function makeTempDir(prefix: string): string { + const dir = join( + tmpdir(), + `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`, + ); + mkdirSync(dir, { recursive: true }); + return dir; +} + +function setupGsdDir(tmp: string): void { + mkdirSync(join(tmp, ".gsd"), { recursive: true }); +} + +// ─── Classification Types ───────────────────────────────────────────────────── + +test("stop is a valid classification", () => { + const tmp = makeTempDir("stop-class"); + setupGsdDir(tmp); + const id = appendCapture(tmp, "stop running immediately"); + markCaptureResolved(tmp, id, "stop", "Halt auto-mode", "User said stop", "M005"); + const all = loadAllCaptures(tmp); + const cap = all.find(c => c.id === id); + assert.equal(cap?.classification, "stop"); + rmSync(tmp, { recursive: true, force: true }); +}); + +test("backtrack is a valid classification", () => { + const tmp = makeTempDir("bt-class"); + setupGsdDir(tmp); + const id = appendCapture(tmp, "restart from M003"); + markCaptureResolved(tmp, id, "backtrack", "Backtrack to M003", "User wants to restart", "M005"); + const all = loadAllCaptures(tmp); + const cap = all.find(c => c.id === id); + assert.equal(cap?.classification, "backtrack"); + rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── loadStopCaptures ───────────────────────────────────────────────────────── + +test("loadStopCaptures returns unexecuted stop and backtrack captures", () => { + const tmp = makeTempDir("load-stop"); + setupGsdDir(tmp); + const stopId = appendCapture(tmp, "halt execution"); + const btId = appendCapture(tmp, "go back to M003"); + const noteId = appendCapture(tmp, "just a note"); + markCaptureResolved(tmp, stopId, "stop", "Halt", "User stop", "M005"); + markCaptureResolved(tmp, btId, "backtrack", "Backtrack to M003", "User backtrack", "M005"); + markCaptureResolved(tmp, noteId, "note", "Info only", "Not actionable", "M005"); + + const stops = loadStopCaptures(tmp); + assert.equal(stops.length, 2); + assert.ok(stops.some(c => c.classification === "stop")); + assert.ok(stops.some(c => c.classification === "backtrack")); + rmSync(tmp, { recursive: true, force: true }); +}); + +test("loadBacktrackCaptures returns only backtrack captures", () => { + const tmp = makeTempDir("load-bt"); + setupGsdDir(tmp); + const stopId = appendCapture(tmp, "halt execution"); + const btId = appendCapture(tmp, "go back to M003"); + markCaptureResolved(tmp, stopId, "stop", "Halt", "User stop", "M005"); + markCaptureResolved(tmp, btId, "backtrack", "Backtrack to M003", "User backtrack", "M005"); + + const bts = loadBacktrackCaptures(tmp); + assert.equal(bts.length, 1); + assert.equal(bts[0].classification, "backtrack"); + rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── revertExecutorResolvedCaptures ─────────────────────────────────────────── + +test("revertExecutorResolvedCaptures reverts captures resolved without classification", () => { + const tmp = makeTempDir("revert-exec"); + setupGsdDir(tmp); + const id = appendCapture(tmp, "stop everything"); + + // Simulate an executor writing Status: resolved directly (no classification) + const capPath = join(tmp, ".gsd", "CAPTURES.md"); + let content = readFileSync(capPath, "utf-8"); + content = content.replace("**Status:** pending", "**Status:** resolved"); + writeFileSync(capPath, content, "utf-8"); + + // Verify it's now "resolved" without classification + assert.equal(hasPendingCaptures(tmp), false); + + // Revert should detect and fix it + const reverted = revertExecutorResolvedCaptures(tmp); + assert.equal(reverted, 1); + + // Should be pending again + assert.equal(hasPendingCaptures(tmp), true); + rmSync(tmp, { recursive: true, force: true }); +}); + +test("revertExecutorResolvedCaptures does NOT revert properly triaged captures", () => { + const tmp = makeTempDir("revert-skip"); + setupGsdDir(tmp); + const id = appendCapture(tmp, "restart from M003"); + markCaptureResolved(tmp, id, "backtrack", "Backtrack to M003", "User wants restart", "M005"); + + // This capture was properly triaged — should NOT be reverted + const reverted = revertExecutorResolvedCaptures(tmp); + assert.equal(reverted, 0); + rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── executeBacktrack ───────────────────────────────────────────────────────── + +test("executeBacktrack writes trigger and regression markers", () => { + const tmp = makeTempDir("exec-bt"); + setupGsdDir(tmp); + + // Create target milestone directory + mkdirSync(join(tmp, ".gsd", "milestones", "M003"), { recursive: true }); + + const targetMid = executeBacktrack(tmp, "M005", { + id: "CAP-test123", + text: "restart from M003 — milestones after 2 failed", + timestamp: new Date().toISOString(), + status: "resolved", + classification: "backtrack", + resolution: "Backtrack to M003", + rationale: "User directive", + }); + + assert.equal(targetMid, "M003"); + + // Check trigger file exists + const triggerPath = join(tmp, ".gsd", "BACKTRACK-TRIGGER.md"); + assert.ok(existsSync(triggerPath)); + const triggerContent = readFileSync(triggerPath, "utf-8"); + assert.ok(triggerContent.includes("M005")); + assert.ok(triggerContent.includes("M003")); + + // Check regression marker exists on target milestone + const regressionPath = join(tmp, ".gsd", "milestones", "M003", "M003-REGRESSION.md"); + assert.ok(existsSync(regressionPath)); + const regressionContent = readFileSync(regressionPath, "utf-8"); + assert.ok(regressionContent.includes("M005")); + rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── readBacktrackTrigger ───────────────────────────────────────────────────── + +test("readBacktrackTrigger parses trigger file", () => { + const tmp = makeTempDir("read-bt"); + setupGsdDir(tmp); + mkdirSync(join(tmp, ".gsd", "milestones", "M003"), { recursive: true }); + + executeBacktrack(tmp, "M005", { + id: "CAP-abc", + text: "go back to M003", + timestamp: new Date().toISOString(), + status: "resolved", + classification: "backtrack", + resolution: "Backtrack to M003", + rationale: "Regression", + }); + + const trigger = readBacktrackTrigger(tmp); + assert.ok(trigger); + assert.equal(trigger.target, "M003"); + assert.equal(trigger.from, "M005"); + rmSync(tmp, { recursive: true, force: true }); +}); + +test("readBacktrackTrigger returns null when no trigger exists", () => { + const tmp = makeTempDir("no-bt"); + setupGsdDir(tmp); + const trigger = readBacktrackTrigger(tmp); + assert.equal(trigger, null); + rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── Slice Skip Status (#3477) ────────────────────────────────────────────── + +test("isClosedStatus treats 'skipped' as closed", () => { + assert.equal(isClosedStatus("skipped"), true); + assert.equal(isClosedStatus("complete"), true); + assert.equal(isClosedStatus("done"), true); + assert.equal(isClosedStatus("pending"), false); + assert.equal(isClosedStatus("active"), false); +}); diff --git a/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts b/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts new file mode 100644 index 000000000..992e6375b --- /dev/null +++ b/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts @@ -0,0 +1,217 @@ +// GSD State Machine Regression Tests — Stuck Detection Coverage (#3161) + +import test from "node:test"; +import assert from "node:assert/strict"; + +import { detectStuck } from "../auto/detect-stuck.ts"; + +// ─── Baseline: window too small ────────────────────────────────────────────── + +test("returns null for empty window", () => { + assert.equal(detectStuck([]), null); +}); + +test("returns null for single entry", () => { + assert.equal(detectStuck([{ key: "A" }]), null); +}); + +test("returns null for two different entries without errors", () => { + assert.equal(detectStuck([{ key: "A" }, { key: "B" }]), null); +}); + +// ─── Rule 1: Same error repeated consecutively ─────────────────────────────── + +test("Rule 1: same error twice consecutively triggers stuck", () => { + const result = detectStuck([ + { key: "A", error: "ENOENT: no such file" }, + { key: "A", error: "ENOENT: no such file" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok(result!.reason.includes("Same error"), `reason was: ${result!.reason}`); +}); + +test("Rule 1: different errors do not trigger stuck", () => { + // Only 2 entries with different errors — Rule 2 needs 3 entries, so null. + const result = detectStuck([ + { key: "A", error: "err1" }, + { key: "A", error: "err2" }, + ]); + assert.equal(result, null); +}); + +test("Rule 1: only last two entries matter for error check", () => { + // First two share an error, but the last two have distinct errors — no trigger. + const result = detectStuck([ + { key: "A", error: "same-error" }, + { key: "A", error: "same-error" }, + { key: "B", error: "different-error-1" }, + { key: "C", error: "different-error-2" }, + ]); + assert.equal(result, null); +}); + +// ─── Rule 2: Same unit key 3+ consecutive times ─────────────────────────────── + +test("Rule 2: same unit key 3 consecutive times triggers stuck", () => { + const result = detectStuck([ + { key: "A" }, + { key: "A" }, + { key: "A" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok( + result!.reason.includes("3 consecutive times"), + `reason was: ${result!.reason}`, + ); +}); + +test("Rule 2: same key twice is not enough", () => { + assert.equal(detectStuck([{ key: "A" }, { key: "A" }]), null); +}); + +test("Rule 2: interrupted sequence does not trigger", () => { + // A, B, A — last three are not all the same key. + assert.equal( + detectStuck([{ key: "A" }, { key: "B" }, { key: "A" }]), + null, + ); +}); + +// ─── Rule 3: Oscillation A→B→A→B ───────────────────────────────────────────── + +test("Rule 3: A-B-A-B oscillation triggers stuck", () => { + const result = detectStuck([ + { key: "A" }, + { key: "B" }, + { key: "A" }, + { key: "B" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok( + result!.reason.includes("Oscillation"), + `reason was: ${result!.reason}`, + ); +}); + +test("Rule 3: A-B-A-C does not trigger oscillation", () => { + assert.equal( + detectStuck([{ key: "A" }, { key: "B" }, { key: "A" }, { key: "C" }]), + null, + ); +}); + +test("Rule 3: A-A-A-A triggers Rule 2 not Rule 3", () => { + // Rule 2 fires first (last 3 are all the same key). + const result = detectStuck([ + { key: "A" }, + { key: "A" }, + { key: "A" }, + { key: "A" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok( + result!.reason.includes("3 consecutive times"), + `expected Rule 2 reason but got: ${result!.reason}`, + ); + assert.ok( + !result!.reason.includes("Oscillation"), + `unexpectedly matched Rule 3: ${result!.reason}`, + ); +}); + +// ─── Rule 4: ENOENT same path twice in window (#3575) ─────────────────────── + +test("Rule 4: same ENOENT path in two entries triggers stuck", () => { + const result = detectStuck([ + { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" }, + { key: "B" }, + { key: "A", error: "ENOENT: no such file or directory, access '/home/user/.gsd/agent/skills/debug-like-expert/SKILL.md'" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok(result!.reason.includes("Missing file"), `reason was: ${result!.reason}`); + assert.ok(result!.reason.includes("ENOENT"), `reason was: ${result!.reason}`); +}); + +test("Rule 4: different ENOENT paths do not trigger stuck", () => { + const result = detectStuck([ + { key: "A", error: "ENOENT: no such file or directory, access '/path/a'" }, + { key: "B", error: "ENOENT: no such file or directory, access '/path/b'" }, + ]); + assert.equal(result, null); +}); + +test("Rule 4: single ENOENT does not trigger stuck", () => { + const result = detectStuck([ + { key: "A", error: "ENOENT: no such file or directory, access '/path/a'" }, + { key: "B" }, + ]); + assert.equal(result, null); +}); + +test("Rule 4: ENOENT paths non-consecutive still triggers", () => { + const result = detectStuck([ + { key: "A", error: "ENOENT: no such file or directory, access '/missing/skill'" }, + { key: "B" }, + { key: "C" }, + { key: "D", error: "ENOENT: no such file or directory, access '/missing/skill'" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok(result!.reason.includes("/missing/skill"), `reason was: ${result!.reason}`); +}); + + +// ─── Gap documentation: 3-unit cycle evades detection ──────────────────────── + +test("Three-unit cycle A-B-C-A-B-C does NOT trigger stuck (documents gap L13)", () => { + // None of the three rules fires for a 3-unit repeating cycle. + // This test intentionally documents the coverage gap where such cycles + // slip through undetected (#3161). + const result = detectStuck([ + { key: "A" }, + { key: "B" }, + { key: "C" }, + { key: "A" }, + { key: "B" }, + { key: "C" }, + ]); + assert.equal(result, null); +}); + +// ─── Window boundary: earlier patterns do not contaminate recent check ───────── + +test("window bounded: detection uses last N entries correctly", () => { + // The first three entries would trigger Rule 2, but the last entries are + // healthy — only the tail matters. + const result = detectStuck([ + { key: "X" }, + { key: "X" }, + { key: "X" }, // would be stuck if this were the end + { key: "A" }, + { key: "B" }, // last two: different keys, no error + ]); + assert.equal(result, null); +}); + +// ─── Rule priority: Rule 1 before Rule 2 ───────────────────────────────────── + +test("Rule 1 takes priority over Rule 2 when both match", () => { + // Last 3 entries share the same key (Rule 2 candidate) AND last 2 share + // the same error (Rule 1 candidate). Rule 1 is evaluated first. + const result = detectStuck([ + { key: "A", error: "boom" }, + { key: "A", error: "boom" }, + { key: "A", error: "boom" }, + ]); + assert.notEqual(result, null); + assert.equal(result!.stuck, true); + assert.ok( + result!.reason.includes("Same error"), + `expected Rule 1 reason but got: ${result!.reason}`, + ); +}); diff --git a/src/resources/extensions/gsd/tests/subagent-agent-discovery.test.ts b/src/resources/extensions/gsd/tests/subagent-agent-discovery.test.ts index 14cf587e5..5d8a6bd12 100644 --- a/src/resources/extensions/gsd/tests/subagent-agent-discovery.test.ts +++ b/src/resources/extensions/gsd/tests/subagent-agent-discovery.test.ts @@ -42,3 +42,50 @@ test("discoverAgents falls back to legacy .pi/agents when needed", (t) => { assert.equal(discovery.projectAgentsDir, agentsDir); assert.deepEqual(discovery.agents.map((agent) => agent.name), ["ping"]); }); + +test("discoverAgents accepts tools frontmatter as a YAML list", (t) => { + const root = makeProjectRoot(t); + const agentsDir = join(root, ".gsd", "agents"); + mkdirSync(agentsDir, { recursive: true }); + writeFileSync( + join(agentsDir, "reviewer.md"), + [ + "---", + "name: reviewer", + "description: review agent", + "tools:", + " - bash", + " - read", + "---", + "Review code", + "", + ].join("\n"), + ); + + const discovery = discoverAgents(root, "project"); + + assert.deepEqual(discovery.agents.map((agent) => agent.name), ["reviewer"]); + assert.deepEqual(discovery.agents[0]?.tools, ["bash", "read"]); +}); + +test("discoverAgents still accepts comma-separated tools frontmatter", (t) => { + const root = makeProjectRoot(t); + const agentsDir = join(root, ".gsd", "agents"); + mkdirSync(agentsDir, { recursive: true }); + writeFileSync( + join(agentsDir, "reviewer.md"), + [ + "---", + "name: reviewer", + "description: review agent", + "tools: bash, read", + "---", + "Review code", + "", + ].join("\n"), + ); + + const discovery = discoverAgents(root, "project"); + + assert.deepEqual(discovery.agents[0]?.tools, ["bash", "read"]); +}); diff --git a/src/resources/extensions/gsd/tests/summary-render-parity.test.ts b/src/resources/extensions/gsd/tests/summary-render-parity.test.ts new file mode 100644 index 000000000..ffd4fc955 --- /dev/null +++ b/src/resources/extensions/gsd/tests/summary-render-parity.test.ts @@ -0,0 +1,221 @@ +/** + * summary-render-parity.test.ts — Regression test for #2720 + * + * Asserts that the SUMMARY.md produced at task-completion time + * (renderSummaryMarkdown in complete-task.ts) is structurally identical + * to the SUMMARY.md produced at projection-regeneration time + * (renderSummaryContent in workflow-projections.ts). + * + * Both render paths receive equivalent data (CompleteTaskParams vs TaskRow) + * and must produce the same output. If they diverge, projection regeneration + * silently replaces richer content with a stripped-down version. + */ + +import { createTestContext } from './test-helpers.ts'; +import { renderSummaryContent } from '../workflow-projections.ts'; +import type { TaskRow } from '../gsd-db.ts'; + +const { assertEq, assertTrue, report } = createTestContext(); + +// ═══════════════════════════════════════════════════════════════════════════ +// Fixtures — same logical data in both shapes +// ═══════════════════════════════════════════════════════════════════════════ + +const SLICE_ID = "S01"; +const MILESTONE_ID = "M001"; + +const taskRow: TaskRow = { + milestone_id: MILESTONE_ID, + slice_id: SLICE_ID, + id: "T01", + title: "Implement widget parser", + status: "complete", + one_liner: "Implement widget parser", + narrative: "Added a recursive descent parser for widget DSL.", + verification_result: "All 42 unit tests pass; linter clean.", + duration: "2h", + completed_at: "2025-01-15T10:30:00.000Z", + blocker_discovered: false, + deviations: "Switched from PEG to hand-rolled parser for perf.", + known_issues: "No known issues.", + key_files: ["src/parser.ts", "src/lexer.ts"], + key_decisions: ["Hand-rolled parser over PEG for 3x throughput"], + full_summary_md: "", + description: "", + estimate: "", + files: [], + verify: "", + inputs: [], + expected_output: [], + observability_impact: "", + full_plan_md: "", + sequence: 1, +}; + +const verificationEvidence = [ + { command: "npm test", exitCode: 0, verdict: "42/42 passed ✅", durationMs: 3200 }, + { command: "npm run lint", exitCode: 0, verdict: "No warnings ✅", durationMs: 1100 }, +]; + +// ═══════════════════════════════════════════════════════════════════════════ +// Tests +// ═══════════════════════════════════════════════════════════════════════════ + +// Test 1: renderSummaryContent includes Verification section +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("## Verification"), + "renderSummaryContent must include a ## Verification section", + ); +} + +// Test 2: renderSummaryContent includes Verification Evidence table +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID, verificationEvidence); + assertTrue( + output.includes("## Verification Evidence"), + "renderSummaryContent must include a ## Verification Evidence section", + ); + assertTrue( + output.includes("npm test"), + "Verification Evidence table must include the command", + ); + assertTrue( + output.includes("| Exit Code |") || output.includes("exit_code") || output.includes("Exit Code"), + "Verification Evidence table must include exit code column", + ); +} + +// Test 3: renderSummaryContent includes Files Created/Modified section +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("## Files Created/Modified"), + "renderSummaryContent must include a ## Files Created/Modified section", + ); + assertTrue( + output.includes("`src/parser.ts`"), + "Files section must list key_files as inline code", + ); +} + +// Test 4: one_liner renders as bold (not blockquote) for consistency +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes(`**${taskRow.one_liner}**`), + "one_liner must render as bold text (not blockquote)", + ); +} + +// Test 5: frontmatter key_files uses YAML list format (not JSON array) +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("key_files:\n - src/parser.ts\n - src/lexer.ts"), + "key_files frontmatter must use YAML list format, not JSON array", + ); +} + +// Test 6: frontmatter key_decisions uses YAML list format (not JSON array) +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("key_decisions:\n - Hand-rolled parser over PEG for 3x throughput"), + "key_decisions frontmatter must use YAML list format, not JSON array", + ); +} + +// Test 7: Deviations section always present (with "None." fallback) +{ + const noDeviations = { ...taskRow, deviations: "" }; + const output = renderSummaryContent(noDeviations, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("## Deviations"), + "Deviations section must always be present even when empty", + ); + assertTrue( + output.includes("None."), + "Deviations section must show 'None.' when no deviations", + ); +} + +// Test 8: Known Issues section always present (with "None." fallback) +{ + const noKnownIssues = { ...taskRow, known_issues: "" }; + const output = renderSummaryContent(noKnownIssues, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("## Known Issues"), + "Known Issues section must always be present even when empty", + ); +} + +// Test 9: verification_result frontmatter not double-quoted +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + // Should be: verification_result: passed (not "passed") + assertTrue( + !output.includes('verification_result: "'), + "verification_result frontmatter value must not be double-quoted", + ); +} + +// Test 10: duration frontmatter not double-quoted +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + !output.includes('duration: "'), + "duration frontmatter value must not be double-quoted", + ); +} + +// Test 11: empty key_files renders YAML placeholder, not empty array +{ + const noFiles = { ...taskRow, key_files: [] }; + const output = renderSummaryContent(noFiles, SLICE_ID, MILESTONE_ID); + assertTrue( + output.includes("key_files:\n - (none)"), + "empty key_files must render as YAML list with (none) placeholder", + ); +} + +// Test 12: frontmatter does not contain extra projection-only fields +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID); + assertTrue( + !output.includes("provides:"), + "frontmatter must not contain provides field", + ); + assertTrue( + !output.includes("requires:"), + "frontmatter must not contain requires field", + ); + assertTrue( + !output.includes("affects:"), + "frontmatter must not contain affects field", + ); + assertTrue( + !output.includes("patterns_established:"), + "frontmatter must not contain patterns_established field", + ); + assertTrue( + !output.includes("drill_down_paths:"), + "frontmatter must not contain drill_down_paths field", + ); + assertTrue( + !output.includes("observability_surfaces:"), + "frontmatter must not contain observability_surfaces field", + ); +} + +// Test 13: no verification evidence renders empty table row +{ + const output = renderSummaryContent(taskRow, SLICE_ID, MILESTONE_ID, []); + assertTrue( + output.includes("No verification commands discovered"), + "Empty evidence array must render placeholder row", + ); +} + +report(); diff --git a/src/resources/extensions/gsd/tests/symlink-extension-discovery.test.ts b/src/resources/extensions/gsd/tests/symlink-extension-discovery.test.ts new file mode 100644 index 000000000..a420b679b --- /dev/null +++ b/src/resources/extensions/gsd/tests/symlink-extension-discovery.test.ts @@ -0,0 +1,125 @@ +// Regression test for: discoverManifests() skips symlinked extension directories +// +// The bug: Dirent.isDirectory() returns false for symlinks, so extensions installed +// as directory symlinks under ~/.gsd/agent/extensions/ were invisible to all +// management commands (list, enable, disable, info). +// +// The fix: check `entry.isDirectory() || entry.isSymbolicLink()`, matching the +// pattern already used in loader.ts discoverExtensionsInDir(). + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + symlinkSync, + readdirSync, + existsSync, + rmSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +// Inline the discovery logic so the test is self-contained and can verify both +// the buggy and fixed behaviour without importing the private function. +function discoverManifestsBuggy(extDir: string): string[] { + const found: string[] = []; + if (!existsSync(extDir)) return found; + for (const entry of readdirSync(extDir, { withFileTypes: true })) { + if (!entry.isDirectory()) continue; // BUG: skips symlinks + const mPath = join(extDir, entry.name, "extension-manifest.json"); + if (existsSync(mPath)) found.push(entry.name); + } + return found; +} + +function discoverManifestsFixed(extDir: string): string[] { + const found: string[] = []; + if (!existsSync(extDir)) return found; + for (const entry of readdirSync(extDir, { withFileTypes: true })) { + if (!entry.isDirectory() && !entry.isSymbolicLink()) continue; // FIX + const mPath = join(extDir, entry.name, "extension-manifest.json"); + if (existsSync(mPath)) found.push(entry.name); + } + return found; +} + +const MANIFEST = JSON.stringify({ + id: "test-ext", + name: "Test Extension", + version: "1.0.0", + description: "A test extension", + tier: "community", + requires: { platform: "linux" }, +}); + +describe("symlink extension discovery", () => { + let tmp: string; + let extDir: string; + let realExtDir: string; + + beforeEach(() => { + tmp = mkdtempSync(join(tmpdir(), "gsd-ext-test-")); + extDir = join(tmp, "agent", "extensions"); + realExtDir = join(tmp, "my-ext-source"); + + // Create the real extension directory outside extDir (simulates a dev checkout) + mkdirSync(realExtDir, { recursive: true }); + writeFileSync(join(realExtDir, "extension-manifest.json"), MANIFEST, "utf-8"); + + // Create the extensions scan directory + mkdirSync(extDir, { recursive: true }); + }); + + afterEach(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + test("real directory is discovered by both implementations", () => { + // Install extension as a real directory copy + const realCopy = join(extDir, "my-ext"); + mkdirSync(realCopy); + writeFileSync(join(realCopy, "extension-manifest.json"), MANIFEST, "utf-8"); + + assert.deepEqual(discoverManifestsBuggy(extDir), ["my-ext"]); + assert.deepEqual(discoverManifestsFixed(extDir), ["my-ext"]); + }); + + test("symlinked directory is missed by buggy implementation", () => { + // Install extension as a directory symlink — the common dev workflow + symlinkSync(realExtDir, join(extDir, "my-ext")); + + // Buggy: symlink is invisible + assert.deepEqual(discoverManifestsBuggy(extDir), []); + }); + + test("symlinked directory is discovered by fixed implementation", () => { + symlinkSync(realExtDir, join(extDir, "my-ext")); + + // Fixed: symlink is visible + assert.deepEqual(discoverManifestsFixed(extDir), ["my-ext"]); + }); + + test("non-manifest symlinks are ignored", () => { + // Symlink to a dir that has no manifest — should not appear + const noManifestDir = join(tmp, "no-manifest"); + mkdirSync(noManifestDir); + symlinkSync(noManifestDir, join(extDir, "no-manifest")); + + assert.deepEqual(discoverManifestsFixed(extDir), []); + }); + + test("mix of real dirs and symlinks are all discovered", () => { + // Real dir + const realCopy = join(extDir, "ext-real"); + mkdirSync(realCopy); + writeFileSync(join(realCopy, "extension-manifest.json"), MANIFEST, "utf-8"); + + // Symlink dir + symlinkSync(realExtDir, join(extDir, "ext-symlink")); + + const found = discoverManifestsFixed(extDir).sort(); + assert.deepEqual(found, ["ext-real", "ext-symlink"]); + }); +}); diff --git a/src/resources/extensions/gsd/tests/sync-worktree-skip-current.test.ts b/src/resources/extensions/gsd/tests/sync-worktree-skip-current.test.ts new file mode 100644 index 000000000..9b0070cb1 --- /dev/null +++ b/src/resources/extensions/gsd/tests/sync-worktree-skip-current.test.ts @@ -0,0 +1,65 @@ +/** + * Regression test for #3641 — syncWorktreeStateBack skips current milestone + * + * When syncing worktree state back to main, the current milestone being + * merged should be skipped. Its files are already in the milestone branch + * and copying them back would conflict with the squash merge. + * + * The fix adds a `mid === milestoneId` skip guard inside the milestone + * iteration loop in syncWorktreeStateBack. + */ + +import { describe, it } from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' + +const src = readFileSync( + resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'auto-worktree.ts'), + 'utf-8', +) + +describe('syncWorktreeStateBack skips current milestone (#3641)', () => { + it('syncWorktreeStateBack function exists', () => { + assert.ok( + src.includes('function syncWorktreeStateBack('), + 'syncWorktreeStateBack function must be defined', + ) + }) + + it('mid === milestoneId skip guard exists in the milestone loop', () => { + // Find syncWorktreeStateBack + const fnStart = src.indexOf('function syncWorktreeStateBack(') + assert.ok(fnStart !== -1) + + // Get a reasonable portion of the function + const fnBlock = src.slice(fnStart, fnStart + 3000) + + // Find the for loop iterating milestones + const loopIdx = fnBlock.indexOf('for (const mid of wtMilestones)') + assert.ok(loopIdx !== -1, 'milestone iteration loop must exist') + + // After the loop, there should be the skip guard + const loopBody = fnBlock.slice(loopIdx, loopIdx + 300) + assert.ok( + loopBody.includes('mid === milestoneId'), + 'mid === milestoneId skip guard must exist inside the milestone loop', + ) + assert.ok( + loopBody.includes('continue'), + 'skip guard must use continue to skip the current milestone', + ) + }) + + it('syncMilestoneDir is still called for non-current milestones', () => { + const fnStart = src.indexOf('function syncWorktreeStateBack(') + assert.ok(fnStart !== -1) + + const fnBlock = src.slice(fnStart, fnStart + 3000) + + assert.ok( + fnBlock.includes('syncMilestoneDir('), + 'syncMilestoneDir must still be called for other milestones', + ) + }) +}) diff --git a/src/resources/extensions/gsd/tests/terminated-transient.test.ts b/src/resources/extensions/gsd/tests/terminated-transient.test.ts index f15223f60..84c0c8db0 100644 --- a/src/resources/extensions/gsd/tests/terminated-transient.test.ts +++ b/src/resources/extensions/gsd/tests/terminated-transient.test.ts @@ -82,3 +82,47 @@ test("#2572: 'SyntaxError' with JSON context (truncated stream) is transient", ( assert.equal(isTransient(result), true, "'SyntaxError...JSON' should be transient"); assert.equal(result.kind, "stream", "JSON parse errors are stream kind"); }); + +// --- Catch-all: all V8 JSON.parse variants matched by "in JSON at position" --- + +test("V8 JSON.parse: 'No number after minus sign in JSON' is transient (#2882)", () => { + const result = classifyError("No number after minus sign in JSON at position 42"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse: 'Expected property value after colon' is transient", () => { + const result = classifyError("Expected ',' or '}' after property value in JSON at position 108"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse: 'Bad control character in string literal' is transient", () => { + const result = classifyError("Bad control character in string literal in JSON at position 5"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse: 'Bad escaped character' is transient", () => { + const result = classifyError("Bad escaped character in JSON at position 17"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse: 'Unexpected number' is transient", () => { + const result = classifyError("Unexpected number in JSON at position 0"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse: 'Unexpected string' is transient", () => { + const result = classifyError("Unexpected string in JSON at position 12"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); + +test("V8 JSON.parse with line/column suffix is transient", () => { + const result = classifyError("Unexpected token x in JSON at position 99 (line 3 column 14)"); + assert.equal(isTransient(result), true); + assert.equal(result.kind, "stream"); +}); diff --git a/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts b/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts index c1fcecd2c..ab82b3a5e 100644 --- a/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts +++ b/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts @@ -136,17 +136,30 @@ console.log('\n── Loop guard: nested args are not stripped ──'); assert.deepStrictEqual(getToolCallLoopCount(), 1, `Each unique nested call should reset count to 1`); } - // Truly identical nested calls should still be detected + // Truly identical nested calls should still be detected. + // ask_user_questions has a strict threshold of 1, so the 2nd identical call is blocked. resetToolCallLoopGuard(); - for (let i = 1; i <= 4; i++) { - checkToolCallLoop('ask_user_questions', { - questions: [{ id: 'same', question: 'Same?' }], - }); - } + const first = checkToolCallLoop('ask_user_questions', { + questions: [{ id: 'same', question: 'Same?' }], + }); + assert.ok(first.block === false, 'First ask_user_questions call should be allowed'); const blocked = checkToolCallLoop('ask_user_questions', { questions: [{ id: 'same', question: 'Same?' }], }); - assert.ok(blocked.block === true, 'Identical nested calls should still be blocked'); + assert.ok(blocked.block === true, '2nd identical ask_user_questions call should be blocked (strict threshold)'); + + // Non-strict tools still allow up to 4 identical calls + resetToolCallLoopGuard(); + for (let i = 1; i <= 4; i++) { + const r = checkToolCallLoop('web_search', { + questions: [{ id: 'same', question: 'Same?' }], + }); + assert.ok(r.block === false, `web_search call ${i} should be allowed (normal threshold)`); + } + const blockedNormal = checkToolCallLoop('web_search', { + questions: [{ id: 'same', question: 'Same?' }], + }); + assert.ok(blockedNormal.block === true, '5th identical web_search call should be blocked'); } // ═══════════════════════════════════════════════════════════════════════════ diff --git a/src/resources/extensions/gsd/tests/tool-compatibility.test.ts b/src/resources/extensions/gsd/tests/tool-compatibility.test.ts new file mode 100644 index 000000000..6b533bf63 --- /dev/null +++ b/src/resources/extensions/gsd/tests/tool-compatibility.test.ts @@ -0,0 +1,199 @@ +// GSD-2 — Tool Compatibility + Model Router Tool Filtering Tests (ADR-005 Phases 2-3) +import { describe, test, beforeEach } from "node:test"; +import assert from "node:assert/strict"; + +import { + registerToolCompatibility, + getToolCompatibility, + getAllToolCompatibility, + registerMcpToolCompatibility, + resetToolCompatibilityRegistry, +} from "@gsd/pi-coding-agent"; + +import { + isToolCompatibleWithProvider, + filterToolsForProvider, + adjustToolSet, +} from "../model-router.js"; + +import { + getProviderCapabilities, +} from "@gsd/pi-ai"; + +// ─── Tool Compatibility Registry ──────────────────────────────────────────── + +describe("tool compatibility registry", () => { + beforeEach(() => { + resetToolCompatibilityRegistry(); + }); + + test("built-in tools are pre-registered", () => { + const builtins = ["bash", "read", "write", "edit", "grep", "find", "ls", "lsp"]; + for (const name of builtins) { + const compat = getToolCompatibility(name); + assert.ok(compat !== undefined, `${name} should be pre-registered`); + } + }); + + test("unknown tool returns undefined", () => { + assert.equal(getToolCompatibility("nonexistent_tool_xyz"), undefined); + }); + + test("registerToolCompatibility stores and retrieves metadata", () => { + registerToolCompatibility("screenshot_tool", { + producesImages: true, + minCapabilityTier: "standard", + }); + const compat = getToolCompatibility("screenshot_tool"); + assert.ok(compat); + assert.equal(compat.producesImages, true); + assert.equal(compat.minCapabilityTier, "standard"); + }); + + test("registerMcpToolCompatibility sets default schema features", () => { + registerMcpToolCompatibility("mcp__test__tool"); + const compat = getToolCompatibility("mcp__test__tool"); + assert.ok(compat); + assert.ok(compat.schemaFeatures?.includes("patternProperties")); + }); + + test("registerMcpToolCompatibility allows overrides", () => { + registerMcpToolCompatibility("mcp__test__override", { producesImages: true }); + const compat = getToolCompatibility("mcp__test__override"); + assert.ok(compat); + assert.equal(compat.producesImages, true); + assert.ok(compat.schemaFeatures?.includes("patternProperties")); + }); + + test("getAllToolCompatibility returns all entries", () => { + const all = getAllToolCompatibility(); + assert.ok(all.size >= 10); // at least built-in tools + assert.ok(all.has("bash")); + assert.ok(all.has("read")); + }); + + test("resetToolCompatibilityRegistry clears custom entries but keeps builtins", () => { + registerToolCompatibility("custom_tool", { producesImages: true }); + assert.ok(getToolCompatibility("custom_tool")); + resetToolCompatibilityRegistry(); + assert.equal(getToolCompatibility("custom_tool"), undefined); + assert.ok(getToolCompatibility("bash")); // built-in preserved + }); +}); + +// ─── isToolCompatibleWithProvider ─────────────────────────────────────────── + +describe("isToolCompatibleWithProvider", () => { + beforeEach(() => { + resetToolCompatibilityRegistry(); + }); + + test("tool without compatibility metadata is always compatible", () => { + const caps = getProviderCapabilities("anthropic-messages"); + assert.equal(isToolCompatibleWithProvider("unknown_tool", caps), true); + }); + + test("built-in tools are compatible with all providers", () => { + const providers = ["anthropic-messages", "openai-responses", "google-generative-ai", "mistral-conversations"]; + const tools = ["bash", "read", "write", "edit"]; + for (const api of providers) { + const caps = getProviderCapabilities(api); + for (const tool of tools) { + assert.equal( + isToolCompatibleWithProvider(tool, caps), + true, + `${tool} should be compatible with ${api}`, + ); + } + } + }); + + test("image-producing tool filtered for providers without image support", () => { + registerToolCompatibility("screenshot", { producesImages: true }); + const openaiCaps = getProviderCapabilities("openai-responses"); + assert.equal(isToolCompatibleWithProvider("screenshot", openaiCaps), false); + + const anthropicCaps = getProviderCapabilities("anthropic-messages"); + assert.equal(isToolCompatibleWithProvider("screenshot", anthropicCaps), true); + }); + + test("tool with unsupported schema features filtered for Google", () => { + registerToolCompatibility("complex_schema_tool", { + schemaFeatures: ["patternProperties"], + }); + const googleCaps = getProviderCapabilities("google-generative-ai"); + assert.equal(isToolCompatibleWithProvider("complex_schema_tool", googleCaps), false); + + const anthropicCaps = getProviderCapabilities("anthropic-messages"); + assert.equal(isToolCompatibleWithProvider("complex_schema_tool", anthropicCaps), true); + }); +}); + +// ─── filterToolsForProvider ───────────────────────────────────────────────── + +describe("filterToolsForProvider", () => { + beforeEach(() => { + resetToolCompatibilityRegistry(); + }); + + test("all built-in tools pass for any provider", () => { + const toolNames = ["bash", "read", "write", "edit", "grep", "find", "ls"]; + const { compatible, filtered } = filterToolsForProvider(toolNames, "mistral-conversations"); + assert.deepEqual(compatible, toolNames); + assert.deepEqual(filtered, []); + }); + + test("image tool filtered for OpenAI Responses", () => { + registerToolCompatibility("browser_screenshot", { producesImages: true }); + const toolNames = ["bash", "read", "browser_screenshot"]; + const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-responses"); + assert.deepEqual(compatible, ["bash", "read"]); + assert.deepEqual(filtered, ["browser_screenshot"]); + }); + + test("MCP tool with patternProperties filtered for Google", () => { + registerMcpToolCompatibility("mcp__repowise__search"); + const toolNames = ["bash", "read", "mcp__repowise__search"]; + const { compatible, filtered } = filterToolsForProvider(toolNames, "google-generative-ai"); + assert.deepEqual(compatible, ["bash", "read"]); + assert.deepEqual(filtered, ["mcp__repowise__search"]); + }); + + test("unknown provider passes all tools (permissive default)", () => { + registerToolCompatibility("image_tool", { producesImages: true }); + registerMcpToolCompatibility("mcp_tool"); + const toolNames = ["bash", "image_tool", "mcp_tool"]; + const { compatible, filtered } = filterToolsForProvider(toolNames, "unknown-provider-xyz"); + assert.deepEqual(compatible, toolNames); + assert.deepEqual(filtered, []); + }); +}); + +// ─── adjustToolSet ────────────────────────────────────────────────────────── + +describe("adjustToolSet", () => { + beforeEach(() => { + resetToolCompatibilityRegistry(); + }); + + test("returns all tools for Anthropic (most permissive)", () => { + registerToolCompatibility("screenshot", { producesImages: true }); + const toolNames = ["bash", "read", "screenshot"]; + const { toolNames: result, removedTools } = adjustToolSet(toolNames, "anthropic-messages"); + assert.deepEqual(result, toolNames); + assert.deepEqual(removedTools, []); + }); + + test("removes incompatible tools and reports them", () => { + registerToolCompatibility("screenshot", { producesImages: true }); + registerMcpToolCompatibility("mcp_complex"); + const toolNames = ["bash", "read", "screenshot", "mcp_complex"]; + const { toolNames: result, removedTools } = adjustToolSet(toolNames, "google-generative-ai"); + // Google supports images but not patternProperties + assert.ok(result.includes("bash")); + assert.ok(result.includes("read")); + assert.ok(result.includes("screenshot")); // Google supports images + assert.ok(!result.includes("mcp_complex")); // patternProperties not supported + assert.deepEqual(removedTools, ["mcp_complex"]); + }); +}); diff --git a/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts b/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts new file mode 100644 index 000000000..c802e91a5 --- /dev/null +++ b/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts @@ -0,0 +1,138 @@ +/** + * Regression tests for #2883: gsd_complete_slice tool invocation fails with + * JSON truncation, causing stuck retry loop. + * + * When a GSD tool is invoked with malformed/truncated JSON arguments, the tool + * execution fails (isError: true). But postUnitPreVerification only checks if + * the expected artifact exists on disk — it does not know the tool itself failed. + * When the artifact is missing (because the tool never ran), it sets up + * pendingVerificationRetry, re-dispatching the same unit with the same truncated + * input, creating a stuck loop. + * + * The fix adds a `lastToolInvocationError` field to AutoSession. When a GSD tool + * execution ends with isError, the error is recorded. postUnitPreVerification + * checks this field before retrying — if a tool invocation error occurred, it + * pauses auto-mode instead of retrying. + */ +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { AutoSession } from "../auto/session.ts"; + +// ─── AutoSession.lastToolInvocationError field ─────────────────────────── + +describe("#2883: tool invocation error tracking on AutoSession", () => { + test("lastToolInvocationError defaults to null", () => { + const s = new AutoSession(); + assert.equal(s.lastToolInvocationError, null); + }); + + test("lastToolInvocationError is cleared on reset()", () => { + const s = new AutoSession(); + s.lastToolInvocationError = "Validation failed for tool gsd_complete_slice"; + assert.ok(s.lastToolInvocationError); + s.reset(); + assert.equal(s.lastToolInvocationError, null); + }); + + test("lastToolInvocationError can store truncated JSON error", () => { + const s = new AutoSession(); + const errorMsg = "Expected ',' or '}' in JSON at position 4096"; + s.lastToolInvocationError = errorMsg; + assert.equal(s.lastToolInvocationError, errorMsg); + }); +}); + +// ─── isToolInvocationError classifier ──────────────────────────────────── + +import { isToolInvocationError, isQueuedUserMessageSkip } from "../auto-tool-tracking.ts"; + +describe("#2883: isToolInvocationError classification", () => { + test("detects JSON validation failure pattern", () => { + assert.equal( + isToolInvocationError("Validation failed for tool gsd_complete_slice: Expected ',' or '}' in JSON"), + true, + ); + }); + + test("detects truncated JSON parse error", () => { + assert.equal( + isToolInvocationError("Expected ',' or '}' in JSON at position 4096"), + true, + ); + }); + + test("detects Node v18+ JSON parse variant with property-value text", () => { + assert.equal( + isToolInvocationError("Expected ',' or '}' after property value in JSON at position 4096"), + true, + ); + }); + + test("detects Unexpected end of JSON input", () => { + assert.equal( + isToolInvocationError("Unexpected end of JSON input"), + true, + ); + }); + + test("detects Unexpected token in JSON", () => { + assert.equal( + isToolInvocationError("Unexpected token < in JSON at position 0"), + true, + ); + }); + + test("detects 'Validation failed for tool' prefix", () => { + assert.equal( + isToolInvocationError("Validation failed for tool gsd_slice_complete"), + true, + ); + }); + + test("returns false for normal tool errors (business logic)", () => { + assert.equal( + isToolInvocationError("Slice S01 is already complete"), + false, + ); + }); + + test("returns false for empty string", () => { + assert.equal(isToolInvocationError(""), false); + }); + + test("returns false for generic error", () => { + assert.equal(isToolInvocationError("Something went wrong"), false); + }); + + test("returns false for network errors (handled elsewhere)", () => { + assert.equal(isToolInvocationError("ECONNRESET"), false); + }); +}); + +// ─── isQueuedUserMessageSkip classifier (#3595) ───────────────────────── + +describe("#3595: isQueuedUserMessageSkip classification", () => { + test("detects exact skip message with period", () => { + assert.equal(isQueuedUserMessageSkip("Skipped due to queued user message."), true); + }); + + test("detects skip message without period", () => { + assert.equal(isQueuedUserMessageSkip("Skipped due to queued user message"), true); + }); + + test("detects skip message with surrounding whitespace", () => { + assert.equal(isQueuedUserMessageSkip(" Skipped due to queued user message. "), true); + }); + + test("returns false for normal tool errors", () => { + assert.equal(isQueuedUserMessageSkip("Slice S01 is already complete"), false); + }); + + test("returns false for empty string", () => { + assert.equal(isQueuedUserMessageSkip(""), false); + }); + + test("returns false for partial match (substring)", () => { + assert.equal(isQueuedUserMessageSkip("Error: Skipped due to queued user message. Retry later."), false); + }); +}); diff --git a/src/resources/extensions/gsd/tests/tool-naming.test.ts b/src/resources/extensions/gsd/tests/tool-naming.test.ts index 772a4eed6..a88fc8ac0 100644 --- a/src/resources/extensions/gsd/tests/tool-naming.test.ts +++ b/src/resources/extensions/gsd/tests/tool-naming.test.ts @@ -24,6 +24,7 @@ function makeMockPi() { const RENAME_MAP: Array<{ canonical: string; alias: string }> = [ { canonical: "gsd_decision_save", alias: "gsd_save_decision" }, { canonical: "gsd_requirement_update", alias: "gsd_update_requirement" }, + { canonical: "gsd_requirement_save", alias: "gsd_save_requirement" }, { canonical: "gsd_summary_save", alias: "gsd_save_summary" }, { canonical: "gsd_milestone_generate_id", alias: "gsd_generate_milestone_id" }, { canonical: "gsd_task_complete", alias: "gsd_complete_task" }, @@ -44,7 +45,7 @@ console.log('\n── Tool naming: registration count ──'); const pi = makeMockPi(); registerDbTools(pi); -assert.deepStrictEqual(pi.tools.length, 27, 'Should register exactly 27 tools (13 canonical + 13 aliases + 1 gate tool)'); +assert.deepStrictEqual(pi.tools.length, 30, 'Should register exactly 30 tools (14 canonical + 14 aliases + 1 gate tool + 1 gsd_skip_slice)'); // ─── Both names exist for each pair ────────────────────────────────────────── diff --git a/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts b/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts new file mode 100644 index 000000000..6521d1bda --- /dev/null +++ b/src/resources/extensions/gsd/tests/tool-param-optionality.test.ts @@ -0,0 +1,349 @@ +/** + * tool-param-optionality — Verifies that enrichment/metadata parameters on + * planning and completion tools are optional, not required. + * + * Models with limited tool-calling capability (e.g. kimi-k2.5, glm-5-turbo) + * cannot reliably populate 20+ top-level parameters in a single tool call. + * This test ensures that only the core identification and content parameters + * are required, while enrichment arrays (patterns, requirements, files, etc.) + * are optional — so any model can call the tool successfully. + * + * See: https://github.com/gsd-build/gsd-2/issues/2771 + */ + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { registerDbTools } from "../bootstrap/db-tools.ts"; +import { Value } from "@sinclair/typebox/value"; + +// ─── Mock PI ────────────────────────────────────────────────────────────────── + +function makeMockPi() { + const tools: any[] = []; + return { + registerTool: (tool: any) => tools.push(tool), + tools, + } as any; +} + +const pi = makeMockPi(); +registerDbTools(pi); + +function getTool(name: string) { + return pi.tools.find((t: any) => t.name === name); +} + +// ─── Helper: count required top-level properties ───────────────────────────── + +function getRequiredProps(tool: any): string[] { + const schema = tool.parameters; + return schema.required ?? []; +} + +function getOptionalProps(tool: any): string[] { + const schema = tool.parameters; + const allProps = Object.keys(schema.properties ?? {}); + const required = new Set(schema.required ?? []); + return allProps.filter((p: string) => !required.has(p)); +} + +// ─── gsd_slice_complete: enrichment arrays must be optional ────────────────── + +test("gsd_slice_complete — enrichment arrays are optional", () => { + const tool = getTool("gsd_slice_complete"); + assert.ok(tool, "gsd_slice_complete must be registered"); + + const required = new Set(getRequiredProps(tool)); + + // Core identification and content fields MUST be required + const coreRequired = [ + "sliceId", + "milestoneId", + "sliceTitle", + "oneLiner", + "narrative", + "verification", + "uatContent", + ]; + for (const field of coreRequired) { + assert.ok(required.has(field), `core field "${field}" must be required`); + } + + // Enrichment/metadata arrays MUST be optional + const enrichmentFields = [ + "keyFiles", + "keyDecisions", + "patternsEstablished", + "observabilitySurfaces", + "provides", + "requirementsSurfaced", + "drillDownPaths", + "affects", + "requirementsAdvanced", + "requirementsValidated", + "requirementsInvalidated", + "filesModified", + "requires", + "deviations", + "knownLimitations", + "followUps", + ]; + for (const field of enrichmentFields) { + assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`); + } +}); + +test("gsd_slice_complete — validates with only core params", () => { + const tool = getTool("gsd_slice_complete"); + assert.ok(tool, "gsd_slice_complete must be registered"); + + const minimalParams = { + sliceId: "S01", + milestoneId: "M001", + sliceTitle: "Test slice", + oneLiner: "Did the thing", + narrative: "We did it step by step.", + verification: "Tests pass.", + uatContent: "## UAT\n- [x] Works", + }; + + // Should pass schema validation with only core params + const errors = [...Value.Errors(tool.parameters, minimalParams)]; + assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`); +}); + +// ─── gsd_plan_milestone: enrichment arrays must be optional ────────────────── + +test("gsd_plan_milestone — enrichment arrays are optional", () => { + const tool = getTool("gsd_plan_milestone"); + assert.ok(tool, "gsd_plan_milestone must be registered"); + + const required = new Set(getRequiredProps(tool)); + + // Core fields + const coreRequired = ["milestoneId", "title", "vision", "slices"]; + for (const field of coreRequired) { + assert.ok(required.has(field), `core field "${field}" must be required`); + } + + // Enrichment fields must be optional + const enrichmentFields = [ + "successCriteria", + "keyRisks", + "proofStrategy", + "verificationContract", + "verificationIntegration", + "verificationOperational", + "verificationUat", + "definitionOfDone", + "requirementCoverage", + "boundaryMapMarkdown", + ]; + for (const field of enrichmentFields) { + assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`); + } +}); + +test("gsd_plan_milestone — validates with only core params", () => { + const tool = getTool("gsd_plan_milestone"); + assert.ok(tool, "gsd_plan_milestone must be registered"); + + const minimalParams = { + milestoneId: "M001", + title: "Test milestone", + vision: "Build the thing.", + slices: [ + { + sliceId: "S01", + title: "First slice", + risk: "Low", + depends: [], + demo: "After this, X works", + goal: "Set up X", + successCriteria: "X is set up", + proofLevel: "unit-tests", + integrationClosure: "N/A", + observabilityImpact: "None", + }, + ], + }; + + const errors = [...Value.Errors(tool.parameters, minimalParams)]; + assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`); +}); + +// ─── gsd_task_complete: enrichment arrays must be optional ─────────────────── + +test("gsd_task_complete — enrichment arrays are optional", () => { + const tool = getTool("gsd_task_complete"); + assert.ok(tool, "gsd_task_complete must be registered"); + + const required = new Set(getRequiredProps(tool)); + + // Core fields + const coreRequired = [ + "taskId", + "sliceId", + "milestoneId", + "oneLiner", + "narrative", + "verification", + ]; + for (const field of coreRequired) { + assert.ok(required.has(field), `core field "${field}" must be required`); + } + + // Enrichment fields must be optional + const enrichmentFields = [ + "keyFiles", + "keyDecisions", + "deviations", + "knownIssues", + "blockerDiscovered", + "verificationEvidence", + ]; + for (const field of enrichmentFields) { + assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`); + } +}); + +test("gsd_task_complete — validates with only core params", () => { + const tool = getTool("gsd_task_complete"); + assert.ok(tool, "gsd_task_complete must be registered"); + + const minimalParams = { + taskId: "T01", + sliceId: "S01", + milestoneId: "M001", + oneLiner: "Implemented the feature", + narrative: "Created the module and wired it up.", + verification: "npm test passes.", + }; + + const errors = [...Value.Errors(tool.parameters, minimalParams)]; + assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`); +}); + +// ─── gsd_complete_milestone: enrichment arrays must be optional ────────────── + +test("gsd_complete_milestone — enrichment arrays are optional", () => { + const tool = getTool("gsd_complete_milestone"); + assert.ok(tool, "gsd_complete_milestone must be registered"); + + const required = new Set(getRequiredProps(tool)); + + // Core fields + const coreRequired = [ + "milestoneId", + "title", + "oneLiner", + "narrative", + "verificationPassed", + ]; + for (const field of coreRequired) { + assert.ok(required.has(field), `core field "${field}" must be required`); + } + + // Enrichment fields must be optional + const enrichmentFields = [ + "successCriteriaResults", + "definitionOfDoneResults", + "requirementOutcomes", + "keyDecisions", + "keyFiles", + "lessonsLearned", + ]; + for (const field of enrichmentFields) { + assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`); + } +}); + +test("gsd_complete_milestone — validates with only core params", () => { + const tool = getTool("gsd_complete_milestone"); + assert.ok(tool, "gsd_complete_milestone must be registered"); + + const minimalParams = { + milestoneId: "M001", + title: "Test milestone", + oneLiner: "Finished it.", + narrative: "All work completed.", + verificationPassed: true, + }; + + const errors = [...Value.Errors(tool.parameters, minimalParams)]; + assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`); +}); + +// ─── gsd_plan_slice: enrichment fields must be optional ────────────────────── + +test("gsd_plan_slice — enrichment fields are optional", () => { + const tool = getTool("gsd_plan_slice"); + assert.ok(tool, "gsd_plan_slice must be registered"); + + const required = new Set(getRequiredProps(tool)); + + // Core fields + const coreRequired = ["milestoneId", "sliceId", "goal", "tasks"]; + for (const field of coreRequired) { + assert.ok(required.has(field), `core field "${field}" must be required`); + } + + // Enrichment fields + const enrichmentFields = [ + "successCriteria", + "proofLevel", + "integrationClosure", + "observabilityImpact", + ]; + for (const field of enrichmentFields) { + assert.ok(!required.has(field), `enrichment field "${field}" must be optional, not required`); + } +}); + +test("gsd_plan_slice — validates with only core params", () => { + const tool = getTool("gsd_plan_slice"); + assert.ok(tool, "gsd_plan_slice must be registered"); + + const minimalParams = { + milestoneId: "M001", + sliceId: "S01", + goal: "Implement feature X", + tasks: [ + { + taskId: "T01", + title: "Build X", + description: "Build the thing", + estimate: "2h", + files: ["src/x.ts"], + verify: "npm test", + inputs: [], + expectedOutput: ["src/x.ts"], + }, + ], + }; + + const errors = [...Value.Errors(tool.parameters, minimalParams)]; + assert.strictEqual(errors.length, 0, `Minimal params should validate but got errors: ${errors.map(e => `${e.path}: ${e.message}`).join(", ")}`); +}); + +// ─── Required param count ceiling ──────────────────────────────────────────── + +test("no planning/completion tool requires more than 10 top-level params", () => { + const heavyTools = [ + "gsd_slice_complete", + "gsd_plan_milestone", + "gsd_task_complete", + "gsd_complete_milestone", + "gsd_plan_slice", + ]; + + for (const name of heavyTools) { + const tool = getTool(name); + assert.ok(tool, `${name} must be registered`); + const required = getRequiredProps(tool); + assert.ok( + required.length <= 10, + `${name} has ${required.length} required params (max 10) — required: ${required.join(", ")}`, + ); + } +}); diff --git a/src/resources/extensions/gsd/tests/triage-resolution.test.ts b/src/resources/extensions/gsd/tests/triage-resolution.test.ts index 496685732..0decf9e6f 100644 --- a/src/resources/extensions/gsd/tests/triage-resolution.test.ts +++ b/src/resources/extensions/gsd/tests/triage-resolution.test.ts @@ -212,6 +212,14 @@ test("resolution: buildQuickTaskPrompt includes capture text and ID", () => { assert.ok(prompt.includes("add retry logic to OAuth"), "should include capture text"); assert.ok(prompt.includes("Quick Task"), "should have Quick Task header"); assert.ok(prompt.includes("Do NOT modify"), "should warn about plan files"); + assert.ok( + prompt.includes("Verify the issue still exists"), + "should instruct agent to verify issue still exists (#2872)", + ); + assert.ok( + prompt.includes("Already resolved"), + "should instruct agent to report already resolved if fixed (#2872)", + ); }); // ─── markCaptureExecuted ───────────────────────────────────────────────────── @@ -379,7 +387,8 @@ test("resolution: executeTriageResolutions handles mixed classifications", () => assert.strictEqual(result.injected, 1, "should inject 1 task"); assert.strictEqual(result.replanned, 0); assert.strictEqual(result.quickTasks.length, 1, "should queue 1 quick-task"); - assert.strictEqual(result.actions.length, 2, "should have 2 action entries (note/defer excluded)"); + // inject + quick-task + note acknowledged = 3 actions (defer still excluded) + assert.strictEqual(result.actions.length, 3, "should have 3 action entries (defer excluded, note now included)"); } finally { rmSync(tmp, { recursive: true, force: true }); } diff --git a/src/resources/extensions/gsd/tests/uat-stuck-loop-orphaned-worktree.test.ts b/src/resources/extensions/gsd/tests/uat-stuck-loop-orphaned-worktree.test.ts new file mode 100644 index 000000000..44ae79661 --- /dev/null +++ b/src/resources/extensions/gsd/tests/uat-stuck-loop-orphaned-worktree.test.ts @@ -0,0 +1,289 @@ +/** + * uat-stuck-loop-orphaned-worktree.test.ts — Regression tests for #2821. + * + * Reproduces two cascading bugs: + * + * Bug 1 — UAT stuck-loop: syncProjectRootToWorktree uses force:false for + * milestone files. When the project root has an ASSESSMENT with a verdict + * but the worktree has a stale/empty ASSESSMENT (or none at all after DB + * rebuild), the verdict is NOT synced into the worktree. checkNeedsRunUat + * finds no verdict → re-dispatches run-uat indefinitely. + * + * Bug 2 — Orphaned worktree: removeWorktree silently swallows failures when + * git worktree remove fails (untracked files, CWD inside worktree, etc.). + * The worktree directory and branch persist on disk after teardown. + * teardownAutoWorktree has a fallback rmSync but it also fails when the + * git internal .git/worktrees/ directory holds a lock. + */ + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdtempSync, + mkdirSync, + writeFileSync, + rmSync, + existsSync, + readFileSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execFileSync } from "node:child_process"; + +import { syncProjectRootToWorktree } from "../auto-worktree.ts"; +import { + createWorktree, + removeWorktree, + worktreePath, +} from "../worktree-manager.ts"; + +function git(args: string[], cwd: string): string { + return execFileSync("git", args, { + cwd, + stdio: ["ignore", "pipe", "pipe"], + encoding: "utf-8", + }).trim(); +} + +function makeBaseRepo(): string { + const base = mkdtempSync(join(tmpdir(), "gsd-2821-")); + git(["init", "-b", "main"], base); + git(["config", "user.name", "Test"], base); + git(["config", "user.email", "test@test.com"], base); + writeFileSync(join(base, "README.md"), "# test\n"); + mkdirSync(join(base, ".gsd", "milestones", "M011"), { recursive: true }); + git(["add", "."], base); + git(["commit", "-m", "init"], base); + return base; +} + +// ─── Bug 1: ASSESSMENT force-sync ───────────────────────────────────────── + +describe("#2821 Bug 1 — ASSESSMENT file force-synced on resume", () => { + let mainBase: string; + let wtBase: string; + + beforeEach(() => { + mainBase = mkdtempSync(join(tmpdir(), "gsd-2821-main-")); + wtBase = mkdtempSync(join(tmpdir(), "gsd-2821-wt-")); + mkdirSync(join(mainBase, ".gsd", "milestones", "M011", "slices", "S01"), { + recursive: true, + }); + mkdirSync(join(wtBase, ".gsd", "milestones", "M011", "slices", "S01"), { + recursive: true, + }); + }); + + afterEach(() => { + rmSync(mainBase, { recursive: true, force: true }); + rmSync(wtBase, { recursive: true, force: true }); + }); + + test("force-syncs ASSESSMENT with verdict from project root into worktree when worktree copy has no verdict", () => { + // Project root has ASSESSMENT with a PASS verdict (written by run-uat, synced by post-unit) + const prAssessment = join( + mainBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + writeFileSync( + prAssessment, + "---\nverdict: pass\n---\n# S01 Assessment\nAll tests pass.\n", + ); + + // Worktree has a stale ASSESSMENT with FAIL verdict (from the initial run-uat execution) + const wtAssessment = join( + wtBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + writeFileSync( + wtAssessment, + "---\nverdict: fail\n---\n# S01 Assessment\nSome tests fail.\n", + ); + + syncProjectRootToWorktree(mainBase, wtBase, "M011"); + + // The worktree ASSESSMENT must now have the project root's PASS verdict + const content = readFileSync(wtAssessment, "utf-8"); + assert.ok( + content.includes("verdict: pass"), + `Expected worktree ASSESSMENT to have verdict:pass after sync, got: ${content.slice(0, 100)}`, + ); + }); + + test("force-syncs ASSESSMENT from project root when worktree has no ASSESSMENT at all", () => { + // Project root has ASSESSMENT with verdict + const prAssessment = join( + mainBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + writeFileSync( + prAssessment, + "---\nverdict: pass\n---\n# S01 Assessment\n", + ); + + // Worktree has NO ASSESSMENT (deleted during DB rebuild) + // — file simply doesn't exist + + syncProjectRootToWorktree(mainBase, wtBase, "M011"); + + const wtAssessment = join( + wtBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + assert.ok( + existsSync(wtAssessment), + "ASSESSMENT should be copied to worktree when missing", + ); + const content = readFileSync(wtAssessment, "utf-8"); + assert.ok( + content.includes("verdict: pass"), + `Synced ASSESSMENT should contain verdict:pass, got: ${content.slice(0, 100)}`, + ); + }); + + test("does NOT overwrite worktree ASSESSMENT when project root has no verdict", () => { + // Project root has ASSESSMENT without verdict (incomplete) + const prAssessment = join( + mainBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + writeFileSync(prAssessment, "# S01 Assessment\nIn progress...\n"); + + // Worktree has ASSESSMENT with verdict:fail + const wtAssessment = join( + wtBase, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ); + writeFileSync( + wtAssessment, + "---\nverdict: fail\n---\n# S01 Assessment\nSome tests fail.\n", + ); + + syncProjectRootToWorktree(mainBase, wtBase, "M011"); + + // Worktree copy should NOT be overwritten by the verdictless project root copy + const content = readFileSync(wtAssessment, "utf-8"); + assert.ok( + content.includes("verdict: fail"), + `Worktree ASSESSMENT should keep verdict:fail when project root has no verdict, got: ${content.slice(0, 100)}`, + ); + }); +}); + +// ─── Bug 2: Orphaned worktree cleanup ───────────────────────────────────── + +describe("#2821 Bug 2 — removeWorktree cleans up despite untracked files", () => { + let base: string; + + beforeEach(() => { + base = makeBaseRepo(); + }); + + afterEach(() => { + rmSync(base, { recursive: true, force: true }); + }); + + test("removes worktree directory even when it contains untracked files", () => { + const info = createWorktree(base, "M011", { + branch: "milestone/M011", + }); + + // Simulate run-uat writing untracked files (S01-UAT-RESULT.md, ASSESSMENT) + mkdirSync( + join(info.path, ".gsd", "milestones", "M011", "slices", "S01"), + { recursive: true }, + ); + writeFileSync( + join( + info.path, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-UAT-RESULT.md", + ), + "# UAT Result\nverdict: fail\n", + ); + writeFileSync( + join( + info.path, + ".gsd", + "milestones", + "M011", + "slices", + "S01", + "S01-ASSESSMENT.md", + ), + "---\nverdict: fail\n---\n# Assessment\n", + ); + + removeWorktree(base, "M011", { + branch: "milestone/M011", + deleteBranch: true, + force: true, + }); + + const wtDir = worktreePath(base, "M011"); + assert.ok( + !existsSync(wtDir), + `Worktree directory should be removed after teardown, but still exists at ${wtDir}`, + ); + }); + + test("removes git internal worktree metadata after filesystem removal", () => { + createWorktree(base, "M011", { + branch: "milestone/M011", + }); + + removeWorktree(base, "M011", { + branch: "milestone/M011", + deleteBranch: true, + force: true, + }); + + // The git internal worktree directory should be cleaned up + const gitInternalWorktreeDir = join(base, ".git", "worktrees", "M011"); + assert.ok( + !existsSync(gitInternalWorktreeDir), + `Git internal worktree dir should be removed: ${gitInternalWorktreeDir}`, + ); + + // The branch should be deleted + const branches = git(["branch"], base); + assert.ok( + !branches.includes("milestone/M011"), + "milestone/M011 branch should be deleted after removeWorktree", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/unit-ownership.test.ts b/src/resources/extensions/gsd/tests/unit-ownership.test.ts index fd062c9c8..39ea6202f 100644 --- a/src/resources/extensions/gsd/tests/unit-ownership.test.ts +++ b/src/resources/extensions/gsd/tests/unit-ownership.test.ts @@ -3,7 +3,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'; +import { mkdtempSync, rmSync } from 'node:fs'; import { join } from 'node:path'; import { tmpdir } from 'node:os'; @@ -14,6 +14,8 @@ import { checkOwnership, taskUnitKey, sliceUnitKey, + initOwnershipTable, + closeOwnershipDb, } from '../unit-ownership.ts'; function makeTmpBase(): string { @@ -34,28 +36,51 @@ test('sliceUnitKey: builds correct key', () => { assert.equal(sliceUnitKey('M001', 'S01'), 'M001/S01'); }); -// ─── Claim / get / release ─────────────────────────────────────────────── +// ─── Claim / get / release (SQLite-backed) ────────────────────────────── -test('claimUnit: creates claim file and records agent', () => { +test('claimUnit: creates DB and records agent', () => { const base = makeTmpBase(); try { - claimUnit(base, 'M001/S01/T01', 'executor-01'); + initOwnershipTable(base); + const claimed = claimUnit(base, 'M001/S01/T01', 'executor-01'); - assert.ok(existsSync(join(base, '.gsd', 'unit-claims.json')), 'claim file should exist'); + assert.equal(claimed, true, 'first claim should succeed'); assert.equal(getOwner(base, 'M001/S01/T01'), 'executor-01'); } finally { + closeOwnershipDb(base); cleanup(base); } }); -test('claimUnit: overwrites existing claim (last writer wins)', () => { +test('claimUnit: rejects second claim on same unit (first-writer-wins)', () => { const base = makeTmpBase(); try { - claimUnit(base, 'M001/S01/T01', 'executor-01'); - claimUnit(base, 'M001/S01/T01', 'executor-02'); + initOwnershipTable(base); + const first = claimUnit(base, 'M001/S01/T01', 'executor-01'); + const second = claimUnit(base, 'M001/S01/T01', 'executor-02'); - assert.equal(getOwner(base, 'M001/S01/T01'), 'executor-02'); + assert.equal(first, true, 'first claim should succeed'); + assert.equal(second, false, 'second claim should fail (first-writer-wins)'); + assert.equal(getOwner(base, 'M001/S01/T01'), 'executor-01', + 'original owner must be preserved'); } finally { + closeOwnershipDb(base); + cleanup(base); + } +}); + +test('claimUnit: same agent re-claiming same unit succeeds', () => { + const base = makeTmpBase(); + try { + initOwnershipTable(base); + const first = claimUnit(base, 'M001/S01/T01', 'agent-a'); + const second = claimUnit(base, 'M001/S01/T01', 'agent-a'); + + assert.equal(first, true); + assert.equal(second, true, 're-claim by same agent should succeed'); + assert.equal(getOwner(base, 'M001/S01/T01'), 'agent-a'); + } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -63,21 +88,25 @@ test('claimUnit: overwrites existing claim (last writer wins)', () => { test('claimUnit: multiple units can be claimed independently', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); claimUnit(base, 'M001/S01/T02', 'agent-b'); assert.equal(getOwner(base, 'M001/S01/T01'), 'agent-a'); assert.equal(getOwner(base, 'M001/S01/T02'), 'agent-b'); } finally { + closeOwnershipDb(base); cleanup(base); } }); -test('getOwner: returns null when no claim file exists', () => { +test('getOwner: returns null when no DB initialized', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); assert.equal(getOwner(base, 'M001/S01/T01'), null); } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -85,9 +114,11 @@ test('getOwner: returns null when no claim file exists', () => { test('getOwner: returns null for unclaimed unit', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); assert.equal(getOwner(base, 'M001/S01/T99'), null); } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -95,11 +126,13 @@ test('getOwner: returns null for unclaimed unit', () => { test('releaseUnit: removes claim', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); releaseUnit(base, 'M001/S01/T01'); assert.equal(getOwner(base, 'M001/S01/T01'), null); } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -107,9 +140,27 @@ test('releaseUnit: removes claim', () => { test('releaseUnit: no-op for non-existent claim', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); // Should not throw releaseUnit(base, 'M001/S01/T01'); } finally { + closeOwnershipDb(base); + cleanup(base); + } +}); + +test('releaseUnit: allows reclaim after release', () => { + const base = makeTmpBase(); + try { + initOwnershipTable(base); + claimUnit(base, 'M001/S01/T01', 'agent-a'); + releaseUnit(base, 'M001/S01/T01'); + + const reclaimed = claimUnit(base, 'M001/S01/T01', 'agent-b'); + assert.equal(reclaimed, true, 'reclaim after release should succeed'); + assert.equal(getOwner(base, 'M001/S01/T01'), 'agent-b'); + } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -119,20 +170,13 @@ test('releaseUnit: no-op for non-existent claim', () => { test('checkOwnership: returns null when no actorName provided (opt-in)', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); // No actorName → ownership not enforced assert.equal(checkOwnership(base, 'M001/S01/T01', undefined), null); } finally { - cleanup(base); - } -}); - -test('checkOwnership: returns null when no claim file exists', () => { - const base = makeTmpBase(); - try { - assert.equal(checkOwnership(base, 'M001/S01/T01', 'agent-a'), null); - } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -140,11 +184,13 @@ test('checkOwnership: returns null when no claim file exists', () => { test('checkOwnership: returns null when unit is unclaimed', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); // Different unit, unclaimed assert.equal(checkOwnership(base, 'M001/S01/T99', 'agent-b'), null); } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -152,10 +198,12 @@ test('checkOwnership: returns null when unit is unclaimed', () => { test('checkOwnership: returns null when actor matches owner', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); assert.equal(checkOwnership(base, 'M001/S01/T01', 'agent-a'), null); } finally { + closeOwnershipDb(base); cleanup(base); } }); @@ -163,6 +211,7 @@ test('checkOwnership: returns null when actor matches owner', () => { test('checkOwnership: returns error string when actor does not match owner', () => { const base = makeTmpBase(); try { + initOwnershipTable(base); claimUnit(base, 'M001/S01/T01', 'agent-a'); const err = checkOwnership(base, 'M001/S01/T01', 'agent-b'); @@ -170,6 +219,40 @@ test('checkOwnership: returns error string when actor does not match owner', () assert.match(err!, /owned by agent-a/); assert.match(err!, /not agent-b/); } finally { + closeOwnershipDb(base); + cleanup(base); + } +}); + +// ─── Race condition: first-writer-wins atomicity ───────────────────────── + +test('claimUnit: concurrent claims — only first writer wins (no lost update)', () => { + const base = makeTmpBase(); + try { + initOwnershipTable(base); + + // Simulate the race described in #2728: + // Two agents both try to claim the same unit. + // With SQLite INSERT OR IGNORE, only the first succeeds. + const results: boolean[] = []; + const agents = ['agent-alpha', 'agent-beta', 'agent-gamma']; + for (const agent of agents) { + results.push(claimUnit(base, 'M001/S01/T01', agent)); + } + + // Exactly one agent should have won + const wins = results.filter(r => r === true); + assert.equal(wins.length, 1, 'exactly one agent should win the claim'); + + // The winner is the first agent (deterministic in single-threaded) + assert.equal(results[0], true); + assert.equal(results[1], false); + assert.equal(results[2], false); + + // The owner must be the first agent + assert.equal(getOwner(base, 'M001/S01/T01'), 'agent-alpha'); + } finally { + closeOwnershipDb(base); cleanup(base); } }); diff --git a/src/resources/extensions/gsd/tests/unstructured-continue-context-injection.test.ts b/src/resources/extensions/gsd/tests/unstructured-continue-context-injection.test.ts new file mode 100644 index 000000000..c784bc421 --- /dev/null +++ b/src/resources/extensions/gsd/tests/unstructured-continue-context-injection.test.ts @@ -0,0 +1,163 @@ +// GSD-2 — Regression test for #3615: unstructured "continue" must inject task context +// Copyright (c) 2026 Jeremy McSpadden + +/** + * Bug #3615: When a user types "continue" (or any bare text) to resume + * an in-progress session, buildGuidedExecuteContextInjection() only + * matched two hardcoded regex patterns (auto-dispatch and guided-resume). + * The function returned null for any other input, so no task context was + * injected — causing the agent to rebuild everything from scratch and + * burn ~86k tokens. + * + * This test verifies: + * 1. Structural: the fallback exists with phase + intent guards + * 2. Behavioral: RESUME_INTENT_PATTERNS matches expected prompts and + * rejects non-resume prompts (control, help, diagnostic, etc.) + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const systemContextSource = readFileSync( + join(__dirname, "..", "bootstrap", "system-context.ts"), + "utf-8", +); + +// ── Structural tests ──────────────────────────────────────────────── + +describe("#3615 — structural: fallback exists with correct guards", () => { + const fnStart = systemContextSource.indexOf("async function buildGuidedExecuteContextInjection("); + assert.ok(fnStart >= 0, "should find buildGuidedExecuteContextInjection"); + const fnEnd = systemContextSource.indexOf("\nasync function ", fnStart + 1); + const fnBody = fnEnd >= 0 + ? systemContextSource.slice(fnStart, fnEnd) + : systemContextSource.slice(fnStart); + + test("has a deriveState fallback after the two regex branches", () => { + const deriveStateCalls = fnBody.match(/deriveState\(basePath\)/g); + assert.ok( + deriveStateCalls && deriveStateCalls.length >= 2, + `expected >=2 deriveState(basePath) calls, got ${deriveStateCalls?.length ?? 0}`, + ); + }); + + test("fallback is phase-gated to executing only", () => { + const afterFallback = fnBody.indexOf("// Fallback:"); + assert.ok(afterFallback >= 0, "should have a fallback comment"); + const fallbackSection = fnBody.slice(afterFallback); + assert.ok( + fallbackSection.includes('state.phase === "executing"'), + 'fallback must be gated on state.phase === "executing"', + ); + }); + + test("fallback is intent-gated via RESUME_INTENT_PATTERNS", () => { + const afterFallback = fnBody.indexOf("// Fallback:"); + const fallbackSection = fnBody.slice(afterFallback); + assert.ok( + fallbackSection.includes("RESUME_INTENT_PATTERNS"), + "fallback must check RESUME_INTENT_PATTERNS before deriveState", + ); + }); + + test("fallback calls buildTaskExecutionContextInjection with derived state", () => { + const afterFallback = fnBody.indexOf("// Fallback:"); + const fallbackSection = fnBody.slice(afterFallback); + assert.ok( + fallbackSection.includes("buildTaskExecutionContextInjection") && + fallbackSection.includes("state.activeMilestone.id") && + fallbackSection.includes("state.activeSlice.id") && + fallbackSection.includes("state.activeTask.id"), + "fallback must call buildTaskExecutionContextInjection with state-derived IDs", + ); + }); + + test("only one return null at the end", () => { + const returnNulls = fnBody.match(/return null;/g); + assert.ok( + returnNulls && returnNulls.length === 1, + `expected exactly 1 'return null' (at end after fallback), got ${returnNulls?.length ?? 0}`, + ); + }); +}); + +// ── Behavioral tests: RESUME_INTENT_PATTERNS ──────────────────────── + +describe("#3615 — behavioral: RESUME_INTENT_PATTERNS matches resume prompts", () => { + // Extract the regex from source so the test stays in sync + const patternMatch = systemContextSource.match(/const RESUME_INTENT_PATTERNS\s*=\s*\/(.+)\/;/); + assert.ok(patternMatch, "should find RESUME_INTENT_PATTERNS definition"); + const pattern = new RegExp(patternMatch[1]); + + // Helper: normalize prompt the same way the production code does + const normalize = (s: string) => s.trim().toLowerCase().replace(/[.!?,]+$/g, ""); + + const shouldMatch = [ + "continue", + "Continue", + "CONTINUE", + "continue.", + "continue!", + "resume", + "ok", + "OK", + "Ok!", + "go", + "go ahead", + "Go ahead.", + "proceed", + "keep going", + "carry on", + "next", + "yes", + "yeah", + "yep", + "sure", + "do it", + "let's go", + "pick up where you left off", + " continue ", // whitespace padded + ]; + + const shouldNotMatch = [ + "help", + "status", + "/gsd auto", + "/gsd stats", + "what's the plan?", + "show me the logs", + "abort", + "stop", + "cancel", + "replan this slice", + "I think we should change the approach", + "can you explain what you just did?", + "run the tests", + "check the build", + "Execute the next task: T01", + "what files were changed", + "", + ]; + + for (const prompt of shouldMatch) { + test(`matches resume prompt: "${prompt}"`, () => { + assert.ok( + pattern.test(normalize(prompt)), + `expected RESUME_INTENT_PATTERNS to match "${prompt}" (normalized: "${normalize(prompt)}")`, + ); + }); + } + + for (const prompt of shouldNotMatch) { + test(`rejects non-resume prompt: "${prompt}"`, () => { + assert.ok( + !pattern.test(normalize(prompt)), + `expected RESUME_INTENT_PATTERNS to NOT match "${prompt}" (normalized: "${normalize(prompt)}")`, + ); + }); + } +}); diff --git a/src/resources/extensions/gsd/tests/update-command.test.ts b/src/resources/extensions/gsd/tests/update-command.test.ts index 9245d87c0..849f261ef 100644 --- a/src/resources/extensions/gsd/tests/update-command.test.ts +++ b/src/resources/extensions/gsd/tests/update-command.test.ts @@ -65,3 +65,22 @@ test("/gsd update is listed in completions with correct description", () => { "completion description should mention updating", ); }); + +test("/gsd codebase appears in top-level completions", () => { + const pi = createMockPi(); + registerGSDCommand(pi as any); + + const gsd = pi.commands.get("gsd"); + const completions = gsd.getArgumentCompletions("code"); + const codebaseEntry = completions.find((c: any) => c.value === "codebase"); + assert.ok(codebaseEntry, "codebase should appear in completions"); + assert.match(codebaseEntry.description, /codebase map cache/i); +}); + +test("/gsd codebase appears in help description", () => { + const pi = createMockPi(); + registerGSDCommand(pi as any); + + const gsd = pi.commands.get("gsd"); + assert.ok(gsd?.description?.includes("codebase"), "description should mention codebase"); +}); diff --git a/src/resources/extensions/gsd/tests/vacuum-recovery.test.ts b/src/resources/extensions/gsd/tests/vacuum-recovery.test.ts new file mode 100644 index 000000000..5cd0bb230 --- /dev/null +++ b/src/resources/extensions/gsd/tests/vacuum-recovery.test.ts @@ -0,0 +1,154 @@ +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import * as os from 'node:os'; +import { createRequire } from 'node:module'; +import { + openDatabase, + closeDatabase, + isDbAvailable, + _getAdapter, +} from '../gsd-db.ts'; + +const _require = createRequire(import.meta.url); + +// ═══════════════════════════════════════════════════════════════════════════ +// Helpers +// ═══════════════════════════════════════════════════════════════════════════ + +function tempDbPath(): string { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-vacuum-test-')); + return path.join(dir, 'test.db'); +} + +function cleanup(dbPath: string): void { + closeDatabase(); + try { + const dir = path.dirname(dbPath); + for (const f of fs.readdirSync(dir)) { + fs.unlinkSync(path.join(dir, f)); + } + fs.rmdirSync(dir); + } catch { /* best effort */ } +} + +/** + * Create a SQLite DB with a corrupt freelist that causes DDL to fail + * with "database disk image is malformed" but is recoverable via VACUUM. + * + * Strategy: + * 1. Create a DB with schema_version at v0 (so initSchema needs to run DDL) + * 2. Add padding rows to create many pages, then delete + drop to free them + * 3. Corrupt the freelist trunk pointer to point at a B-tree page + * + * This simulates the real-world scenario described in #2519: an interrupted + * WAL checkpoint leaves the freelist in an inconsistent state. + */ +function createCorruptFreelistDb(dbPath: string): void { + // Use node:sqlite directly to build the minimal corrupt DB + const sqlite = _require('node:sqlite'); + const db = new sqlite.DatabaseSync(dbPath); + db.exec('PRAGMA journal_mode=WAL'); + db.exec('CREATE TABLE schema_version (version INTEGER NOT NULL, applied_at TEXT NOT NULL)'); + db.exec("INSERT INTO schema_version VALUES (0, '2024-01-01')"); + // Pad with data to create many pages, then free them + db.exec('CREATE TABLE _padding (id INTEGER PRIMARY KEY, data TEXT)'); + for (let i = 0; i < 30; i++) { + db.exec(`INSERT INTO _padding (data) VALUES ('${'x'.repeat(4000)}')`); + } + db.exec('DELETE FROM _padding'); + db.exec('DROP TABLE _padding'); + db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); + db.close(); + + // Remove WAL/SHM files to ensure clean file-only state + try { fs.unlinkSync(dbPath + '-wal'); } catch { /* may not exist */ } + try { fs.unlinkSync(dbPath + '-shm'); } catch { /* may not exist */ } + + // Corrupt: point freelist trunk (offset 32-35) to page 2 (a B-tree page), + // and claim 10 free pages (offset 36-39) + const fd = fs.openSync(dbPath, 'r+'); + try { + const buf = Buffer.alloc(8); + buf.writeUInt32BE(2, 0); // trunk page = page 2 (actually a B-tree page) + buf.writeUInt32BE(10, 4); // freelist count = 10 + fs.writeSync(fd, buf, 0, 8, 32); + } finally { + fs.closeSync(fd); + } +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Tests +// ═══════════════════════════════════════════════════════════════════════════ + +describe('openDatabase VACUUM recovery on corrupt freelist', () => { + + test('recovers a file-backed DB with corrupt freelist via VACUUM', () => { + const dbPath = tempDbPath(); + + // Create a DB with corrupt freelist (schema at v0 so initSchema runs DDL) + createCorruptFreelistDb(dbPath); + + // Without the fix, this throws "database disk image is malformed". + // With the fix, openDatabase detects "malformed", runs VACUUM, retries. + const ok = openDatabase(dbPath); + assert.ok(ok, 'openDatabase should succeed after VACUUM recovery'); + assert.ok(isDbAvailable(), 'DB should be available after recovery'); + + // Verify full schema was applied + const adapter = _getAdapter()!; + const row = adapter.prepare( + 'SELECT MAX(version) as version FROM schema_version', + ).get(); + assert.ok( + typeof row?.['version'] === 'number' && (row['version'] as number) > 0, + 'schema_version should have a positive version after recovery', + ); + + cleanup(dbPath); + }); + + test('does not attempt VACUUM for non-malformed errors', () => { + // openDatabase with :memory: never hits the fileBacked VACUUM path, + // so non-malformed errors propagate directly. We verify by checking + // that a non-file error from an in-memory DB propagates unchanged. + // (In-memory DBs always succeed for initSchema, so this is a design + // check — the VACUUM path is only for fileBacked = true.) + const ok = openDatabase(':memory:'); + assert.ok(ok, 'in-memory DB should open fine'); + closeDatabase(); + }); + + test('throws if VACUUM itself fails on unrecoverable corruption', () => { + const dbPath = tempDbPath(); + + // Create a file with valid SQLite header but thoroughly corrupt content + const page = Buffer.alloc(4096); + // SQLite magic: "SQLite format 3\0" + page.write('SQLite format 3\0', 0, 'utf8'); + // Page size: 4096 (big-endian at offset 16) + page.writeUInt16BE(4096, 16); + page[18] = 1; // write version + page[19] = 1; // read version + page[20] = 0; // reserved space + page[21] = 64; // max embedded payload fraction + page[22] = 32; // min embedded payload fraction + page[23] = 32; // leaf payload fraction + page.writeUInt32BE(1, 28); // page_count = 1 + page.writeUInt32BE(999, 32); // corrupt freelist trunk + page.writeUInt32BE(5, 36); // freelist count = 5 + + fs.writeFileSync(dbPath, page); + + // Should throw — VACUUM cannot save a thoroughly corrupt file + assert.throws( + () => openDatabase(dbPath), + /./, + 'should throw for unrecoverable corruption', + ); + + cleanup(dbPath); + }); +}); diff --git a/src/resources/extensions/gsd/tests/validate-directory.test.ts b/src/resources/extensions/gsd/tests/validate-directory.test.ts index 72c45be38..c86e08a80 100644 --- a/src/resources/extensions/gsd/tests/validate-directory.test.ts +++ b/src/resources/extensions/gsd/tests/validate-directory.test.ts @@ -74,6 +74,27 @@ test("validateDirectory: C:\\Windows is blocked", { skip: !isWindows ? "Windows- assert.equal(result.severity, "blocked"); }); +test("validateDirectory: D:\\Windows is blocked", { skip: !isWindows ? "Windows-only test" : undefined }, () => { + const result = validateDirectory("D:\\Windows"); + assert.equal(result.safe, false); + assert.equal(result.severity, "blocked"); + assert.ok(result.reason?.includes("system directory")); +}); + +test("validateDirectory: E:\\Program Files is blocked", { skip: !isWindows ? "Windows-only test" : undefined }, () => { + const result = validateDirectory("E:\\Program Files"); + assert.equal(result.safe, false); + assert.equal(result.severity, "blocked"); + assert.ok(result.reason?.includes("system directory")); +}); + +test("validateDirectory: any Windows drive root is blocked", { skip: !isWindows ? "Windows-only test" : undefined }, () => { + const result = validateDirectory("D:\\"); + assert.equal(result.safe, false); + assert.equal(result.severity, "blocked"); + assert.ok(result.reason?.includes("system directory")); +}); + // ─── Home directory (cross-platform) ───────────────────────────────────────────── test("validateDirectory: home directory itself is blocked", () => { @@ -104,7 +125,13 @@ test("validateDirectory: subdirectory of home is NOT blocked", () => { // Regression test for #1317: GSD worktree inside $HOME must not be blocked even // when the resolved project root equals $HOME (e.g. home dir is a git repo). test("validateDirectory: GSD worktree path nested under home is NOT blocked (#1317)", () => { + const originalHome = process.env.HOME; + const originalUserProfile = process.env.USERPROFILE; + const fakeHome = makeTempDir("fake-home"); + process.env.HOME = fakeHome; + process.env.USERPROFILE = fakeHome; const worktreePath = join(homedir(), ".gsd", "worktrees", "M001"); + const worktreeRoot = join(fakeHome, ".gsd", "worktrees", "M001"); mkdirSync(worktreePath, { recursive: true }); try { // The worktree CWD itself is a valid location — it must pass. @@ -112,7 +139,12 @@ test("validateDirectory: GSD worktree path nested under home is NOT blocked (#13 assert.equal(result.safe, true, "GSD worktree path should be safe to run in"); assert.equal(result.severity, "ok"); } finally { - rmSync(join(homedir(), ".gsd", "worktrees", "M001"), { recursive: true, force: true }); + if (originalHome === undefined) delete process.env.HOME; + else process.env.HOME = originalHome; + if (originalUserProfile === undefined) delete process.env.USERPROFILE; + else process.env.USERPROFILE = originalUserProfile; + rmSync(worktreeRoot, { recursive: true, force: true }); + rmSync(fakeHome, { recursive: true, force: true }); } }); diff --git a/src/resources/extensions/gsd/tests/validate-milestone-prompt-verification-classes.test.ts b/src/resources/extensions/gsd/tests/validate-milestone-prompt-verification-classes.test.ts new file mode 100644 index 000000000..df08568f3 --- /dev/null +++ b/src/resources/extensions/gsd/tests/validate-milestone-prompt-verification-classes.test.ts @@ -0,0 +1,18 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const promptPath = join(process.cwd(), "src/resources/extensions/gsd/prompts/validate-milestone.md"); +const prompt = readFileSync(promptPath, "utf-8"); + +test("validate-milestone reviewer C requires canonical verification class names", () => { + assert.match(prompt, /\*\*Reviewer C[\s\S]*Verification Classes/i); + assert.match(prompt, /exact class names [`']?Contract[`']?, [`']?Integration[`']?, [`']?Operational[`']?, and [`']?UAT[`']?/i); + assert.match(prompt, /If no verification classes were planned, say that explicitly/i); +}); + +test("validate-milestone prompt routes verification class analysis into verificationClasses", () => { + assert.match(prompt, /pass it in `verificationClasses`/i); + assert.match(prompt, /Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses`/); +}); diff --git a/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts b/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts index 120751b60..1f07791e0 100644 --- a/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts +++ b/src/resources/extensions/gsd/tests/validate-milestone-write-order.test.ts @@ -6,7 +6,7 @@ import { tmpdir } from "node:os"; import { randomUUID } from "node:crypto"; import { handleValidateMilestone } from "../tools/validate-milestone.js"; -import { openDatabase, closeDatabase, _getAdapter, insertMilestone } from "../gsd-db.js"; +import { openDatabase, closeDatabase, _getAdapter, insertMilestone, insertSlice } from "../gsd-db.js"; import { clearPathCache } from "../paths.js"; import { clearParseCache } from "../files.js"; @@ -45,6 +45,7 @@ describe("handleValidateMilestone write ordering (#2725)", () => { const dbPath = join(base, ".gsd", "gsd.db"); openDatabase(dbPath); insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); const result = await handleValidateMilestone(VALID_PARAMS, base); assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`); @@ -71,6 +72,7 @@ describe("handleValidateMilestone write ordering (#2725)", () => { const dbPath = join(base, ".gsd", "gsd.db"); openDatabase(dbPath); insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); const result = await handleValidateMilestone( { ...VALID_PARAMS, verificationClasses: undefined }, @@ -88,6 +90,7 @@ describe("handleValidateMilestone write ordering (#2725)", () => { const dbPath = join(base, ".gsd", "gsd.db"); openDatabase(dbPath); insertMilestone({ id: "M001" }); + insertSlice({ id: "S01", milestoneId: "M001" }); // Force disk write failure by replacing the milestone directory with a // regular file. saveFile() will fail because it cannot write inside a diff --git a/src/resources/extensions/gsd/tests/validate-milestone.test.ts b/src/resources/extensions/gsd/tests/validate-milestone.test.ts index 9647ddb46..7ba062229 100644 --- a/src/resources/extensions/gsd/tests/validate-milestone.test.ts +++ b/src/resources/extensions/gsd/tests/validate-milestone.test.ts @@ -9,9 +9,11 @@ import { deriveState, isValidationTerminal } from "../state.ts"; import { resolveExpectedArtifactPath, diagnoseExpectedArtifact } from "../auto-artifact-paths.ts"; import { verifyExpectedArtifact, buildLoopRemediationSteps } from "../auto-recovery.ts"; import { resolveDispatch, type DispatchContext } from "../auto-dispatch.ts"; +import { buildCompleteMilestonePrompt, buildValidateMilestonePrompt } from "../auto-prompts.ts"; import type { GSDState } from "../types.ts"; import { clearPathCache } from "../paths.ts"; import { clearParseCache } from "../files.ts"; +import { closeDatabase, insertMilestone, insertSlice, openDatabase } from "../gsd-db.ts"; // ─── Helpers ────────────────────────────────────────────────────────────── @@ -24,9 +26,15 @@ function makeTmpBase(): string { function cleanup(base: string): void { clearPathCache(); clearParseCache(); + closeDatabase(); try { rmSync(base, { recursive: true, force: true }); } catch { /* */ } } +function openTestDb(base: string): void { + const dbPath = join(base, ".gsd", "gsd.db"); + assert.equal(openDatabase(dbPath), true, "test DB should open"); +} + function writeRoadmap(base: string, mid: string, content: string): void { const dir = join(base, ".gsd", "milestones", mid); mkdirSync(dir, { recursive: true }); @@ -57,6 +65,12 @@ function writeSliceSummary(base: string, mid: string, sid: string, content: stri writeFileSync(join(dir, `${sid}-SUMMARY.md`), content); } +function writeSliceAssessment(base: string, mid: string, sid: string, content: string): void { + const dir = join(base, ".gsd", "milestones", mid, "slices", sid); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, `${sid}-ASSESSMENT.md`), content); +} + const ALL_DONE_ROADMAP = `# M001: Test Milestone ## Vision @@ -163,16 +177,15 @@ test("deriveState returns completing-milestone when VALIDATION exists with termi } }); -test("deriveState treats needs-remediation as terminal — does not re-enter validating-milestone (#832)", async () => { +test("deriveState treats needs-remediation as non-terminal — re-enters validating-milestone (#832)", async () => { const base = makeTmpBase(); try { writeRoadmap(base, "M001", ALL_DONE_ROADMAP); writeValidation(base, "M001", "---\nverdict: needs-remediation\nremediation_round: 0\n---\n\n# Validation\nNeeds fixes."); const state = await deriveState(base); - // needs-remediation is now terminal — milestone needs a SUMMARY to be fully complete - // Without SUMMARY, it enters completing-milestone (not validating-milestone) - assert.notEqual(state.phase, "validating-milestone"); + // needs-remediation routes back to validating-milestone for re-validation + assert.equal(state.phase, "validating-milestone"); assert.equal(state.activeMilestone?.id, "M001"); } finally { cleanup(base); @@ -193,6 +206,104 @@ test("deriveState returns complete when both VALIDATION and SUMMARY exist", asyn } }); +test("buildValidateMilestonePrompt inlines ASSESSMENT evidence instead of UAT spec", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, "M001", ALL_DONE_ROADMAP); + const dir = join(base, ".gsd", "milestones", "M001"); + writeFileSync(join(dir, "M001-CONTEXT.md"), CONTEXT_FILE); + writeSliceSummary(base, "M001", "S01", "# S01 Summary\nDelivered."); + writeFileSync(join(dir, "slices", "S01", "S01-UAT.md"), "# UAT Spec\nDo the thing.\n"); + writeSliceAssessment(base, "M001", "S01", "---\nverdict: PASS\n---\n# Assessment\nEvidence captured."); + + const prompt = await buildValidateMilestonePrompt("M001", "Test Milestone", base); + assert.match(prompt, /S01 Assessment/i, "prompt should inline assessment evidence"); + assert.match(prompt, /verdict: PASS/i, "prompt should include the assessment verdict"); + assert.doesNotMatch(prompt, /UAT Spec/i, "prompt should not inline the raw UAT spec as evidence"); + } finally { + cleanup(base); + } +}); + +test("buildCompleteMilestonePrompt skips skipped slices from DB-backed summary inlining", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, "M001", `# M001: Test Milestone + +## Vision +Test + +## Success Criteria +- It works + +## Slices + +- [x] **S01: First slice** \`risk:low\` \`depends:[]\` + > Done +- [ ] **S02: Skipped slice** \`risk:low\` \`depends:[]\` + > Intentionally skipped + +## Boundary Map + +| From | To | Produces | Consumes | +|------|-----|----------|----------| +| S01 | terminal | output | nothing | +`); + openTestDb(base); + insertMilestone({ id: "M001", title: "Test Milestone", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First slice", status: "complete", depends: [], sequence: 1 }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Skipped slice", status: "skipped", depends: [], sequence: 2 }); + writeSliceSummary(base, "M001", "S01", "# S01 Summary\nDelivered."); + + const prompt = await buildCompleteMilestonePrompt("M001", "Test Milestone", base); + assert.match(prompt, /S01 Summary/i, "prompt should inline non-skipped slice summaries"); + assert.doesNotMatch(prompt, /### S02 Summary/i, "prompt should not inline skipped slice summaries"); + assert.doesNotMatch(prompt, /not found — file does not exist yet/i, "prompt should not emit skipped-slice missing-file placeholders"); + } finally { + cleanup(base); + } +}); + +test("buildValidateMilestonePrompt skips skipped slices from DB-backed summary inlining", async () => { + const base = makeTmpBase(); + try { + writeRoadmap(base, "M001", `# M001: Test Milestone + +## Vision +Test + +## Success Criteria +- It works + +## Slices + +- [x] **S01: First slice** \`risk:low\` \`depends:[]\` + > Done +- [ ] **S02: Skipped slice** \`risk:low\` \`depends:[]\` + > Intentionally skipped + +## Boundary Map + +| From | To | Produces | Consumes | +|------|-----|----------|----------| +| S01 | terminal | output | nothing | +`); + openTestDb(base); + insertMilestone({ id: "M001", title: "Test Milestone", status: "active" }); + insertSlice({ id: "S01", milestoneId: "M001", title: "First slice", status: "complete", depends: [], sequence: 1 }); + insertSlice({ id: "S02", milestoneId: "M001", title: "Skipped slice", status: "skipped", depends: [], sequence: 2 }); + writeSliceSummary(base, "M001", "S01", "# S01 Summary\nDelivered."); + writeSliceAssessment(base, "M001", "S01", "---\nverdict: PASS\n---\n# Assessment\nEvidence captured."); + + const prompt = await buildValidateMilestonePrompt("M001", "Test Milestone", base); + assert.match(prompt, /S01 Summary/i, "prompt should inline non-skipped slice summaries"); + assert.doesNotMatch(prompt, /### S02 Summary/i, "prompt should not inline skipped slice summaries"); + assert.doesNotMatch(prompt, /not found — file does not exist yet/i, "prompt should not emit skipped-slice missing-file placeholders"); + } finally { + cleanup(base); + } +}); + // ─── Dispatch rule ──────────────────────────────────────────────────────── test("dispatch rule matches validating-milestone phase", async () => { diff --git a/src/resources/extensions/gsd/tests/verdict-parser.test.ts b/src/resources/extensions/gsd/tests/verdict-parser.test.ts new file mode 100644 index 000000000..c8aafea8c --- /dev/null +++ b/src/resources/extensions/gsd/tests/verdict-parser.test.ts @@ -0,0 +1,156 @@ +/** + * Tests for verdict-parser.ts — extraction, normalization, and schema validation. + * + * Regression tests for #2960: extractVerdict() must detect verdicts in both + * YAML frontmatter and common markdown body patterns (LLM manual writes). + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { + extractVerdict, + hasVerdict, + isAcceptableUatVerdict, + isValidMilestoneVerdict, +} from "../verdict-parser.ts"; + +// ── extractVerdict ────────────────────────────────────────────────────────── + +describe("extractVerdict", () => { + it("extracts verdict from YAML frontmatter", () => { + const content = "---\nverdict: pass\n---\n\n# Validation"; + assert.equal(extractVerdict(content), "pass"); + }); + + it("normalizes 'passed' to 'pass' in frontmatter", () => { + const content = "---\nverdict: passed\n---\n"; + assert.equal(extractVerdict(content), "pass"); + }); + + it("extracts case-insensitive verdict from frontmatter", () => { + const content = "---\nVerdict: PASS\n---\n"; + assert.equal(extractVerdict(content), "pass"); + }); + + it("extracts needs-remediation from frontmatter", () => { + const content = "---\nverdict: needs-remediation\n---\n"; + assert.equal(extractVerdict(content), "needs-remediation"); + }); + + it("returns undefined when content has no frontmatter and no markdown verdict", () => { + const content = "# Just a heading\n\nSome text without any verdict."; + assert.equal(extractVerdict(content), undefined); + }); + + // ── Regression: #2960 — markdown body verdicts ───────────────────────── + + it("detects **Verdict:** PASS in markdown body (#2960)", () => { + const content = [ + "# M013 — Milestone Validation", + "", + "**Verdict:** PASS", + "", + "All slices completed successfully.", + ].join("\n"); + assert.equal(extractVerdict(content), "pass"); + }); + + it("detects **Verdict:** with emoji prefix in markdown body (#2960)", () => { + const content = [ + "# Milestone Validation", + "", + "**Verdict:** ✅ PASS", + "", + "Everything looks good.", + ].join("\n"); + assert.equal(extractVerdict(content), "pass"); + }); + + it("detects **Verdict:** needs-remediation in markdown body (#2960)", () => { + const content = [ + "# Milestone Validation", + "", + "**Verdict:** needs-remediation", + "", + "Several issues found.", + ].join("\n"); + assert.equal(extractVerdict(content), "needs-remediation"); + }); + + it("normalizes 'passed' to 'pass' in markdown body (#2960)", () => { + const content = "# Validation\n\n**Verdict:** Passed\n"; + assert.equal(extractVerdict(content), "pass"); + }); + + it("detects verdict without colon in bold pattern (#2960)", () => { + const content = "# Validation\n\n**Verdict** PASS\n"; + assert.equal(extractVerdict(content), "pass"); + }); + + it("prefers frontmatter verdict over markdown body", () => { + const content = [ + "---", + "verdict: needs-remediation", + "---", + "", + "**Verdict:** PASS", + ].join("\n"); + assert.equal(extractVerdict(content), "needs-remediation"); + }); +}); + +// ── hasVerdict ──────────────────────────────────────────────────────────── + +describe("hasVerdict", () => { + it("returns true when verdict field exists", () => { + assert.equal(hasVerdict("verdict: pass"), true); + }); + + it("returns false when no verdict field exists", () => { + assert.equal(hasVerdict("# Just a heading"), false); + }); +}); + +// ── isAcceptableUatVerdict ─────────────────────────────────────────────── + +describe("isAcceptableUatVerdict", () => { + it("accepts pass verdict", () => { + assert.equal(isAcceptableUatVerdict("pass", undefined), true); + }); + + it("accepts passed verdict", () => { + assert.equal(isAcceptableUatVerdict("passed", undefined), true); + }); + + it("rejects fail verdict", () => { + assert.equal(isAcceptableUatVerdict("fail", undefined), false); + }); + + it("accepts partial for mixed UAT type", () => { + assert.equal(isAcceptableUatVerdict("partial", "mixed"), true); + }); + + it("rejects partial for artifact-driven UAT type", () => { + assert.equal(isAcceptableUatVerdict("partial", "artifact-driven"), false); + }); +}); + +// ── isValidMilestoneVerdict ────────────────────────────────────────────── + +describe("isValidMilestoneVerdict", () => { + it("accepts pass", () => { + assert.equal(isValidMilestoneVerdict("pass"), true); + }); + + it("accepts needs-attention", () => { + assert.equal(isValidMilestoneVerdict("needs-attention"), true); + }); + + it("accepts needs-remediation", () => { + assert.equal(isValidMilestoneVerdict("needs-remediation"), true); + }); + + it("rejects unknown verdict", () => { + assert.equal(isValidMilestoneVerdict("fail"), false); + }); +}); diff --git a/src/resources/extensions/gsd/tests/verification-operational-gate.test.ts b/src/resources/extensions/gsd/tests/verification-operational-gate.test.ts new file mode 100644 index 000000000..65a6779c3 --- /dev/null +++ b/src/resources/extensions/gsd/tests/verification-operational-gate.test.ts @@ -0,0 +1,108 @@ +/** + * Regression test for #2931: completing-milestone gate should treat + * "None required", "N/A", "Not applicable", etc. as equivalent to "none" + * and skip the operational verification content check entirely. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; + +import { isVerificationNotApplicable } from "../auto-dispatch.ts"; + +test("isVerificationNotApplicable: bare 'none' is not applicable", () => { + assert.equal(isVerificationNotApplicable("none"), true); +}); + +test("isVerificationNotApplicable: 'None' (capitalized) is not applicable", () => { + assert.equal(isVerificationNotApplicable("None"), true); +}); + +test("isVerificationNotApplicable: 'NONE' (uppercase) is not applicable", () => { + assert.equal(isVerificationNotApplicable("NONE"), true); +}); + +test("isVerificationNotApplicable: 'None required' is not applicable (#2931)", () => { + assert.equal(isVerificationNotApplicable("None required"), true); +}); + +test("isVerificationNotApplicable: 'None needed' is not applicable", () => { + assert.equal(isVerificationNotApplicable("None needed"), true); +}); + +test("isVerificationNotApplicable: 'None planned' is not applicable", () => { + assert.equal(isVerificationNotApplicable("None planned"), true); +}); + +test("isVerificationNotApplicable: 'None — ' is not applicable (#3897)", () => { + assert.equal( + isVerificationNotApplicable("None — no new background jobs, workers, or lifecycle changes introduced."), + true, + ); +}); + +test("isVerificationNotApplicable: em dash without spaces is not applicable (#3897)", () => { + assert.equal(isVerificationNotApplicable("none—inline"), true); +}); + +test("isVerificationNotApplicable: 'N/A' is not applicable", () => { + assert.equal(isVerificationNotApplicable("N/A"), true); +}); + +test("isVerificationNotApplicable: 'n/a' is not applicable", () => { + assert.equal(isVerificationNotApplicable("n/a"), true); +}); + +test("isVerificationNotApplicable: 'Not applicable' is not applicable", () => { + assert.equal(isVerificationNotApplicable("Not applicable"), true); +}); + +test("isVerificationNotApplicable: 'Not required' is not applicable", () => { + assert.equal(isVerificationNotApplicable("Not required"), true); +}); + +test("isVerificationNotApplicable: 'Not needed' is not applicable", () => { + assert.equal(isVerificationNotApplicable("Not needed"), true); +}); + +test("isVerificationNotApplicable: 'No operational verification needed' is not applicable", () => { + assert.equal(isVerificationNotApplicable("No operational verification needed"), true); +}); + +test("isVerificationNotApplicable: 'No operational' is not applicable", () => { + assert.equal(isVerificationNotApplicable("No operational"), true); +}); + +test("isVerificationNotApplicable: empty string is not applicable", () => { + assert.equal(isVerificationNotApplicable(""), true); +}); + +test("isVerificationNotApplicable: whitespace-only is not applicable", () => { + assert.equal(isVerificationNotApplicable(" "), true); +}); + +// Positive cases: these SHOULD require verification +test("isVerificationNotApplicable: 'Run load tests' requires verification", () => { + assert.equal(isVerificationNotApplicable("Run load tests"), false); +}); + +test("isVerificationNotApplicable: 'Verify API response times under load' requires verification", () => { + assert.equal(isVerificationNotApplicable("Verify API response times under load"), false); +}); + +test("isVerificationNotApplicable: 'Monitor error rates for 24h' requires verification", () => { + assert.equal(isVerificationNotApplicable("Monitor error rates for 24h"), false); +}); + +// Regression: #3634 — "Not provided." default from plan-milestone +test("isVerificationNotApplicable: 'Not provided.' is not applicable (#3634)", () => { + assert.equal(isVerificationNotApplicable("Not provided."), true); +}); + +test("isVerificationNotApplicable: 'Not provided' (no period) is not applicable (#3634)", () => { + assert.equal(isVerificationNotApplicable("Not provided"), true); +}); + +test("isVerificationNotApplicable: trailing period does not defeat match (#3634)", () => { + assert.equal(isVerificationNotApplicable("None required."), true); + assert.equal(isVerificationNotApplicable("N/A."), true); + assert.equal(isVerificationNotApplicable("Not applicable."), true); +}); diff --git a/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts b/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts new file mode 100644 index 000000000..1a64299d2 --- /dev/null +++ b/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts @@ -0,0 +1,89 @@ +/** + * Regression test for #3607 — tighten verifyExpectedArtifact legacy branch + * + * The legacy (pre-migration) fallback in verifyExpectedArtifact previously + * accepted either a heading match (### T01 --) or a checked checkbox as proof + * that gsd_complete_task ran. A heading alone does not prove completion — + * it could result from a rogue write. + * + * The fix removes the hdRe heading regex and requires only a checked checkbox + * (cbRe) in the legacy branch, ensuring that only actual tool-completed tasks + * are treated as verified. + */ + +import { describe, it } from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' + +const src = readFileSync( + resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'auto-recovery.ts'), + 'utf-8', +) + +describe('verifyExpectedArtifact legacy branch tightened (#3607)', () => { + it('legacy branch does NOT define hdRe heading regex', () => { + // Find the legacy fallback section + const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback') + assert.ok(legacyIdx !== -1, 'LEGACY comment must exist') + + // Check the code within a reasonable window after the LEGACY comment + const legacyBlock = src.slice(legacyIdx, legacyIdx + 600) + + assert.ok( + !legacyBlock.includes('hdRe'), + 'hdRe heading regex must NOT exist in legacy branch — heading alone is not proof of completion', + ) + }) + + it('legacy branch requires checked checkbox via cbRe', () => { + const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback') + assert.ok(legacyIdx !== -1) + + const legacyBlock = src.slice(legacyIdx, legacyIdx + 600) + + assert.ok( + legacyBlock.includes('cbRe'), + 'cbRe checked-checkbox regex must exist in legacy branch', + ) + + // cbRe must match checked checkboxes [x] or [X] + assert.ok( + legacyBlock.includes('[xX]'), + 'cbRe must match both [x] and [X] checkbox variants', + ) + }) + + it('legacy branch returns false when no plan file exists', () => { + const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback') + assert.ok(legacyIdx !== -1) + + const legacyBlock = src.slice(legacyIdx, legacyIdx + 1000) + + // The else branch: no plan file means cannot verify + assert.ok( + legacyBlock.includes('no plan file'), + 'missing plan file must be handled with return false', + ) + }) + + it('DB available but task not found returns false', () => { + const legacyIdx = src.indexOf('LEGACY: Pre-migration fallback') + assert.ok(legacyIdx !== -1) + + const legacyBlock = src.slice(legacyIdx, legacyIdx + 1000) + + assert.ok( + legacyBlock.includes('DB available but task row not found'), + 'must handle case where DB is available but task row is missing', + ) + + // The comment should be followed by a return false + const commentIdx = legacyBlock.indexOf('DB available but task row not found') + const afterComment = legacyBlock.slice(commentIdx, commentIdx + 200) + assert.ok( + afterComment.includes('return false'), + 'missing task row when DB available must return false', + ) + }) +}) diff --git a/src/resources/extensions/gsd/tests/visualizer-overlay.test.ts b/src/resources/extensions/gsd/tests/visualizer-overlay.test.ts index db3e18d4e..a0743679e 100644 --- a/src/resources/extensions/gsd/tests/visualizer-overlay.test.ts +++ b/src/resources/extensions/gsd/tests/visualizer-overlay.test.ts @@ -233,3 +233,62 @@ assert.ok( overlaySrc.includes('from "../shared/mod.js"'), "imports from shared barrel", ); + +test("visualizer overlay closes on escape in filter and help submodes", async () => { + const mod = await import("../visualizer-overlay.js"); + + const mockTui = { requestRender: () => {} }; + const mockTheme = { + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + + let closedFilter = false; + const filterOverlay = new mod.GSDVisualizerOverlay( + mockTui, + mockTheme as any, + () => { closedFilter = true; }, + ); + filterOverlay.filterMode = true; + filterOverlay.handleInput("\u0003"); + assert.equal(closedFilter, true, "Ctrl+C closes while filter mode is active"); + filterOverlay.dispose(); + + let closedHelp = false; + const helpOverlay = new mod.GSDVisualizerOverlay( + mockTui, + mockTheme as any, + () => { closedHelp = true; }, + ); + helpOverlay.showHelp = true; + helpOverlay.handleInput("\u001b"); + assert.equal(closedHelp, true, "Escape closes while help overlay is visible"); + helpOverlay.dispose(); +}); + +test("visualizer overlay tab hitboxes include rendered badges", async () => { + const mod = await import("../visualizer-overlay.js"); + + const mockTui = { requestRender: () => {} }; + const mockTheme = { + fg: (_color: string, text: string) => text, + bold: (text: string) => text, + }; + + const overlay = new mod.GSDVisualizerOverlay( + mockTui, + mockTheme as any, + () => {}, + ); + overlay.loading = true; + overlay.data = { captures: { pendingCount: 3 } } as any; + + const lines = overlay.render(120); + const tabLine = lines.find((line: string) => line.includes("Captures") && line.includes("(3)")); + assert.ok(tabLine, "rendered tab bar includes captures badge"); + const plain = tabLine!.replace(/\x1b\[[0-9;]*m/g, ""); + const badgeColumn = plain.indexOf("(3)") + 2; + overlay.handleInput(`\x1b[<0;${badgeColumn};2M`); + assert.equal(overlay.activeTab, 8, "clicking the badge area selects the captures tab"); + overlay.dispose(); +}); diff --git a/src/resources/extensions/gsd/tests/wave1-critical-regressions.test.ts b/src/resources/extensions/gsd/tests/wave1-critical-regressions.test.ts new file mode 100644 index 000000000..4ec804895 --- /dev/null +++ b/src/resources/extensions/gsd/tests/wave1-critical-regressions.test.ts @@ -0,0 +1,49 @@ +// GSD State Machine — Wave 1 Critical Regression Tests +// Validates fixes for event log format mismatch, skipped milestone status, +// dead code removal, and replan disk-file fallback. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { extractEntityKey } from "../workflow-reconcile.js"; +import { isClosedStatus } from "../status-guards.js"; +import type { WorkflowEvent } from "../workflow-events.js"; + +// ── Fix 1: Event log cmd format — hyphens and underscores both accepted ── + +describe("extractEntityKey normalizes cmd format", () => { + const baseEvent = { params: {}, ts: "", hash: "", actor: "agent" as const, session_id: "" }; + + test("accepts hyphenated complete-task", () => { + const event: WorkflowEvent = { ...baseEvent, cmd: "complete-task", params: { taskId: "T01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "task", id: "T01" }); + }); + + test("accepts underscored complete_task (legacy)", () => { + const event: WorkflowEvent = { ...baseEvent, cmd: "complete_task", params: { taskId: "T01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "task", id: "T01" }); + }); + + test("accepts hyphenated complete-slice", () => { + const event: WorkflowEvent = { ...baseEvent, cmd: "complete-slice", params: { sliceId: "S01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "slice", id: "S01" }); + }); + + test("accepts hyphenated complete-milestone", () => { + const event: WorkflowEvent = { ...baseEvent, cmd: "complete-milestone", params: { milestoneId: "M001" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "milestone", id: "M001" }); + }); +}); + +// ── Fix 3: getActiveMilestoneId must skip "skipped" milestones ── + +describe("isClosedStatus includes skipped", () => { + test("complete is closed", () => assert.ok(isClosedStatus("complete"))); + test("done is closed", () => assert.ok(isClosedStatus("done"))); + test("skipped is closed", () => assert.ok(isClosedStatus("skipped"))); + test("pending is not closed", () => assert.ok(!isClosedStatus("pending"))); + test("active is not closed", () => assert.ok(!isClosedStatus("active"))); +}); diff --git a/src/resources/extensions/gsd/tests/wave2-events-regressions.test.ts b/src/resources/extensions/gsd/tests/wave2-events-regressions.test.ts new file mode 100644 index 000000000..d7673a9ab --- /dev/null +++ b/src/resources/extensions/gsd/tests/wave2-events-regressions.test.ts @@ -0,0 +1,48 @@ +// GSD State Machine — Wave 2 Event Log Regression Tests +// Validates fixes for appendEvent isolation, entity replay handlers, +// and post-reconcile cache invalidation. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { extractEntityKey } from "../workflow-reconcile.js"; +import type { WorkflowEvent } from "../workflow-events.js"; + +const base = { params: {}, ts: "", hash: "", actor: "agent" as const, session_id: "" }; + +// ── Fix 8: New entity event types handled by extractEntityKey ── + +describe("extractEntityKey handles plan events", () => { + test("plan-milestone → milestone type", () => { + const event: WorkflowEvent = { ...base, cmd: "plan-milestone", params: { milestoneId: "M001" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "milestone", id: "M001" }); + }); + + test("plan-task → task type", () => { + const event: WorkflowEvent = { ...base, cmd: "plan-task", params: { taskId: "T01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "task", id: "T01" }); + }); + + test("plan-slice preserves slice_plan type (conflict isolation)", () => { + const event: WorkflowEvent = { ...base, cmd: "plan-slice", params: { sliceId: "S01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "slice_plan", id: "S01" }); + }); + + test("replan-slice → slice type", () => { + const event: WorkflowEvent = { ...base, cmd: "replan-slice", params: { sliceId: "S01" } }; + const key = extractEntityKey(event); + assert.deepStrictEqual(key, { type: "slice", id: "S01" }); + }); +}); + +// ── Fix 8b: Unknown commands return null (don't crash) ── + +describe("extractEntityKey handles unknown commands gracefully", () => { + test("unknown-command returns null", () => { + const event: WorkflowEvent = { ...base, cmd: "unknown-future-cmd", params: { foo: "bar" } }; + const key = extractEntityKey(event); + assert.strictEqual(key, null); + }); +}); diff --git a/src/resources/extensions/gsd/tests/wave3-session-regressions.test.ts b/src/resources/extensions/gsd/tests/wave3-session-regressions.test.ts new file mode 100644 index 000000000..821f79aa1 --- /dev/null +++ b/src/resources/extensions/gsd/tests/wave3-session-regressions.test.ts @@ -0,0 +1,47 @@ +// GSD State Machine — Wave 3 Session Regression Tests +// Validates tri-state hasImplementationArtifacts and AutoSession.consecutiveCompleteBootstraps. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { hasImplementationArtifacts } from "../auto-recovery.js"; +import { AutoSession } from "../auto/session.js"; + +// ── Fix 9: hasImplementationArtifacts returns tri-state ── + +describe("hasImplementationArtifacts tri-state return", () => { + test("returns 'unknown' for non-git directory", () => { + const result = hasImplementationArtifacts("/tmp/not-a-git-repo-" + Date.now()); + assert.strictEqual(result, "unknown"); + }); + + test("return type is one of present/absent/unknown", () => { + const result = hasImplementationArtifacts(process.cwd()); + assert.ok( + result === "present" || result === "absent" || result === "unknown", + `Expected present/absent/unknown, got: ${result}`, + ); + }); +}); + +// ── Fix 11: consecutiveCompleteBootstraps is per-session ── + +describe("AutoSession.consecutiveCompleteBootstraps", () => { + test("initial value is 0", () => { + const s = new AutoSession(); + assert.strictEqual(s.consecutiveCompleteBootstraps, 0); + }); + + test("reset() clears the counter", () => { + const s = new AutoSession(); + s.consecutiveCompleteBootstraps = 5; + s.reset(); + assert.strictEqual(s.consecutiveCompleteBootstraps, 0); + }); + + test("two sessions have independent counters", () => { + const s1 = new AutoSession(); + const s2 = new AutoSession(); + s1.consecutiveCompleteBootstraps = 3; + assert.strictEqual(s2.consecutiveCompleteBootstraps, 0); + }); +}); diff --git a/src/resources/extensions/gsd/tests/wave4-write-safety-regressions.test.ts b/src/resources/extensions/gsd/tests/wave4-write-safety-regressions.test.ts new file mode 100644 index 000000000..c5d12a51c --- /dev/null +++ b/src/resources/extensions/gsd/tests/wave4-write-safety-regressions.test.ts @@ -0,0 +1,70 @@ +// GSD State Machine — Wave 4 Write Safety Regression Tests +// Validates randomized tmp suffix in json-persistence and atomic writes. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { saveJsonFile, loadJsonFile } from "../json-persistence.js"; + +// ── Fix 15: json-persistence uses randomized tmp suffix ── + +describe("saveJsonFile atomic write", () => { + test("writes JSON file correctly", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-json-test-")); + try { + const file = join(tmp, "test.json"); + saveJsonFile(file, { key: "value" }); + const content = JSON.parse(readFileSync(file, "utf-8")); + assert.deepStrictEqual(content, { key: "value" }); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("no .tmp file left after successful write", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-json-test-")); + try { + const file = join(tmp, "test.json"); + saveJsonFile(file, { data: 123 }); + const files = readdirSync(tmp); + const tmpFiles = files.filter((f: string) => f.includes(".tmp")); + assert.strictEqual(tmpFiles.length, 0, "No .tmp files should remain after write"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("concurrent writes don't corrupt data", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-json-test-")); + try { + const file = join(tmp, "shared.json"); + // Write two different values rapidly — both should succeed without corruption + saveJsonFile(file, { writer: "first" }); + saveJsonFile(file, { writer: "second" }); + const content = JSON.parse(readFileSync(file, "utf-8")); + assert.strictEqual(content.writer, "second"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); + + test("round-trip through loadJsonFile", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-json-test-")); + try { + const file = join(tmp, "roundtrip.json"); + const data = { items: [1, 2, 3], name: "test" }; + saveJsonFile(file, data); + const loaded = loadJsonFile( + file, + (d): d is typeof data => typeof d === "object" && d !== null && "items" in d, + () => ({ items: [], name: "" }), + ); + assert.deepStrictEqual(loaded.items, [1, 2, 3]); + assert.strictEqual(loaded.name, "test"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); diff --git a/src/resources/extensions/gsd/tests/wave5-consistency-regressions.test.ts b/src/resources/extensions/gsd/tests/wave5-consistency-regressions.test.ts new file mode 100644 index 000000000..d128b993d --- /dev/null +++ b/src/resources/extensions/gsd/tests/wave5-consistency-regressions.test.ts @@ -0,0 +1,165 @@ +// GSD State Machine — Wave 5 Consistency Regression Tests +// Validates isClosedStatus usage in projections, upsertDecision seq preservation, +// event schema versioning, and replay round-trip with mixed cmd formats. + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { isClosedStatus } from "../status-guards.js"; +import { openDatabase, closeDatabase, upsertDecision, _getAdapter, insertMilestone, insertSlice, insertTask, getTask } from "../gsd-db.js"; +import { extractEntityKey } from "../workflow-reconcile.js"; +import type { WorkflowEvent } from "../workflow-events.js"; + +// ── Fix 19: isClosedStatus covers all closed statuses ── + +describe("isClosedStatus used by projections", () => { + test("skipped is closed (projections now show checked)", () => { + assert.ok(isClosedStatus("skipped")); + }); + test("complete is closed", () => { + assert.ok(isClosedStatus("complete")); + }); + test("done is closed", () => { + assert.ok(isClosedStatus("done")); + }); + test("in-progress is not closed", () => { + assert.ok(!isClosedStatus("in-progress")); + }); +}); + +// ── Fix 20: upsertDecision preserves seq on update ── + +describe("upsertDecision preserves seq column", () => { + test("seq is preserved when decision is re-upserted", () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-upsert-test-")); + const dbPath = join(tmp, "gsd.db"); + try { + openDatabase(dbPath); + const adapter = _getAdapter(); + assert.ok(adapter, "adapter must be available"); + + // Insert two decisions + upsertDecision({ + id: "D001", when_context: "ctx1", scope: "s1", + decision: "d1", choice: "c1", rationale: "r1", + revisable: "yes", made_by: "agent", superseded_by: null, + }); + upsertDecision({ + id: "D002", when_context: "ctx2", scope: "s2", + decision: "d2", choice: "c2", rationale: "r2", + revisable: "yes", made_by: "agent", superseded_by: null, + }); + + // Get original seq values + const rows1 = adapter.prepare("SELECT id, seq FROM decisions ORDER BY seq").all() as Array<{ id: string; seq: number }>; + assert.strictEqual(rows1[0].id, "D001"); + assert.strictEqual(rows1[1].id, "D002"); + const d001OriginalSeq = rows1[0].seq; + + // Re-upsert D001 with updated content + upsertDecision({ + id: "D001", when_context: "updated", scope: "s1", + decision: "d1-updated", choice: "c1", rationale: "r1", + revisable: "yes", made_by: "agent", superseded_by: null, + }); + + // Verify seq is preserved (not moved to end) + const rows2 = adapter.prepare("SELECT id, seq FROM decisions ORDER BY seq").all() as Array<{ id: string; seq: number }>; + assert.strictEqual(rows2[0].id, "D001", "D001 should still be first by seq"); + assert.strictEqual(rows2[0].seq, d001OriginalSeq, "D001 seq should be preserved"); + assert.strictEqual(rows2[1].id, "D002", "D002 should still be second"); + + // Verify content was updated + const updated = adapter.prepare("SELECT decision FROM decisions WHERE id = 'D001'").get() as { decision: string }; + assert.strictEqual(updated.decision, "d1-updated"); + + closeDatabase(); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// ── Fix 23: Event schema versioning ── + +describe("WorkflowEvent v field", () => { + test("appendEvent includes v:2 in output", async () => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-event-v-test-")); + try { + const { appendEvent } = await import("../workflow-events.js"); + appendEvent(tmp, { + cmd: "test-event", + params: { foo: "bar" }, + ts: new Date().toISOString(), + actor: "system", + }); + + const logPath = join(tmp, ".gsd", "event-log.jsonl"); + const line = readFileSync(logPath, "utf-8").trim(); + const event = JSON.parse(line); + assert.strictEqual(event.v, 2, "New events should have v:2"); + assert.strictEqual(event.cmd, "test-event"); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } + }); +}); + +// ── Fix 19 (behavior-level): Projection rendering with skipped tasks ── + +describe("isClosedStatus drives projection checkbox logic", () => { + test("skipped task produces checked checkbox via isClosedStatus", () => { + // This tests the behavior contract that projections rely on: + // workflow-projections.ts uses isClosedStatus() to determine checkbox state. + // "skipped" tasks must render as [x], not [ ]. + const statuses = ["complete", "done", "skipped"]; + for (const status of statuses) { + assert.ok( + isClosedStatus(status), + `status "${status}" must be closed so projections render [x]`, + ); + } + // Non-closed statuses must render as [ ] + for (const status of ["pending", "in-progress", "blocked", "active"]) { + assert.ok( + !isClosedStatus(status), + `status "${status}" must NOT be closed so projections render [ ]`, + ); + } + }); +}); + +// ── extractEntityKey: underscored cmds are recognized (Wave 5 scope) ── +// Note: hyphenated cmd normalization is in Wave 1. These tests validate +// the underscored format that Wave 5's extractEntityKey handles directly. + +describe("extractEntityKey recognizes underscored cmds", () => { + const base: WorkflowEvent = { cmd: "", params: {}, ts: "", hash: "", actor: "agent", session_id: "" }; + + test("complete_task → task entity", () => { + const key = extractEntityKey({ ...base, cmd: "complete_task", params: { taskId: "T01" } }); + assert.deepStrictEqual(key, { type: "task", id: "T01" }); + }); + + test("complete_slice → slice entity", () => { + const key = extractEntityKey({ ...base, cmd: "complete_slice", params: { sliceId: "S01" } }); + assert.deepStrictEqual(key, { type: "slice", id: "S01" }); + }); + + test("plan_slice → slice_plan entity (distinct from complete)", () => { + const key = extractEntityKey({ ...base, cmd: "plan_slice", params: { sliceId: "S01" } }); + assert.deepStrictEqual(key, { type: "slice_plan", id: "S01" }); + }); + + test("save_decision → decision entity", () => { + const key = extractEntityKey({ ...base, cmd: "save_decision", params: { scope: "s", decision: "d" } }); + assert.deepStrictEqual(key, { type: "decision", id: "s:d" }); + }); + + test("unknown cmd returns null (not crash)", () => { + const key = extractEntityKey({ ...base, cmd: "future_unknown_cmd", params: {} }); + assert.strictEqual(key, null); + }); +}); diff --git a/src/resources/extensions/gsd/tests/worker-model-override.test.ts b/src/resources/extensions/gsd/tests/worker-model-override.test.ts new file mode 100644 index 000000000..0b1e49edf --- /dev/null +++ b/src/resources/extensions/gsd/tests/worker-model-override.test.ts @@ -0,0 +1,48 @@ +/** + * Worker model override — tests for parallel.worker_model preference. + * + * Verifies validation, resolveParallelConfig pass-through, and type definitions. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +const typesSrc = readFileSync(join(__dirname, "..", "types.ts"), "utf-8"); +const validationSrc = readFileSync(join(__dirname, "..", "preferences-validation.ts"), "utf-8"); +const preferencesSrc = readFileSync(join(__dirname, "..", "preferences.ts"), "utf-8"); + +// ─── Type definition ────────────────────────────────────────────────────── + +test("ParallelConfig includes worker_model optional field", () => { + assert.ok( + typesSrc.includes("worker_model?: string"), + "ParallelConfig should have optional worker_model field", + ); +}); + +// ─── Validation ─────────────────────────────────────────────────────────── + +test("validatePreferences accepts valid worker_model string", () => { + assert.ok( + validationSrc.includes("p.worker_model"), + "validation should check parallel.worker_model", + ); + assert.ok( + validationSrc.includes('parallel.worker_model must be a non-empty string'), + "validation should reject invalid worker_model", + ); +}); + +// ─── resolveParallelConfig ──────────────────────────────────────────────── + +test("resolveParallelConfig passes through worker_model", () => { + assert.ok( + preferencesSrc.includes("worker_model: prefs?.parallel?.worker_model"), + "resolveParallelConfig should pass through worker_model", + ); +}); diff --git a/src/resources/extensions/gsd/tests/workflow-logger-audit.test.ts b/src/resources/extensions/gsd/tests/workflow-logger-audit.test.ts new file mode 100644 index 000000000..1c63b60bd --- /dev/null +++ b/src/resources/extensions/gsd/tests/workflow-logger-audit.test.ts @@ -0,0 +1,123 @@ +// GSD Extension — Workflow Logger Audit Persistence Tests +// Validates error-only persistence, sanitization, and warning ephemeral behavior. + +import { describe, test, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, readFileSync, existsSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + logWarning, + logError, + setLogBasePath, + _resetLogs, + peekLogs, + drainLogs, +} from "../workflow-logger.ts"; + +function createTempProject(): string { + const tmp = mkdtempSync(join(tmpdir(), "gsd-wflog-test-")); + mkdirSync(join(tmp, ".gsd"), { recursive: true }); + return tmp; +} + +function readAuditLines(basePath: string): Record[] { + const auditPath = join(basePath, ".gsd", "audit-log.jsonl"); + if (!existsSync(auditPath)) return []; + const content = readFileSync(auditPath, "utf-8").trim(); + if (!content) return []; + return content.split("\n").map((line) => JSON.parse(line)); +} + +describe("workflow-logger audit persistence", () => { + let tmp: string; + + beforeEach(() => { + tmp = createTempProject(); + _resetLogs(); + setLogBasePath(tmp); + }); + + afterEach(() => { + _resetLogs(); + setLogBasePath(null as unknown as string); + rmSync(tmp, { recursive: true, force: true }); + }); + + test("logError persists to audit-log.jsonl", () => { + logError("engine", "something broke"); + const lines = readAuditLines(tmp); + assert.equal(lines.length, 1); + assert.equal(lines[0].severity, "error"); + assert.equal(lines[0].component, "engine"); + }); + + test("logWarning does NOT persist to audit-log.jsonl", () => { + logWarning("engine", "something fishy"); + const lines = readAuditLines(tmp); + assert.equal(lines.length, 0, "warnings must not be persisted to audit log"); + }); + + test("logWarning still appears in in-memory buffer", () => { + logWarning("recovery", "probe miss"); + const entries = peekLogs(); + assert.equal(entries.length, 1); + assert.equal(entries[0].severity, "warn"); + assert.equal(entries[0].component, "recovery"); + }); + + test("persisted error messages are truncated at 200 chars", () => { + const longMessage = "x".repeat(300); + logError("engine", longMessage); + const lines = readAuditLines(tmp); + assert.equal(lines.length, 1); + const msg = lines[0].message as string; + assert.ok(msg.length <= 215, `message should be truncated, got ${msg.length} chars`); + assert.ok(msg.endsWith("…[truncated]")); + }); + + test("persisted errors have context filtered to safe allowlist", () => { + logError("tool", "tool failed", { + fn: "saveDecisionToDb", + tool: "gsd_decision_save", + error: "SQLITE_BUSY: database is locked", + file: "/home/user/project/gsd.db", + }); + const lines = readAuditLines(tmp); + assert.equal(lines.length, 1); + const ctx = lines[0].context as Record; + assert.ok(ctx, "context should exist"); + assert.equal(ctx.fn, "saveDecisionToDb"); + assert.equal(ctx.tool, "gsd_decision_save"); + assert.equal(ctx.error, "SQLITE_BUSY: database is locked", "error key should be preserved in persisted context"); + assert.equal(ctx.file, undefined, "file key must be stripped from persisted context"); + }); + + test("persisted errors preserve error key but strip other unsafe keys", () => { + logError("bootstrap", "ensureDbOpen failed", { + error: "ENOENT", + cwd: "/home/user/project", + }); + const lines = readAuditLines(tmp); + assert.equal(lines.length, 1); + const ctx = lines[0].context as Record; + assert.ok(ctx, "context should exist when error key is present"); + assert.equal(ctx.error, "ENOENT", "error key should be preserved"); + assert.equal(ctx.cwd, undefined, "cwd key must be stripped"); + }); + + test("mixed warnings and errors only persist errors", () => { + logWarning("recovery", "main not found"); + logWarning("recovery", "master not found"); + logError("engine", "fatal failure"); + logWarning("prompt", "cache miss"); + + const lines = readAuditLines(tmp); + assert.equal(lines.length, 1, "only the error should be persisted"); + assert.equal(lines[0].severity, "error"); + + const buffered = drainLogs(); + assert.equal(buffered.length, 4, "all entries should be in the in-memory buffer"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/workflow-logger.test.ts b/src/resources/extensions/gsd/tests/workflow-logger.test.ts index 015e4ff85..9af623bd5 100644 --- a/src/resources/extensions/gsd/tests/workflow-logger.test.ts +++ b/src/resources/extensions/gsd/tests/workflow-logger.test.ts @@ -18,6 +18,7 @@ import { summarizeLogs, formatForNotification, setLogBasePath, + setStderrLoggingEnabled, _resetLogs, } from "../workflow-logger.ts"; @@ -217,12 +218,26 @@ describe("workflow-logger", () => { assert.ok(formatted.includes("\n")); }); - test("does not include context in formatted output", () => { + test("includes context fields in formatted output", () => { logError("tool", "failed", { cmd: "complete_task" }); const entries = drainLogs(); const formatted = formatForNotification(entries); - assert.equal(formatted, "[tool] failed"); - assert.ok(!formatted.includes("complete_task")); + assert.equal(formatted, "[tool] failed (cmd: complete_task)"); + }); + + test("excludes error key from context to avoid redundancy", () => { + logError("tool", "disk write failed", { error: "ENOSPC", path: "/tmp/foo" }); + const entries = drainLogs(); + const formatted = formatForNotification(entries); + assert.ok(formatted.includes("path: /tmp/foo")); + assert.ok(!formatted.includes("error: ENOSPC")); + }); + + test("formats entry without context unchanged", () => { + logError("intercept", "blocked write"); + const entries = drainLogs(); + const formatted = formatForNotification(entries); + assert.equal(formatted, "[intercept] blocked write"); }); }); @@ -240,13 +255,13 @@ describe("workflow-logger", () => { test("writes entry to .gsd/audit-log.jsonl after setLogBasePath", () => { setLogBasePath(dir); - logWarning("engine", "audit test entry"); + logError("engine", "audit test entry"); const auditPath = join(dir, ".gsd", "audit-log.jsonl"); assert.ok(existsSync(auditPath), "audit-log.jsonl should exist"); const content = readFileSync(auditPath, "utf-8"); const entry = JSON.parse(content.trim()); - assert.equal(entry.severity, "warn"); + assert.equal(entry.severity, "error"); assert.equal(entry.component, "engine"); assert.equal(entry.message, "audit test entry"); }); @@ -254,7 +269,7 @@ describe("workflow-logger", () => { test("_resetLogs does not clear the audit base path", () => { setLogBasePath(dir); _resetLogs(); - logWarning("engine", "post-reset entry"); + logError("engine", "post-reset entry"); const auditPath = join(dir, ".gsd", "audit-log.jsonl"); assert.ok(existsSync(auditPath), "audit-log.jsonl should exist after _resetLogs"); @@ -279,41 +294,51 @@ describe("workflow-logger", () => { }); }); - describe("audit log persistence", () => { - let dir: string; - - beforeEach(() => { - dir = makeTempDir("wl-audit-"); + describe("new log components (db, dispatch)", () => { + test("logError with 'db' component stores correct component", () => { + logError("db", "failed to copy DB to worktree", { error: "ENOENT" }); + const entries = peekLogs(); + assert.equal(entries.length, 1); + assert.equal(entries[0].severity, "error"); + assert.equal(entries[0].component, "db"); + assert.equal(entries[0].message, "failed to copy DB to worktree"); + assert.deepEqual(entries[0].context, { error: "ENOENT" }); }); - afterEach(() => { - setLogBasePath(""); - cleanup(dir); + test("logError with 'dispatch' component stores correct component", () => { + logError("dispatch", "reactive graph derivation failed", { error: "timeout" }); + const entries = peekLogs(); + assert.equal(entries.length, 1); + assert.equal(entries[0].severity, "error"); + assert.equal(entries[0].component, "dispatch"); + assert.deepEqual(entries[0].context, { error: "timeout" }); }); - test("writes entry to .gsd/audit-log.jsonl after setLogBasePath", () => { - setLogBasePath(dir); - logWarning("engine", "audit test entry"); - - const auditPath = join(dir, ".gsd", "audit-log.jsonl"); - assert.ok(existsSync(auditPath), "audit-log.jsonl should exist"); - const content = readFileSync(auditPath, "utf-8"); - const entry = JSON.parse(content.trim()); - assert.equal(entry.severity, "warn"); - assert.equal(entry.component, "engine"); - assert.equal(entry.message, "audit test entry"); + test("logWarning with 'reconcile' component for centralized logging path", () => { + logWarning("reconcile", "could not acquire sync lock — another reconciliation may be in progress"); + const entries = peekLogs(); + assert.equal(entries.length, 1); + assert.equal(entries[0].severity, "warn"); + assert.equal(entries[0].component, "reconcile"); }); - test("_resetLogs does not clear the audit base path", () => { - setLogBasePath(dir); - _resetLogs(); - logWarning("engine", "post-reset entry"); + test("summarizeLogs includes db and dispatch entries", () => { + logError("db", "worktree DB reconciliation failed: path contains unsafe characters"); + logWarning("dispatch", "graph derivation timeout"); + const summary = summarizeLogs()!; + assert.ok(summary.includes("1 error(s)")); + assert.ok(summary.includes("1 warning(s)")); + assert.ok(summary.includes("unsafe characters")); + assert.ok(summary.includes("graph derivation timeout")); + }); - const auditPath = join(dir, ".gsd", "audit-log.jsonl"); - assert.ok(existsSync(auditPath), "audit-log.jsonl should exist after _resetLogs"); - const content = readFileSync(auditPath, "utf-8"); - const entry = JSON.parse(content.trim()); - assert.equal(entry.message, "post-reset entry"); + test("formatForNotification renders db and dispatch components", () => { + logError("db", "copy failed"); + logWarning("dispatch", "slow derivation"); + const entries = drainLogs(); + const formatted = formatForNotification(entries); + assert.ok(formatted.includes("[db] copy failed")); + assert.ok(formatted.includes("[dispatch] slow derivation")); }); }); @@ -351,5 +376,20 @@ describe("workflow-logger", () => { logError("tool", "failed", { cmd: "complete_task" }); assert.ok(written[0].includes('"cmd":"complete_task"')); }); + + test("suppresses stderr when disabled", (t) => { + const written: string[] = []; + const orig = process.stderr.write.bind(process.stderr); + const previous = setStderrLoggingEnabled(false); + // @ts-ignore — patching for test + process.stderr.write = (chunk: string) => { written.push(chunk); return true; }; + t.after(() => { + process.stderr.write = orig; + setStderrLoggingEnabled(previous); + }); + + logWarning("engine", "hidden warning"); + assert.deepEqual(written, []); + }); }); }); diff --git a/src/resources/extensions/gsd/tests/workflow-manifest.test.ts b/src/resources/extensions/gsd/tests/workflow-manifest.test.ts index fa0618cbb..5e4591f9d 100644 --- a/src/resources/extensions/gsd/tests/workflow-manifest.test.ts +++ b/src/resources/extensions/gsd/tests/workflow-manifest.test.ts @@ -12,6 +12,7 @@ import { insertMilestone, insertSlice, insertTask, + _getAdapter, } from '../gsd-db.ts'; import { writeManifest, @@ -165,6 +166,97 @@ test('workflow-manifest: bootstrapFromManifest restores DB from manifest (round- } }); +// ─── snapshotState: numeric column coercion (#2962) ───────────────────── + +test('workflow-manifest: snapshotState coerces string placeholders in numeric columns to null (#2962)', () => { + const base = tempDir(); + openDatabase(tempDbPath(base)); + try { + // Set up prerequisite rows + insertMilestone({ id: 'M001' }); + insertSlice({ id: 'S01', milestoneId: 'M001' }); + insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Task', status: 'complete' }); + + // Insert verification_evidence with string placeholders in numeric columns + // This simulates what happens after schema migrations or manual inserts + const db = _getAdapter()!; + db.prepare( + `INSERT INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + ).run('T01', 'S01', 'M001', 'npm test', '-', 'pass', '-', new Date().toISOString()); + + // snapshotState should coerce "-" to null for numeric columns + const snap = snapshotState(); + const ev = snap.verification_evidence[0]; + assert.strictEqual(ev.exit_code, null, 'exit_code "-" should be coerced to null'); + assert.strictEqual(ev.duration_ms, null, 'duration_ms "-" should be coerced to null'); + + // Round-trip through JSON should not throw + const json = JSON.stringify(snap, null, 2); + const reparsed = JSON.parse(json); + assert.strictEqual(reparsed.verification_evidence[0].exit_code, null); + assert.strictEqual(reparsed.verification_evidence[0].duration_ms, null); + } finally { + closeDatabase(); + cleanupDir(base); + } +}); + +test('workflow-manifest: snapshotState coerces empty string and N/A in numeric columns (#2962)', () => { + const base = tempDir(); + openDatabase(tempDbPath(base)); + try { + insertMilestone({ id: 'M001' }); + insertSlice({ id: 'S01', milestoneId: 'M001' }); + insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Task', status: 'complete' }); + + const db = _getAdapter()!; + db.prepare( + `INSERT INTO verification_evidence (task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, + ).run('T01', 'S01', 'M001', 'npm test', 'N/A', 'pass', '', new Date().toISOString()); + + const snap = snapshotState(); + const ev = snap.verification_evidence[0]; + assert.strictEqual(ev.exit_code, null, 'exit_code "N/A" should be coerced to null'); + assert.strictEqual(ev.duration_ms, null, 'duration_ms "" should be coerced to null'); + } finally { + closeDatabase(); + cleanupDir(base); + } +}); + +test('workflow-manifest: snapshotState coerces string placeholders in sequence columns (#2962)', () => { + const base = tempDir(); + openDatabase(tempDbPath(base)); + try { + insertMilestone({ id: 'M001' }); + + // Insert a slice with a string sequence via raw SQL + const db = _getAdapter()!; + db.prepare( + `INSERT INTO slices (milestone_id, id, title, status, risk, depends, demo, created_at, sequence) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, + ).run('M001', 'S01', 'Test Slice', 'planned', 'low', '[]', '', new Date().toISOString(), '-'); + + db.prepare( + `INSERT INTO tasks (milestone_id, slice_id, id, title, status, sequence) + VALUES (?, ?, ?, ?, ?, ?)`, + ).run('M001', 'S01', 'T01', 'Test Task', 'planned', 'N/A'); + + const snap = snapshotState(); + assert.strictEqual(snap.slices[0].sequence, 0, 'slice sequence "-" should be coerced to 0'); + assert.strictEqual(snap.tasks[0].sequence, 0, 'task sequence "N/A" should be coerced to 0'); + + // JSON round-trip must not throw + const json = JSON.stringify(snap, null, 2); + assert.doesNotThrow(() => JSON.parse(json)); + } finally { + closeDatabase(); + cleanupDir(base); + } +}); + // ─── readManifest: version check ───────────────────────────────────────── test('workflow-manifest: readManifest throws on unsupported version', () => { diff --git a/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts b/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts new file mode 100644 index 000000000..fabb15c3a --- /dev/null +++ b/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts @@ -0,0 +1,76 @@ +import test from "node:test"; +import assert from "node:assert/strict"; + +import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts"; + +test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => { + const result = shouldAutoPrepareWorkflowMcp({ + model: { provider: "claude-code", baseUrl: "local://claude-code" }, + modelRegistry: { + getProviderAuthMode: () => "externalCli", + isProviderRequestReady: () => false, + }, + }); + + assert.equal(result, true); +}); + +test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is ready", () => { + const result = shouldAutoPrepareWorkflowMcp({ + model: { provider: "openai", baseUrl: "https://api.openai.com" }, + modelRegistry: { + getProviderAuthMode: () => "apiKey", + isProviderRequestReady: (provider: string) => provider === "claude-code", + }, + }); + + assert.equal(result, true); +}); + +test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is registered", () => { + const result = shouldAutoPrepareWorkflowMcp({ + model: { provider: "openai", baseUrl: "https://api.openai.com" }, + modelRegistry: { + getProviderAuthMode: (provider: string) => provider === "claude-code" ? "externalCli" : "apiKey", + isProviderRequestReady: () => false, + }, + }); + + assert.equal(result, true); +}); + +test("shouldAutoPrepareWorkflowMcp stays disabled when neither transport nor provider readiness match", () => { + const result = shouldAutoPrepareWorkflowMcp({ + model: { provider: "openai", baseUrl: "https://api.openai.com" }, + modelRegistry: { + getProviderAuthMode: () => "apiKey", + isProviderRequestReady: () => false, + }, + }); + + assert.equal(result, false); +}); + +test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep fails", () => { + const notifications: Array<{ message: string; level: "info" | "warning" | "error" | "success" }> = []; + const result = prepareWorkflowMcpForProject( + { + model: { provider: "claude-code", baseUrl: "local://claude-code" }, + modelRegistry: { + getProviderAuthMode: () => "externalCli", + isProviderRequestReady: () => true, + }, + ui: { + notify: (message: string, level?: "info" | "warning" | "error" | "success") => { + notifications.push({ message, level: level ?? "info" }); + }, + }, + }, + "/", + ); + + assert.equal(result, null); + assert.equal(notifications.length, 1); + assert.equal(notifications[0].level, "warning"); + assert.match(notifications[0].message, /Please run \/gsd mcp init \./); +}); diff --git a/src/resources/extensions/gsd/tests/workflow-mcp.test.ts b/src/resources/extensions/gsd/tests/workflow-mcp.test.ts new file mode 100644 index 000000000..2b9687623 --- /dev/null +++ b/src/resources/extensions/gsd/tests/workflow-mcp.test.ts @@ -0,0 +1,695 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; +import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"; + +import { + buildWorkflowMcpServers, + detectWorkflowMcpLaunchConfig, + getWorkflowTransportSupportError, + getRequiredWorkflowToolsForAutoUnit, + getRequiredWorkflowToolsForGuidedUnit, + supportsStructuredQuestions, + usesWorkflowMcpTransport, +} from "../workflow-mcp.ts"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const gsdDir = join(__dirname, ".."); + +type ElicitPayload = { + message: string; + requestedSchema: { properties: Record; required?: string[] }; +}; + +function readSrc(file: string): string { + return readFileSync(join(gsdDir, file), "utf-8"); +} + +function extractElicitPayload(request: unknown): ElicitPayload { + const payload = (request as { params?: unknown }).params ?? request; + return payload as ElicitPayload; +} + +test("guided execute-task requires canonical task completion tool", () => { + assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), ["gsd_task_complete"]); +}); + +test("auto execute-task requires legacy completion alias until prompt contract is aligned", () => { + assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_complete_task"]); +}); + +test("detectWorkflowMcpLaunchConfig prefers explicit env override", () => { + const launch = detectWorkflowMcpLaunchConfig("/tmp/project", { + GSD_WORKFLOW_MCP_NAME: "workflow-tools", + GSD_WORKFLOW_MCP_COMMAND: "node", + GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["dist/cli.js"]), + GSD_WORKFLOW_MCP_ENV: JSON.stringify({ FOO: "bar" }), + GSD_WORKFLOW_MCP_CWD: "/tmp/project", + GSD_CLI_PATH: "/tmp/gsd", + }); + + assert.deepEqual(launch, { + name: "workflow-tools", + command: "node", + args: ["dist/cli.js"], + cwd: "/tmp/project", + env: launch?.env, + }); + assert.equal(launch?.env?.FOO, "bar"); + assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd"); + assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project"); + assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); +}); + +test("buildWorkflowMcpServers mirrors explicit launch config", () => { + const servers = buildWorkflowMcpServers("/tmp/project", { + GSD_WORKFLOW_MCP_COMMAND: "node", + GSD_WORKFLOW_MCP_ARGS: JSON.stringify(["dist/cli.js"]), + }); + + assert.deepEqual(servers, { + "gsd-workflow": { + command: "node", + args: ["dist/cli.js"], + env: servers?.["gsd-workflow"]?.env, + }, + }); + assert.equal((servers?.["gsd-workflow"]?.env as Record | undefined)?.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal((servers?.["gsd-workflow"]?.env as Record | undefined)?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project"); + assert.match((servers?.["gsd-workflow"]?.env as Record | undefined)?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match((servers?.["gsd-workflow"]?.env as Record | undefined)?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); +}); + +test("detectWorkflowMcpLaunchConfig resolves the bundled server from GSD_PROJECT_ROOT", () => { + const repoRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-root-")); + const worktreeRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-worktree-")); + const cliPath = join(repoRoot, "packages", "mcp-server", "dist", "cli.js"); + + mkdirSync(join(repoRoot, "packages", "mcp-server", "dist"), { recursive: true }); + writeFileSync(cliPath, "#!/usr/bin/env node\n", "utf-8"); + + const launch = detectWorkflowMcpLaunchConfig(worktreeRoot, { + GSD_PROJECT_ROOT: repoRoot, + }); + + assert.deepEqual(launch, { + name: "gsd-workflow", + command: process.execPath, + args: [cliPath], + cwd: repoRoot, + env: launch?.env, + }); + assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, repoRoot); + assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); +}); + +test("detectWorkflowMcpLaunchConfig resolves the bundled server from GSD_BIN_PATH ancestry", () => { + const repoRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-root-")); + const worktreeRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-worktree-")); + const cliPath = join(repoRoot, "packages", "mcp-server", "dist", "cli.js"); + const devCliPath = join(repoRoot, "scripts", "dev-cli.js"); + + mkdirSync(join(repoRoot, "packages", "mcp-server", "dist"), { recursive: true }); + mkdirSync(join(repoRoot, "scripts"), { recursive: true }); + writeFileSync(cliPath, "#!/usr/bin/env node\n", "utf-8"); + writeFileSync(devCliPath, "#!/usr/bin/env node\n", "utf-8"); + + const launch = detectWorkflowMcpLaunchConfig(worktreeRoot, { + GSD_BIN_PATH: devCliPath, + }); + + assert.deepEqual(launch, { + name: "gsd-workflow", + command: process.execPath, + args: [cliPath], + cwd: worktreeRoot, + env: launch?.env, + }); + assert.equal(launch?.env?.GSD_CLI_PATH, devCliPath); + assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1"); + assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, worktreeRoot); + assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); +}); + +test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the installed GSD package", () => { + const launch = detectWorkflowMcpLaunchConfig("/tmp/project", { + GSD_BIN_PATH: "/tmp/gsd-loader.js", + }); + + assert.equal(launch?.command, process.execPath); + assert.equal(launch?.cwd, "/tmp/project"); + assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd-loader.js"); + assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project"); + assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); + assert.equal(typeof launch?.args?.[0], "string"); + assert.match(launch?.args?.[0] ?? "", /packages[\/\\]mcp-server[\/\\](dist[\/\\]cli\.js|src[\/\\]cli\.ts)$/); + if ((launch?.args?.[0] ?? "").endsWith(".ts")) { + assert.match(launch?.env?.NODE_OPTIONS ?? "", /--experimental-strip-types/); + assert.match(launch?.env?.NODE_OPTIONS ?? "", /resolve-ts\.mjs/); + } +}); + +test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the package without env hints", () => { + const launch = detectWorkflowMcpLaunchConfig("/tmp/project", {}); + + assert.equal(launch?.command, process.execPath); + assert.equal(launch?.cwd, "/tmp/project"); + assert.equal(launch?.env?.GSD_CLI_PATH, undefined); + assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project"); + assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/); + assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/); + assert.equal(typeof launch?.args?.[0], "string"); + assert.match(launch?.args?.[0] ?? "", /packages[\/\\]mcp-server[\/\\](dist[\/\\]cli\.js|src[\/\\]cli\.ts)$/); + if ((launch?.args?.[0] ?? "").endsWith(".ts")) { + assert.match(launch?.env?.NODE_OPTIONS ?? "", /--experimental-strip-types/); + assert.match(launch?.env?.NODE_OPTIONS ?? "", /resolve-ts\.mjs/); + } +}); + +test("workflow MCP launch config reaches mutation tools over stdio", async () => { + const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-transport-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + + const launch = detectWorkflowMcpLaunchConfig(projectRoot, {}); + assert.ok(launch, "expected a workflow MCP launch config"); + assert.match( + launch.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", + /(dist[\/\\]resources[\/\\]extensions[\/\\]gsd[\/\\]tools[\/\\]workflow-tool-executors\.js|src[\/\\]resources[\/\\]extensions[\/\\]gsd[\/\\]tools[\/\\]workflow-tool-executors\.(js|ts))$/, + ); + assert.match( + launch.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", + /(dist[\/\\]resources[\/\\]extensions[\/\\]gsd[\/\\]bootstrap[\/\\]write-gate\.js|src[\/\\]resources[\/\\]extensions[\/\\]gsd[\/\\]bootstrap[\/\\]write-gate\.(js|ts))$/, + ); + if ((launch.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "").endsWith(".ts")) { + assert.match(launch.env?.NODE_OPTIONS ?? "", /--experimental-strip-types/); + assert.match(launch.env?.NODE_OPTIONS ?? "", /resolve-ts\.mjs/); + } + + const client = new Client( + { name: "workflow-mcp-transport-test", version: "1.0.0" }, + { capabilities: { elicitation: {} } }, + ); + client.setRequestHandler(ElicitRequestSchema, async (request) => { + const elicitation = extractElicitPayload(request as unknown); + + assert.match(elicitation.message, /Please answer the following question/); + assert.ok(elicitation.requestedSchema.properties.transport_mode); + assert.ok(elicitation.requestedSchema.properties["transport_mode__note"]); + assert.ok(elicitation.requestedSchema.required?.includes("transport_mode")); + + return { + action: "accept", + content: { + transport_mode: "None of the above", + transport_mode__note: "Need Windows-safe MCP elicitation.", + }, + }; + }); + const transport = new StdioClientTransport({ + command: launch.command, + args: launch.args, + env: { ...process.env, ...launch.env } as Record, + cwd: launch.cwd, + stderr: "pipe", + }); + + try { + await client.connect(transport, { timeout: 30_000 }); + + const tools = await client.listTools(undefined, { timeout: 30_000 }); + assert.ok( + (tools.tools ?? []).some((tool) => tool.name === "gsd_plan_slice"), + "expected workflow MCP surface to expose gsd_plan_slice", + ); + assert.ok( + (tools.tools ?? []).some((tool) => tool.name === "ask_user_questions"), + "expected workflow MCP surface to expose ask_user_questions", + ); + + const askResult = await client.callTool( + { + name: "ask_user_questions", + arguments: { + questions: [ + { + id: "transport_mode", + header: "Transport", + question: "How should the workflow prompt be delivered?", + options: [ + { label: "Local UI", description: "Use the host tool UI." }, + { label: "Remote UI", description: "Use a remote response channel." }, + ], + }, + ], + }, + }, + undefined, + { timeout: 30_000 }, + ); + assert.equal(askResult.isError, undefined); + assert.equal( + ((askResult.content as Array<{ text?: string }>)?.[0])?.text ?? "", + JSON.stringify({ + answers: { + transport_mode: { + answers: ["None of the above", "user_note: Need Windows-safe MCP elicitation."], + }, + }, + }), + ); + + const milestoneResult = await client.callTool( + { + name: "gsd_plan_milestone", + arguments: { + projectDir: projectRoot, + milestoneId: "M001", + title: "Transport planning", + vision: "Verify stdio workflow MCP uses the executor bridge.", + slices: [ + { + sliceId: "S01", + title: "Bridge path", + risk: "low", + depends: [], + demo: "Milestone planning succeeds over stdio MCP.", + goal: "Prove the executor bridge works in the spawned server.", + successCriteria: "gsd_plan_slice can write plan artifacts.", + proofLevel: "integration", + integrationClosure: "Stdio MCP client reaches the workflow executor bridge.", + observabilityImpact: "Regression test covers the spawned-server path.", + }, + ], + }, + }, + undefined, + { timeout: 30_000 }, + ); + assert.equal(milestoneResult.isError, undefined); + assert.match( + ((milestoneResult.content as Array<{ text?: string }>)?.[0])?.text ?? "", + /Planned milestone M001/, + ); + + const sliceResult = await client.callTool( + { + name: "gsd_plan_slice", + arguments: { + projectDir: projectRoot, + milestoneId: "M001", + sliceId: "S01", + goal: "Persist slice planning over the spawned MCP transport.", + tasks: [ + { + taskId: "T01", + title: "Connect the bridge", + description: "Ensure the workflow executor bridge resolves in the child process.", + estimate: "10m", + files: ["src/resources/extensions/gsd/workflow-mcp.ts"], + verify: "node --test", + inputs: ["M001-ROADMAP.md"], + expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"], + }, + ], + }, + }, + undefined, + { timeout: 30_000 }, + ); + assert.equal(sliceResult.isError, undefined); + assert.match( + ((sliceResult.content as Array<{ text?: string }>)?.[0])?.text ?? "", + /Planned slice S01/, + ); + assert.ok( + existsSync(join(projectRoot, ".gsd", "milestones", "M001", "slices", "S01", "S01-PLAN.md")), + "expected slice plan artifact to be written through stdio MCP", + ); + assert.ok( + existsSync( + join(projectRoot, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-PLAN.md"), + ), + "expected task plan artifact to be written through stdio MCP", + ); + } finally { + await client.close().catch(() => {}); + rmSync(projectRoot, { recursive: true, force: true }); + } +}); + +test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async () => { + const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-elicit-")); + mkdirSync(join(projectRoot, ".gsd"), { recursive: true }); + + const launch = detectWorkflowMcpLaunchConfig(projectRoot, {}); + assert.ok(launch, "expected a workflow MCP launch config"); + + const client = new Client( + { name: "workflow-mcp-elicit-test", version: "1.0.0" }, + { capabilities: { elicitation: {} } }, + ); + let requestSeen: { + message: string; + requestedSchema: { properties: Record; required?: string[] }; + } | null = null; + + client.setRequestHandler(ElicitRequestSchema, async (request) => { + const params = extractElicitPayload(request as unknown); + + requestSeen = params; + + return { + action: "accept", + content: { + deployment: "None of the above", + deployment__note: "Need hybrid deployment.", + }, + }; + }); + + const transport = new StdioClientTransport({ + command: launch.command, + args: launch.args, + env: { ...process.env, ...launch.env } as Record, + cwd: launch.cwd, + stderr: "pipe", + }); + + try { + await client.connect(transport, { timeout: 30_000 }); + + const result = await client.callTool( + { + name: "ask_user_questions", + arguments: { + questions: [ + { + id: "deployment", + header: "Deploy", + question: "Where will this run?", + options: [ + { label: "Cloud", description: "Managed hosting." }, + { label: "On-prem", description: "Runs in customer infrastructure." }, + ], + }, + ], + }, + }, + undefined, + { timeout: 30_000 }, + ); + + assert.ok(requestSeen, "expected stdio transport to forward an elicitation request"); + const seen = requestSeen as ElicitPayload; + assert.match(seen.message, /Please answer the following question/); + assert.ok(seen.requestedSchema.properties.deployment); + assert.ok(seen.requestedSchema.properties.deployment__note); + assert.ok(seen.requestedSchema.required?.includes("deployment")); + + const content = (result as { content: Array<{ type: string; text?: string }> }).content; + const text = content.find((item: { type: string; text?: string }) => item.type === "text"); + assert.ok(text && "text" in text); + assert.equal( + text.text, + JSON.stringify({ + answers: { + deployment: { + answers: ["None of the above", "user_note: Need hybrid deployment."], + }, + }, + }), + ); + } finally { + await client.close(); + } +}); + +test("usesWorkflowMcpTransport matches local externalCli providers", () => { + assert.equal(usesWorkflowMcpTransport("externalCli", "local://claude-code"), true); + assert.equal(usesWorkflowMcpTransport("externalCli", "https://api.example.com"), false); + assert.equal(usesWorkflowMcpTransport("oauth", "local://custom"), false); +}); + +test("supportsStructuredQuestions disables structured ask flow on workflow MCP transports", () => { + assert.equal( + supportsStructuredQuestions(["ask_user_questions"], { + authMode: "externalCli", + baseUrl: "local://claude-code", + }), + false, + ); + assert.equal( + supportsStructuredQuestions(["ask_user_questions"], { + authMode: "oauth", + baseUrl: "https://api.anthropic.com", + }), + true, + ); + assert.equal( + supportsStructuredQuestions([], { + authMode: "oauth", + baseUrl: "https://api.anthropic.com", + }), + false, + ); +}); + +test("transport compatibility passes when required tools fit current MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_task_complete"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "guided flow", + unitType: "execute-task", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility discovers the bundled MCP server without env overrides", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_task_complete"], + { + projectRoot: "/tmp/project", + env: {}, + surface: "auto-mode", + unitType: "execute-task", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows auto execute-task over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_complete_task"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "execute-task", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility ignores API-backed providers", () => { + const error = getWorkflowTransportSupportError( + "openai-codex", + ["gsd_plan_slice"], + { + projectRoot: "/tmp/project", + env: {}, + surface: "auto-mode", + unitType: "plan-slice", + authMode: "oauth", + baseUrl: "https://api.openai.com", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows plan-slice over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_plan_slice"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "plan-slice", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows complete-slice over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_complete_slice"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "complete-slice", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows reassess-roadmap over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_milestone_status", "gsd_reassess_roadmap"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "reassess-roadmap", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows gate-evaluate over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_save_gate_result"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "gate-evaluate", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows validate-milestone over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_milestone_status", "gsd_validate_milestone"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "validate-milestone", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows complete-milestone over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_milestone_status", "gsd_complete_milestone"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "complete-milestone", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility now allows replan-slice over workflow MCP surface", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["gsd_replan_slice"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "replan-slice", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.equal(error, null); +}); + +test("transport compatibility still blocks units whose MCP tools are not exposed", () => { + const error = getWorkflowTransportSupportError( + "claude-code", + ["secure_env_collect"], + { + projectRoot: "/tmp/project", + env: { GSD_WORKFLOW_MCP_COMMAND: "node" }, + surface: "auto-mode", + unitType: "guided-discussion", + authMode: "externalCli", + baseUrl: "local://claude-code", + }, + ); + + assert.match(error ?? "", /requires secure_env_collect/); + assert.match(error ?? "", /currently exposes only/); +}); + +test("guided-flow source enforces workflow compatibility preflight", () => { + const src = readSrc("guided-flow.ts"); + assert.match(src, /getRequiredWorkflowToolsForGuidedUnit/); + assert.match(src, /getWorkflowTransportSupportError/); +}); + +test("auto direct dispatch source enforces workflow compatibility preflight", () => { + const src = readSrc("auto-direct-dispatch.ts"); + assert.match(src, /getRequiredWorkflowToolsForAutoUnit/); + assert.match(src, /getWorkflowTransportSupportError/); +}); + +test("auto phases source enforces workflow compatibility preflight", () => { + const src = readSrc(join("auto", "phases.ts")); + assert.match(src, /getRequiredWorkflowToolsForAutoUnit/); + assert.match(src, /getWorkflowTransportSupportError/); + assert.match(src, /workflow-capability/); +}); + +test("workflow transport error guidance includes /gsd mcp init hint", () => { + const src = readSrc("workflow-mcp.ts"); + assert.match(src, /Please run \/gsd mcp init \./); +}); diff --git a/src/resources/extensions/gsd/tests/workflow-projections.test.ts b/src/resources/extensions/gsd/tests/workflow-projections.test.ts index cf21052e2..b9379ede8 100644 --- a/src/resources/extensions/gsd/tests/workflow-projections.test.ts +++ b/src/resources/extensions/gsd/tests/workflow-projections.test.ts @@ -86,10 +86,12 @@ test('workflow-projections: renderPlanContent falls back to TBD when goal and fu assert.ok(content.includes('**Goal:** TBD')); }); -test('workflow-projections: renderPlanContent falls back to full_summary_md when goal is empty', () => { +test('workflow-projections: renderPlanContent falls back to TBD when goal is empty (full_summary_md ignored #2945)', () => { const slice = makeSlice({ goal: '', full_summary_md: 'Fallback goal text' }); const content = renderPlanContent(slice, []); - assert.ok(content.includes('**Goal:** Fallback goal text')); + // #2945: full_summary_md is no longer used as a fallback — it contains + // multi-line rendered markdown that corrupts single-line fields. + assert.ok(content.includes('**Goal:** TBD'), `expected TBD fallback, got: ${content}`); }); test('workflow-projections: renderPlanContent includes ## Tasks section', () => { diff --git a/src/resources/extensions/gsd/tests/workflow-reconcile.test.ts b/src/resources/extensions/gsd/tests/workflow-reconcile.test.ts new file mode 100644 index 000000000..e1103262c --- /dev/null +++ b/src/resources/extensions/gsd/tests/workflow-reconcile.test.ts @@ -0,0 +1,91 @@ +import test, { afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { appendEvent, readEvents } from "../workflow-events.ts"; +import { listConflicts, reconcileWorktreeLogs, resolveConflict } from "../workflow-reconcile.ts"; +import { closeDatabase } from "../gsd-db.ts"; + +const tmpDirs: string[] = []; + +function makeTmpRepo(): { main: string; worktree: string } { + const root = mkdtempSync(join(tmpdir(), "workflow-reconcile-")); + const main = join(root, "main"); + const worktree = join(root, "worktree"); + mkdirSync(main, { recursive: true }); + mkdirSync(worktree, { recursive: true }); + tmpDirs.push(root); + return { main, worktree }; +} + +afterEach(() => { + closeDatabase(); + for (const dir of tmpDirs) { + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Best-effort cleanup on platforms that keep files open briefly. + } + } + tmpDirs.length = 0; +}); + +test("resolveConflict(pick=main) rewrites the worktree log durably", () => { + const { main, worktree } = makeTmpRepo(); + + appendEvent(main, { + cmd: "plan_milestone", + params: { milestoneId: "M001", title: "Base Milestone" }, + ts: "2026-01-01T00:00:00.000Z", + actor: "agent", + }); + appendEvent(worktree, { + cmd: "plan_milestone", + params: { milestoneId: "M001", title: "Base Milestone" }, + ts: "2026-01-01T00:00:00.000Z", + actor: "agent", + }); + + appendEvent(main, { + cmd: "plan_milestone", + params: { milestoneId: "M001", title: "Main Choice" }, + ts: "2026-01-01T00:01:00.000Z", + actor: "agent", + }); + + appendEvent(worktree, { + cmd: "plan_milestone", + params: { milestoneId: "M001", title: "Worktree Choice" }, + ts: "2026-01-01T00:01:00.000Z", + actor: "agent", + }); + + const initial = reconcileWorktreeLogs(main, worktree); + assert.equal(initial.conflicts.length, 1, "expected one conflict before resolution"); + assert.ok(listConflicts(main).length === 1, "CONFLICTS.md should exist after detection"); + + resolveConflict(main, worktree, "milestone:M001", "main"); + + assert.equal(listConflicts(main).length, 0, "conflict file should be cleared after resolving main"); + const conflictsPath = join(main, ".gsd", "CONFLICTS.md"); + assert.equal( + existsSync(conflictsPath), + false, + "CONFLICTS.md should be removed after the last conflict is resolved", + ); + + const wtEvents = readEvents(join(worktree, ".gsd", "event-log.jsonl")); + assert.ok( + wtEvents.some((e) => e.cmd === "plan_milestone" && e.params.title === "Main Choice"), + "worktree log should be rewritten to the main-side resolution", + ); + assert.ok( + !wtEvents.some((e) => e.cmd === "plan_milestone" && e.params.title === "Worktree Choice"), + "worktree log should no longer contain the discarded conflict event", + ); + + const second = reconcileWorktreeLogs(main, worktree); + assert.equal(second.conflicts.length, 0, "reconcile should stay clean after choosing main"); +}); diff --git a/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts b/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts new file mode 100644 index 000000000..327f51759 --- /dev/null +++ b/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts @@ -0,0 +1,647 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { randomUUID } from "node:crypto"; + +import { + openDatabase, + closeDatabase, + _getAdapter, + insertGateRow, +} from "../gsd-db.ts"; +import { + executeCompleteMilestone, + executePlanMilestone, + executePlanSlice, + executeReplanSlice, + executeReassessRoadmap, + executeSaveGateResult, + executeSummarySave, + executeTaskComplete, + executeMilestoneStatus, + executeSliceComplete, + executeValidateMilestone, +} from "../tools/workflow-tool-executors.ts"; + +function makeTmpBase(): string { + const base = join(tmpdir(), `gsd-workflow-executors-${randomUUID()}`); + mkdirSync(join(base, ".gsd"), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + try { rmSync(base, { recursive: true, force: true }); } catch { /* swallow */ } +} + +function openTestDb(base: string): void { + openDatabase(join(base, ".gsd", "gsd.db")); +} + +async function inProjectDir(dir: string, fn: () => Promise): Promise { + const originalCwd = process.cwd(); + try { + process.chdir(dir); + return await fn(); + } finally { + process.chdir(originalCwd); + } +} + +function seedMilestone(milestoneId: string, title: string, status = "active"): void { + const db = _getAdapter(); + if (!db) throw new Error("DB not open"); + db.prepare( + "INSERT OR REPLACE INTO milestones (id, title, status, created_at) VALUES (?, ?, ?, ?)", + ).run(milestoneId, title, status, new Date().toISOString()); +} + +function seedSlice(milestoneId: string, sliceId: string, status: string): void { + const db = _getAdapter(); + if (!db) throw new Error("DB not open"); + db.prepare( + "INSERT OR REPLACE INTO slices (milestone_id, id, title, status, created_at) VALUES (?, ?, ?, ?, ?)", + ).run(milestoneId, sliceId, `Slice ${sliceId}`, status, new Date().toISOString()); +} + +function writeRoadmap(base: string, milestoneId: string, sliceIds: string[]): void { + const milestoneDir = join(base, ".gsd", "milestones", milestoneId); + mkdirSync(milestoneDir, { recursive: true }); + const lines = [ + `# ${milestoneId}: Workflow MCP planning`, + "", + "## Slices", + "", + ...sliceIds.map((sliceId) => `- [ ] **${sliceId}: Slice ${sliceId}** \`risk:medium\` \`depends:[]\`\n - After this: demo`), + "", + ]; + writeFileSync(join(milestoneDir, `${milestoneId}-ROADMAP.md`), lines.join("\n")); +} + +test("executeSummarySave persists artifact and returns computed path", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + const result = await inProjectDir(base, () => executeSummarySave({ + milestone_id: "M001", + slice_id: "S01", + artifact_type: "SUMMARY", + content: "# Summary\n\ncontent", + }, base)); + + assert.equal(result.details.operation, "save_summary"); + assert.equal(result.details.path, "milestones/M001/slices/S01/S01-SUMMARY.md"); + + const filePath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"); + assert.ok(existsSync(filePath), "summary artifact should be written to disk"); + assert.match(readFileSync(filePath, "utf-8"), /# Summary/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeTaskComplete coerces string verificationEvidence entries", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + const planDir = join(base, ".gsd", "milestones", "M001", "slices", "S01"); + mkdirSync(planDir, { recursive: true }); + writeFileSync(join(planDir, "S01-PLAN.md"), "# S01\n\n- [ ] **T01: Demo** `est:5m`\n"); + + const result = await inProjectDir(base, () => executeTaskComplete({ + milestoneId: "M001", + sliceId: "S01", + taskId: "T01", + oneLiner: "Completed task", + narrative: "Did the work", + verification: "npm test", + verificationEvidence: ["npm test"], + }, base)); + + assert.equal(result.details.operation, "complete_task"); + assert.equal(result.details.taskId, "T01"); + + const db = _getAdapter(); + assert.ok(db, "DB should be open"); + const rows = db!.prepare( + "SELECT command, exit_code, verdict, duration_ms FROM verification_evidence WHERE milestone_id = ? AND slice_id = ? AND task_id = ?", + ).all("M001", "S01", "T01") as Array>; + + assert.equal(rows.length, 1, "one coerced verification evidence row should be inserted"); + assert.equal(rows[0]["command"], "npm test"); + assert.equal(rows[0]["exit_code"], -1); + assert.match(String(rows[0]["verdict"]), /coerced from string/); + + const summaryPath = String(result.details.summaryPath); + assert.ok(existsSync(summaryPath), "task summary should be written to disk"); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeMilestoneStatus returns milestone metadata and slice counts", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M001", "Milestone One"); + seedSlice("M001", "S01", "active"); + const db = _getAdapter(); + db!.prepare( + "INSERT OR REPLACE INTO tasks (milestone_id, slice_id, id, title, status) VALUES (?, ?, ?, ?, ?)", + ).run("M001", "S01", "T01", "Task T01", "pending"); + + const result = await inProjectDir(base, () => executeMilestoneStatus({ milestoneId: "M001" }, base)); + const parsed = JSON.parse(result.content[0].text); + + assert.equal(parsed.milestoneId, "M001"); + assert.equal(parsed.title, "Milestone One"); + assert.equal(parsed.sliceCount, 1); + assert.equal(parsed.slices[0].id, "S01"); + assert.equal(parsed.slices[0].taskCounts.pending, 1); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executePlanMilestone writes roadmap state and rendered roadmap path", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + + const result = await inProjectDir(base, () => executePlanMilestone({ + milestoneId: "M001", + title: "Workflow MCP planning", + vision: "Plan milestone over shared executors.", + slices: [ + { + sliceId: "S01", + title: "Bridge planning", + risk: "medium", + depends: [], + demo: "Milestone plan persists through MCP.", + goal: "Persist roadmap state.", + successCriteria: "ROADMAP.md renders from DB.", + proofLevel: "integration", + integrationClosure: "Prompts and MCP call the same handler.", + observabilityImpact: "Executor tests cover output paths.", + }, + ], + }, base)); + + assert.equal(result.details.operation, "plan_milestone"); + assert.equal(result.details.milestoneId, "M001"); + const roadmapPath = String(result.details.roadmapPath); + assert.ok(existsSync(roadmapPath), "roadmap should be rendered to disk"); + assert.match(readFileSync(roadmapPath, "utf-8"), /Workflow MCP planning/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executePlanSlice writes task planning state and rendered plan artifacts", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + await inProjectDir(base, () => executePlanMilestone({ + milestoneId: "M001", + title: "Workflow MCP planning", + vision: "Plan milestone over shared executors.", + slices: [ + { + sliceId: "S01", + title: "Bridge planning", + risk: "medium", + depends: [], + demo: "Milestone plan persists through MCP.", + goal: "Persist roadmap state.", + successCriteria: "ROADMAP.md renders from DB.", + proofLevel: "integration", + integrationClosure: "Prompts and MCP call the same handler.", + observabilityImpact: "Executor tests cover output paths.", + }, + ], + }, base)); + + const result = await inProjectDir(base, () => executePlanSlice({ + milestoneId: "M001", + sliceId: "S01", + goal: "Persist slice plan over MCP.", + tasks: [ + { + taskId: "T01", + title: "Add planning bridge", + description: "Implement the shared executor path.", + estimate: "15m", + files: ["src/resources/extensions/gsd/tools/workflow-tool-executors.ts"], + verify: "node --test", + inputs: ["ROADMAP.md"], + expectedOutput: ["S01-PLAN.md", "T01-PLAN.md"], + }, + ], + }, base)); + + assert.equal(result.details.operation, "plan_slice"); + assert.equal(result.details.sliceId, "S01"); + const planPath = String(result.details.planPath); + assert.ok(existsSync(planPath), "slice plan should be rendered to disk"); + assert.match(readFileSync(planPath, "utf-8"), /Persist slice plan over MCP/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executePlanSlice marks validation failures with isError", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + + const result = await inProjectDir(base, () => executePlanSlice({ + milestoneId: "M001", + sliceId: "S01", + goal: "Trigger validation failure for empty tasks.", + tasks: [], + }, base)); + + assert.equal(result.isError, true); + assert.equal(result.details.operation, "plan_slice"); + assert.match(String(result.details.error), /validation failed: tasks must be a non-empty array/); + assert.match(result.content[0].text, /Error planning slice:/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeSliceComplete coerces string enrichment entries and writes summary/UAT artifacts", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M001", "Milestone One"); + seedSlice("M001", "S01", "pending"); + writeRoadmap(base, "M001", ["S01"]); + const db = _getAdapter(); + db!.prepare( + "INSERT OR REPLACE INTO tasks (milestone_id, slice_id, id, title, status) VALUES (?, ?, ?, ?, ?)", + ).run("M001", "S01", "T01", "Task T01", "complete"); + + const rawParams = { + milestoneId: "M001", + sliceId: "S01", + sliceTitle: "Slice S01", + oneLiner: "Completed slice", + narrative: "Implemented the slice", + verification: "node --test", + uatContent: "## UAT\n\nPASS", + provides: "shared executor path", + requirementsAdvanced: ["R001 - added slice completion support"], + filesModified: ["src/file.ts - updated logic"], + requires: ["S00 - upstream context"], + } as unknown as Parameters[0]; + + const result = await inProjectDir(base, () => executeSliceComplete(rawParams, base)); + + assert.equal(result.details.operation, "complete_slice"); + const summaryPath = String(result.details.summaryPath); + const uatPath = String(result.details.uatPath); + assert.ok(existsSync(summaryPath), "slice summary should be written to disk"); + assert.ok(existsSync(uatPath), "slice UAT should be written to disk"); + assert.match(readFileSync(summaryPath, "utf-8"), /shared executor path/); + assert.match(readFileSync(summaryPath, "utf-8"), /R001/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeValidateMilestone persists validation artifact and gate records", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M002", "Milestone Two"); + seedSlice("M002", "S02", "complete"); + + const result = await inProjectDir(base, () => executeValidateMilestone({ + milestoneId: "M002", + verdict: "pass", + remediationRound: 0, + successCriteriaChecklist: "- [x] Works", + sliceDeliveryAudit: "| Slice | Result |\n| --- | --- |\n| S02 | pass |", + crossSliceIntegration: "No cross-slice issues.", + requirementCoverage: "All requirements covered.", + verdictRationale: "Everything passed.", + }, base)); + + assert.equal(result.details.operation, "validate_milestone"); + const validationPath = String(result.details.validationPath); + assert.ok(existsSync(validationPath), "validation file should be written to disk"); + + const db = _getAdapter(); + const gates = db!.prepare( + "SELECT gate_id, verdict FROM quality_gates WHERE milestone_id = ? ORDER BY gate_id", + ).all("M002") as Array>; + assert.ok(gates.length > 0, "validation should seed milestone quality gates"); + assert.equal(gates[0]["verdict"], "pass"); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeCompleteMilestone sanitizes raw params and writes milestone summary", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M003", "Milestone Three"); + seedSlice("M003", "S03", "complete"); + writeRoadmap(base, "M003", ["S03"]); + const db = _getAdapter(); + db!.prepare( + "INSERT OR REPLACE INTO tasks (milestone_id, slice_id, id, title, status) VALUES (?, ?, ?, ?, ?)", + ).run("M003", "S03", "T03", "Task T03", "complete"); + + const rawParams = { + milestoneId: "M003", + title: "Milestone Three", + oneLiner: "Completed milestone", + narrative: "Everything shipped.", + verificationPassed: "true", + keyDecisions: ["shared executor path"], + lessonsLearned: ["MCP transport stays generic"], + } as unknown as Parameters[0]; + + const result = await inProjectDir(base, () => executeCompleteMilestone(rawParams, base)); + + assert.equal(result.details.operation, "complete_milestone"); + const summaryPath = String(result.details.summaryPath); + assert.ok(existsSync(summaryPath), "milestone summary should be written to disk"); + assert.match(readFileSync(summaryPath, "utf-8"), /shared executor path/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeReassessRoadmap writes assessment and updates roadmap projection", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + await inProjectDir(base, () => executePlanMilestone({ + milestoneId: "M004", + title: "Milestone Four", + vision: "Exercise roadmap reassessment.", + slices: [ + { + sliceId: "S04", + title: "Completed slice", + risk: "medium", + depends: [], + demo: "Completed slice works", + goal: "Complete the first slice.", + successCriteria: "S04 is complete.", + proofLevel: "integration", + integrationClosure: "Baseline flow is wired.", + observabilityImpact: "Executor test covers reassessment.", + }, + { + sliceId: "S05", + title: "Follow-up slice", + risk: "medium", + depends: ["S04"], + demo: "Follow-up slice is adjusted", + goal: "Handle the follow-up work.", + successCriteria: "Roadmap gets updated.", + proofLevel: "integration", + integrationClosure: "Downstream work stays aligned.", + observabilityImpact: "Assessment artifact is rendered.", + }, + ], + }, base)); + await inProjectDir(base, () => executePlanSlice({ + milestoneId: "M004", + sliceId: "S04", + goal: "Complete the first slice.", + tasks: [ + { + taskId: "T04", + title: "Finish slice", + description: "Close the completed slice.", + estimate: "5m", + files: ["src/file.ts"], + verify: "node --test", + inputs: ["M004-ROADMAP.md"], + expectedOutput: ["S04-SUMMARY.md", "S04-UAT.md"], + }, + ], + }, base)); + await inProjectDir(base, () => executeTaskComplete({ + milestoneId: "M004", + sliceId: "S04", + taskId: "T04", + oneLiner: "Completed task", + narrative: "Task finished.", + verification: "node --test", + }, base)); + await inProjectDir(base, () => executeSliceComplete({ + milestoneId: "M004", + sliceId: "S04", + sliceTitle: "Completed slice", + oneLiner: "Completed slice", + narrative: "Slice finished.", + verification: "node --test", + uatContent: "## UAT\n\nPASS", + }, base)); + + const result = await inProjectDir(base, () => executeReassessRoadmap({ + milestoneId: "M004", + completedSliceId: "S04", + verdict: "roadmap-adjusted", + assessment: "Added a remediation slice.", + sliceChanges: { + modified: [ + { + sliceId: "S05", + title: "Adjusted follow-up slice", + risk: "high", + depends: ["S04"], + demo: "Adjusted follow-up demo", + }, + ], + added: [ + { + sliceId: "S06", + title: "Remediation slice", + risk: "medium", + depends: ["S05"], + demo: "Remediation slice demo", + }, + ], + removed: [], + }, + }, base)); + + assert.equal(result.details.operation, "reassess_roadmap"); + const assessmentPath = String(result.details.assessmentPath); + const roadmapPath = String(result.details.roadmapPath); + assert.ok(existsSync(assessmentPath), "assessment file should be written"); + assert.ok(existsSync(roadmapPath), "roadmap should be re-rendered"); + assert.match(readFileSync(roadmapPath, "utf-8"), /S06/); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeSaveGateResult validates inputs and persists verdicts", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + seedMilestone("M005", "Milestone Five"); + seedSlice("M005", "S05", "pending"); + insertGateRow({ + milestoneId: "M005", + sliceId: "S05", + gateId: "Q3", + scope: "slice", + }); + + const result = await inProjectDir(base, () => executeSaveGateResult({ + milestoneId: "M005", + sliceId: "S05", + gateId: "Q3", + verdict: "pass", + rationale: "Looks good.", + findings: "No issues found.", + }, base)); + + assert.equal(result.details.operation, "save_gate_result"); + const db = _getAdapter(); + const row = db!.prepare( + "SELECT status, verdict, rationale FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ? AND task_id = ''", + ).get("M005", "S05", "Q3") as Record | undefined; + assert.equal(row?.status, "complete"); + assert.equal(row?.verdict, "pass"); + assert.equal(row?.rationale, "Looks good."); + } finally { + closeDatabase(); + cleanup(base); + } +}); + +test("executeReplanSlice rewrites pending tasks and renders replan artifacts", async () => { + const base = makeTmpBase(); + try { + openTestDb(base); + await inProjectDir(base, () => executePlanMilestone({ + milestoneId: "M006", + title: "Milestone Six", + vision: "Exercise slice replanning.", + slices: [ + { + sliceId: "S06", + title: "Replan slice", + risk: "medium", + depends: [], + demo: "Slice can be replanned after a blocker task completes.", + goal: "Prepare replan state.", + successCriteria: "PLAN and REPLAN artifacts update.", + proofLevel: "integration", + integrationClosure: "Replan shares the workflow executor path.", + observabilityImpact: "Executor test covers replan output files.", + }, + ], + }, base)); + await inProjectDir(base, () => executePlanSlice({ + milestoneId: "M006", + sliceId: "S06", + goal: "Plan a slice that will be replanned.", + tasks: [ + { + taskId: "T06", + title: "Blocker task", + description: "Finish the blocker-discovery task.", + estimate: "5m", + files: ["src/blocker.ts"], + verify: "node --test", + inputs: ["M006-ROADMAP.md"], + expectedOutput: ["T06-SUMMARY.md"], + }, + { + taskId: "T07", + title: "Pending task", + description: "Original follow-up task.", + estimate: "10m", + files: ["src/pending.ts"], + verify: "node --test", + inputs: ["S06-PLAN.md"], + expectedOutput: ["Updated plan"], + }, + ], + }, base)); + await inProjectDir(base, () => executeTaskComplete({ + milestoneId: "M006", + sliceId: "S06", + taskId: "T06", + oneLiner: "Completed blocker task", + narrative: "The blocker was identified and documented.", + verification: "node --test", + }, base)); + + const result = await inProjectDir(base, () => executeReplanSlice({ + milestoneId: "M006", + sliceId: "S06", + blockerTaskId: "T06", + blockerDescription: "Original approach no longer works.", + whatChanged: "Adjusted the remaining tasks and added a remediation task.", + updatedTasks: [ + { + taskId: "T07", + title: "Pending task (updated)", + description: "Updated follow-up task after replanning.", + estimate: "15m", + files: ["src/pending.ts", "src/replanned.ts"], + verify: "node --test", + inputs: ["S06-PLAN.md"], + expectedOutput: ["Updated plan"], + }, + { + taskId: "T08", + title: "Remediation task", + description: "New task introduced by the replan.", + estimate: "20m", + files: ["src/remediation.ts"], + verify: "node --test", + inputs: ["S06-REPLAN.md"], + expectedOutput: ["Remediation patch"], + }, + ], + removedTaskIds: [], + }, base)); + + assert.equal(result.details.operation, "replan_slice"); + const planPath = String(result.details.planPath); + const replanPath = String(result.details.replanPath); + assert.ok(existsSync(planPath), "replanned plan should exist on disk"); + assert.ok(existsSync(replanPath), "replan artifact should exist on disk"); + assert.match(readFileSync(planPath, "utf-8"), /T08/); + assert.match(readFileSync(replanPath, "utf-8"), /Adjusted the remaining tasks/); + + const db = _getAdapter(); + const updatedTask = db!.prepare( + "SELECT title FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?", + ).get("M006", "S06", "T07") as Record | undefined; + const insertedTask = db!.prepare( + "SELECT title FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?", + ).get("M006", "S06", "T08") as Record | undefined; + assert.equal(updatedTask?.title, "Pending task (updated)"); + assert.equal(insertedTask?.title, "Remediation task"); + } finally { + closeDatabase(); + cleanup(base); + } +}); diff --git a/src/resources/extensions/gsd/tests/worktree-db-respawn-truncation.test.ts b/src/resources/extensions/gsd/tests/worktree-db-respawn-truncation.test.ts new file mode 100644 index 000000000..009a0979d --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-db-respawn-truncation.test.ts @@ -0,0 +1,219 @@ +/** + * worktree-db-respawn-truncation.test.ts — Regression test for #2815. + * + * Verifies that syncProjectRootToWorktree does NOT delete a non-empty + * worktree gsd.db. On worker respawn, gsd-migrate populates the DB + * (~1.7MB) before the auto-loop calls syncProjectRootToWorktree. The + * sync step must preserve the freshly-migrated DB to avoid truncating + * it to 0 bytes and causing "no such table: slices" failures. + * + * Covers: + * - Non-empty worktree gsd.db preserved after sync (#2815) + * - Empty (0-byte) worktree gsd.db still deleted (#853 preserved) + * - WAL/SHM sidecar files cleaned up when empty DB is deleted + */ + +import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, statSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; + +import { syncProjectRootToWorktree } from '../auto-worktree.ts'; +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; + + +function createBase(name: string): string { + const base = mkdtempSync(join(tmpdir(), `gsd-wt-respawn-${name}-`)); + mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true }); + return base; +} + +function cleanup(base: string): void { + rmSync(base, { recursive: true, force: true }); +} + +describe('worktree-db-respawn-truncation (#2815)', async () => { + + // ─── 1. Non-empty worktree gsd.db preserved after sync ─────────────── + console.log('\n=== 1. non-empty worktree gsd.db preserved after sync (#2815) ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + // Set up milestone artifacts in main project root + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + + // Simulate a freshly-migrated worktree DB (non-empty, like after gsd-migrate) + // Real DBs are ~1.7MB; we use a smaller payload to prove the size check works + const fakeDbContent = Buffer.alloc(4096, 0x42); // 4KB non-empty DB + writeFileSync(join(wtBase, '.gsd', 'gsd.db'), fakeDbContent); + + const sizeBefore = statSync(join(wtBase, '.gsd', 'gsd.db')).size; + assert.ok(sizeBefore > 0, 'gsd.db is non-empty before sync'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + // The non-empty DB must survive the sync + assert.ok( + existsSync(join(wtBase, '.gsd', 'gsd.db')), + '#2815: non-empty gsd.db must not be deleted by sync', + ); + const sizeAfter = statSync(join(wtBase, '.gsd', 'gsd.db')).size; + assert.equal( + sizeAfter, + sizeBefore, + '#2815: gsd.db size must be unchanged after sync', + ); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } + + // ─── 2. Empty (0-byte) worktree gsd.db still deleted ───────────────── + console.log('\n=== 2. empty (0-byte) worktree gsd.db still deleted (#853) ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + + // Create an empty (0-byte) gsd.db — this is stale/corrupt and should be deleted + writeFileSync(join(wtBase, '.gsd', 'gsd.db'), ''); + assert.ok(existsSync(join(wtBase, '.gsd', 'gsd.db')), 'empty gsd.db exists before sync'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + assert.ok( + !existsSync(join(wtBase, '.gsd', 'gsd.db')), + '#853: empty gsd.db must still be deleted after sync', + ); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } + + // ─── 3. WAL/SHM sidecar files cleaned up when empty DB is deleted (#2478) ── + console.log('\n=== 3. orphaned WAL/SHM cleaned up alongside empty gsd.db (#2478) ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + + // Create an empty (0-byte) gsd.db plus orphaned WAL and SHM files — + // this is the exact state that causes Node 24 node:sqlite CPU spin (#2478). + const wtGsd = join(wtBase, '.gsd'); + writeFileSync(join(wtGsd, 'gsd.db'), ''); + writeFileSync(join(wtGsd, 'gsd.db-wal'), Buffer.alloc(605672, 0xAA)); + writeFileSync(join(wtGsd, 'gsd.db-shm'), Buffer.alloc(32768, 0xBB)); + + assert.ok(existsSync(join(wtGsd, 'gsd.db')), 'gsd.db exists before sync'); + assert.ok(existsSync(join(wtGsd, 'gsd.db-wal')), 'gsd.db-wal exists before sync'); + assert.ok(existsSync(join(wtGsd, 'gsd.db-shm')), 'gsd.db-shm exists before sync'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + assert.ok( + !existsSync(join(wtGsd, 'gsd.db')), + '#2478: empty gsd.db must be deleted', + ); + assert.ok( + !existsSync(join(wtGsd, 'gsd.db-wal')), + '#2478: orphaned gsd.db-wal must be deleted alongside gsd.db', + ); + assert.ok( + !existsSync(join(wtGsd, 'gsd.db-shm')), + '#2478: orphaned gsd.db-shm must be deleted alongside gsd.db', + ); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } + + // ─── 4. Orphaned WAL/SHM cleaned up even when gsd.db already missing (#2478) ── + console.log('\n=== 4. orphaned WAL/SHM cleaned up even without gsd.db (#2478) ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + + // Orphaned WAL/SHM with NO gsd.db at all — can happen from a previous + // partial cleanup. These must still be cleaned up. + const wtGsd = join(wtBase, '.gsd'); + writeFileSync(join(wtGsd, 'gsd.db-wal'), Buffer.alloc(1024, 0xAA)); + writeFileSync(join(wtGsd, 'gsd.db-shm'), Buffer.alloc(1024, 0xBB)); + + assert.ok(!existsSync(join(wtGsd, 'gsd.db')), 'gsd.db does not exist'); + assert.ok(existsSync(join(wtGsd, 'gsd.db-wal')), 'orphaned gsd.db-wal exists'); + assert.ok(existsSync(join(wtGsd, 'gsd.db-shm')), 'orphaned gsd.db-shm exists'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + assert.ok( + !existsSync(join(wtGsd, 'gsd.db-wal')), + '#2478: orphaned gsd.db-wal must be deleted even without main db file', + ); + assert.ok( + !existsSync(join(wtGsd, 'gsd.db-shm')), + '#2478: orphaned gsd.db-shm must be deleted even without main db file', + ); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } + + // ─── 5. Milestone artifacts still synced when DB is preserved ──────── + console.log('\n=== 5. milestone artifacts still synced even when DB preserved ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + mkdirSync(join(m001Dir, 'slices', 'S01'), { recursive: true }); + writeFileSync(join(m001Dir, 'slices', 'S01', 'S01-PLAN.md'), '# Plan'); + + // Non-empty DB in worktree + writeFileSync(join(wtBase, '.gsd', 'gsd.db'), 'populated-db-data'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + // Artifacts must still be synced + assert.ok( + existsSync(join(wtBase, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md')), + 'milestone artifacts synced even with preserved DB', + ); + assert.ok( + existsSync(join(wtBase, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md')), + 'slice artifacts synced even with preserved DB', + ); + // DB must still exist + assert.ok( + existsSync(join(wtBase, '.gsd', 'gsd.db')), + '#2815: DB preserved alongside artifact sync', + ); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } +}); diff --git a/src/resources/extensions/gsd/tests/worktree-expected-warnings.test.ts b/src/resources/extensions/gsd/tests/worktree-expected-warnings.test.ts new file mode 100644 index 000000000..60c2dc064 --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-expected-warnings.test.ts @@ -0,0 +1,38 @@ +/** + * worktree-expected-warnings.test.ts — #3665 + * + * Verify that auto-worktree.ts and worktree-manager.ts suppress expected + * ENOENT and EISDIR conditions instead of logging misleading warnings. + */ + +import { describe, test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const autoWorktreeFile = join(__dirname, "..", "auto-worktree.ts"); +const worktreeManagerFile = join(__dirname, "..", "worktree-manager.ts"); + +describe("worktree expected-condition warning suppression (#3665)", () => { + const autoSource = readFileSync(autoWorktreeFile, "utf-8"); + + test("auto-worktree.ts checks for ENOENT before logging unlink warning", () => { + assert.match(autoSource, /code\s*!==\s*["']ENOENT["']/); + }); + + test("auto-worktree.ts checks for EISDIR before logging unlink warning", () => { + assert.match(autoSource, /code\s*!==\s*["']EISDIR["']/); + }); + + test("auto-worktree.ts references issue #3597", () => { + assert.match(autoSource, /#3597/); + }); + + const managerSource = readFileSync(worktreeManagerFile, "utf-8"); + + test("worktree-manager.ts checks isDirectory() before reading .git file", () => { + assert.match(managerSource, /lstatSync\(gitPath\)\.isDirectory\(\)/); + }); +}); diff --git a/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts b/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts index 6c2ed26f7..fc8e828e1 100644 --- a/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-health-dispatch.test.ts @@ -9,7 +9,7 @@ import { describe, test, beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs"; +import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readdirSync } from "node:fs"; import { join } from "node:path"; import { tmpdir } from "node:os"; import { execSync } from "node:child_process"; @@ -57,13 +57,20 @@ function hasRecognizedProjectFiles(basePath: string, existsSyncFn: (p: string) = return false; } +/** Simulate the phases.ts Xcode-bundle detection (readdirSync suffix scan). */ +function hasXcodeBundle(basePath: string): boolean { + try { + return readdirSync(basePath).some((e) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace")); + } catch { return false; } +} + import { existsSync } from "node:fs"; // ─── Tests ─────────────────────────────────────────────────────────────────── test("PROJECT_FILES is exported and contains expected multi-ecosystem entries", () => { assert.ok(Array.isArray(PROJECT_FILES), "PROJECT_FILES is an array"); - assert.ok(PROJECT_FILES.length >= 17, `expected >= 17 entries, got ${PROJECT_FILES.length}`); + assert.ok(PROJECT_FILES.length >= 18, `expected >= 18 entries, got ${PROJECT_FILES.length}`); // Spot-check key ecosystems assert.ok(PROJECT_FILES.includes("Cargo.toml"), "includes Rust marker"); assert.ok(PROJECT_FILES.includes("go.mod"), "includes Go marker"); @@ -140,3 +147,29 @@ describe("health check without git repo", () => { assert.ok(!wouldPassHealthCheck(dir, existsSync), "no-git directory should fail health check"); }); }); + +describe("health check with xcodegen and Xcode bundles", () => { + let dir: string; + beforeEach(() => { dir = createGitRepo(); }); + afterEach(() => { rmSync(dir, { recursive: true, force: true }); }); + + test("health check passes for xcodegen project (project.yml, no Package.swift)", () => { + writeFileSync(join(dir, "project.yml"), "name: MyApp\ntargets:\n MyApp:\n type: application\n"); + assert.ok(wouldPassHealthCheck(dir, existsSync), "xcodegen project should pass health check"); + }); + + // Regression for the real-world failure in #1882: an iOS project with a + // project-specific Xcode bundle (Sudokuxyz.xcodeproj/) was blocked because + // PROJECT_FILES only probes exact filenames, not suffix-based directory names. + test("Xcode bundle (*.xcodeproj) is not in PROJECT_FILES but detected by suffix scan", () => { + mkdirSync(join(dir, "Sudokuxyz.xcodeproj"), { recursive: true }); + mkdirSync(join(dir, "Sources", "Sudokuxyz"), { recursive: true }); + writeFileSync(join(dir, "Sources", "Sudokuxyz", "ContentView.swift"), "import SwiftUI\n"); + // PROJECT_FILES uses exact names — cannot match project-specific bundle names + assert.ok(!hasRecognizedProjectFiles(dir, existsSync), "xcodeproj bundle must NOT be in PROJECT_FILES"); + // The readdirSync suffix scan used in phases.ts detects it + assert.ok(hasXcodeBundle(dir), "readdirSync suffix scan detects .xcodeproj bundle"); + // Health check passes regardless (only requires .git) + assert.ok(wouldPassHealthCheck(dir, existsSync), "Xcode bundle project should pass health check"); + }); +}); diff --git a/src/resources/extensions/gsd/tests/worktree-health-monorepo.test.ts b/src/resources/extensions/gsd/tests/worktree-health-monorepo.test.ts new file mode 100644 index 000000000..12a9f6f1f --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-health-monorepo.test.ts @@ -0,0 +1,73 @@ +/** + * worktree-health-monorepo.test.ts — #2347 + * + * The worktree health check in auto/phases.ts falsely rejects monorepos + * where package.json (or other project markers) is in a parent directory. + * This test verifies that the health check walks parent directories. + */ + +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { createTestContext } from "./test-helpers.ts"; + +const { assertTrue, report } = createTestContext(); + +const srcPath = join(import.meta.dirname, "..", "auto", "phases.ts"); +const src = readFileSync(srcPath, "utf-8"); + +console.log("\n=== #2347: Worktree health check supports monorepos ==="); + +// ── Test 1: The health check region exists ────────────────────────────── + +const healthCheckIdx = src.indexOf("Worktree health check"); +assertTrue(healthCheckIdx > 0, "auto/phases.ts has worktree health check section"); + +const healthCheckRegion = src.slice(healthCheckIdx, healthCheckIdx + 2000); + +// ── Test 2: The check walks parent directories for project markers ────── + +// The fix should check parent directories for project files, not just s.basePath. +// Look for patterns like: walking up directories, dirname, parent, or a helper +// function that checks ancestors. +const checksParentDirs = + healthCheckRegion.includes("dirname") || + healthCheckRegion.includes("parent") || + healthCheckRegion.includes("ancestor") || + healthCheckRegion.includes("walk") || + // Or a helper function that's called with the base path + /hasProjectFileInAncestor|findProjectRoot|checkParent/i.test(healthCheckRegion); + +assertTrue( + checksParentDirs, + "Health check should walk parent directories for project markers (monorepo support) (#2347)", +); + +// ── Test 3: The parent walk stops at a .git boundary ────────────────── + +// The parent directory walk must not escape the git repository root. +// Without this guard, ancestor directories like ~ or /usr/local that +// happen to contain package.json would cause false positive health checks. +const hasGitBoundary = healthCheckRegion.includes('.git') && + (healthCheckRegion.includes('break') || healthCheckRegion.includes('stop')); + +assertTrue( + hasGitBoundary, + "Parent directory walk must stop at .git repository boundary to prevent false positives", +); + +// ── Test 4: The greenfield warning should only trigger when no parent has markers ─ + +// The original code was: +// const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f))); +// The fix should check parents too, so the greenfield warning only fires +// when NO ancestor directory has project markers either. +const hasParentCheck = healthCheckRegion.includes("parent") || + healthCheckRegion.includes("dirname") || + /ancestor|walk.*up/i.test(healthCheckRegion); + +assertTrue( + hasParentCheck, + "Greenfield check should consider parent directories before warning (#2347)", +); + +report(); diff --git a/src/resources/extensions/gsd/tests/worktree-integration.test.ts b/src/resources/extensions/gsd/tests/worktree-integration.test.ts index 9c350ff13..ab0030872 100644 --- a/src/resources/extensions/gsd/tests/worktree-integration.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-integration.test.ts @@ -26,9 +26,11 @@ import { getSliceBranchName, autoCommitCurrentBranch, SLICE_BRANCH_RE, + _resetServiceCache, } from "../worktree.ts"; import { deriveState } from "../state.ts"; +import { _clearGsdRootCache } from "../paths.ts"; import { describe, test } from 'node:test'; import assert from 'node:assert/strict'; @@ -74,6 +76,14 @@ run("git add .", base); run('git commit -m "chore: init"', base); describe('worktree-integration', async () => { + // Isolate from user's global preferences (which may have git.main_branch set). + // Reset caches so getService() creates a fresh instance with empty preferences. + const originalHome = process.env.HOME; + const fakeHome = mkdtempSync(join(tmpdir(), "gsd-fake-home-")); + process.env.HOME = fakeHome; + _clearGsdRootCache(); + _resetServiceCache(); + // ── Verify main tree baseline ────────────────────────────────────────────── console.log("\n=== Main tree baseline ==="); @@ -197,4 +207,10 @@ describe('worktree-integration', async () => { assert.deepStrictEqual(listWorktrees(base).length, 0, "all worktrees removed"); rmSync(base, { recursive: true, force: true }); + + // Restore HOME and reset caches + process.env.HOME = originalHome; + _clearGsdRootCache(); + _resetServiceCache(); + rmSync(fakeHome, { recursive: true, force: true }); }); diff --git a/src/resources/extensions/gsd/tests/worktree-main-branch.test.ts b/src/resources/extensions/gsd/tests/worktree-main-branch.test.ts new file mode 100644 index 000000000..f691f73bd --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-main-branch.test.ts @@ -0,0 +1,20 @@ +/** + * Regression test for #3461: createAutoWorktree must use git.main_branch + * preference when META.json integration branch is absent. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +test("auto-worktree.ts includes main_branch preference in startPoint fallback (#3461)", () => { + const src = readFileSync( + join(import.meta.dirname, "..", "auto-worktree.ts"), + "utf-8", + ); + // The fix adds gitPrefs?.main_branch to the startPoint fallback chain + assert.ok( + src.includes("gitPrefs?.main_branch") || src.includes("prefs.main_branch"), + "createAutoWorktree must check git.main_branch preference before falling back to nativeDetectMainBranch", + ); +}); diff --git a/src/resources/extensions/gsd/tests/worktree-nested-git-safety.test.ts b/src/resources/extensions/gsd/tests/worktree-nested-git-safety.test.ts new file mode 100644 index 000000000..27ec1383a --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-nested-git-safety.test.ts @@ -0,0 +1,101 @@ +/** + * worktree-nested-git-safety.test.ts — #2616 + * + * When scaffolding tools (create-next-app, cargo init, etc.) run inside a + * worktree, they create nested .git directories. Git treats these as gitlinks + * (mode 160000) without a .gitmodules entry, so the worktree cleanup destroys + * the only copy of those object databases — causing permanent data loss. + * + * This test verifies that removeWorktree detects nested .git directories + * (orphaned gitlinks) and absorbs or removes them before cleanup so files + * are tracked as regular content instead of unreachable gitlink pointers. + */ + +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { createTestContext } from "./test-helpers.ts"; + +const { assertTrue, report } = createTestContext(); + +const srcPath = join(import.meta.dirname, "..", "worktree-manager.ts"); +const src = readFileSync(srcPath, "utf-8"); + +console.log("\n=== #2616: Worktree cleanup detects nested .git directories ==="); + +// ── Test 1: removeWorktree scans for nested .git directories ───────── + +const removeWorktreeIdx = src.indexOf("export function removeWorktree"); +assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree"); + +const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 5000); + +const detectsNestedGit = + fnBody.includes("nested") && fnBody.includes(".git") || + fnBody.includes("gitlink") || + fnBody.includes("160000") || + fnBody.includes("findNestedGitDirs") || + fnBody.includes("nestedGitDirs"); + +assertTrue( + detectsNestedGit, + "removeWorktree detects nested .git directories or gitlinks (#2616)", +); + +// ── Test 2: A helper function exists to find nested .git directories ── + +const hasNestedGitHelper = + src.includes("findNestedGitDirs") || + src.includes("detectNestedGitDirs") || + src.includes("scanNestedGit") || + src.includes("absorbNestedGit") || + src.includes("nestedGitDirs"); + +assertTrue( + hasNestedGitHelper, + "worktree-manager has a helper to find nested .git directories (#2616)", +); + +// ── Test 3: Nested .git dirs are absorbed or removed before cleanup ─── + +const absorbsOrRemoves = + fnBody.includes("absorb") || + fnBody.includes("rmSync") && fnBody.includes("nested") || + (fnBody.includes("nestedGitDirs") || fnBody.includes("findNestedGitDirs")) && + (fnBody.includes("rm") || fnBody.includes("absorb") || fnBody.includes("remove")); + +assertTrue( + absorbsOrRemoves, + "removeWorktree absorbs or removes nested .git dirs before cleanup (#2616)", +); + +// ── Test 4: A warning is logged when nested .git dirs are found ─────── + +const warnsAboutNestedGit = + fnBody.includes("nested") && fnBody.includes("logWarning") || + fnBody.includes("gitlink") && fnBody.includes("logWarning") || + fnBody.includes("scaffold") && fnBody.includes("logWarning"); + +assertTrue( + warnsAboutNestedGit, + "removeWorktree warns when nested .git directories are detected (#2616)", +); + +// ── Test 5: The findNestedGitDirs helper correctly identifies nested repos ── +// Verify the helper scans subdirectories but skips .gsd/, node_modules/, .git/ + +const helperBody = src.includes("findNestedGitDirs") + ? src.slice(src.indexOf("findNestedGitDirs")) + : ""; + +const skipsExcludedDirs = + helperBody.includes("node_modules") || + helperBody.includes(".gsd") || + helperBody.includes("skip") || + helperBody.includes("exclude"); + +assertTrue( + skipsExcludedDirs, + "findNestedGitDirs skips node_modules and other excluded directories (#2616)", +); + +report(); diff --git a/src/resources/extensions/gsd/tests/worktree-resolver.test.ts b/src/resources/extensions/gsd/tests/worktree-resolver.test.ts index c3a7f7aba..97a766f3c 100644 --- a/src/resources/extensions/gsd/tests/worktree-resolver.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-resolver.test.ts @@ -481,7 +481,8 @@ test("mergeAndExit resolves roadmap from worktree when missing at project root ( // Should have called mergeMilestoneToMain, not bare teardown assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 1); - assert.equal(findCalls(deps.calls, "teardownAutoWorktree").length, 0); + // #2945 Bug 3: secondary teardown is now called after merge for cleanup + assert.equal(findCalls(deps.calls, "teardownAutoWorktree").length, 1); assert.equal(s.basePath, "/project"); // restored assert.ok(ctx.messages.some((m) => m.msg.includes("merged to main"))); }); @@ -549,6 +550,40 @@ test("mergeAndExit failure message tells user worktree and branch are preserved ); }); +test("mergeAndExit failure message references /gsd dispatch complete-milestone, not /complete-milestone (#1891)", () => { + // Regression test: the failure notification previously told users to + // "retry /complete-milestone" — a command that does not exist. The correct + // recovery command is "/gsd dispatch complete-milestone". + const s = makeSession({ + basePath: "/project/.gsd/worktrees/M001", + originalBasePath: "/project", + }); + const deps = makeDeps({ + isInAutoWorktree: () => true, + getIsolationMode: () => "worktree", + mergeMilestoneToMain: () => { + throw new Error("dirty working tree"); + }, + }); + const ctx = makeNotifyCtx(); + const resolver = new WorktreeResolver(s, deps); + + resolver.mergeAndExit("M001", ctx); + + const warning = ctx.messages.find((m) => m.level === "warning"); + assert.ok(warning, "a warning message is emitted"); + // Must reference the correct dispatch command + assert.ok( + warning!.msg.includes("/gsd dispatch complete-milestone"), + "warning references /gsd dispatch complete-milestone, not bare /complete-milestone", + ); + // Must NOT contain the bare (incorrect) command without the dispatch prefix + assert.ok( + !warning!.msg.match(/retry\s+\/complete-milestone(?!\S)/), + "warning must not reference the non-existent /complete-milestone command", + ); +}); + // ─── mergeAndExit Tests (branch mode) ──────────────────────────────────────── test("mergeAndExit in branch mode merges when on milestone branch", () => { @@ -913,3 +948,49 @@ test("isolationDegraded is reset by session.reset() (#2483)", () => { assert.equal(s.isolationDegraded, false); }); + +// ─── #2625 — Default isolation mode change must not orphan worktree commits ── + +test("mergeAndExit still merges when mode is 'none' but session is in a worktree (#2625)", () => { + // Scenario: user upgraded from a version where default was "worktree" to one + // where default is "none". They have an active worktree with committed work. + // mergeAndExit must detect the active worktree and merge regardless of config. + const s = makeSession({ + basePath: "/project/.gsd/worktrees/M001", + originalBasePath: "/project", + }); + const deps = makeDeps({ + isInAutoWorktree: () => true, + getIsolationMode: () => "none", // config says "none" — but we ARE in a worktree + }); + const ctx = makeNotifyCtx(); + const resolver = new WorktreeResolver(s, deps); + + resolver.mergeAndExit("M001", ctx); + + // Must still merge — not skip silently + assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 1, + "must call mergeMilestoneToMain even when isolation mode is 'none' but we are in a worktree"); + assert.equal(s.basePath, "/project", "basePath must be restored to project root"); + assert.ok(ctx.messages.some((m) => m.msg.includes("merged to main")), + "must notify about the merge"); +}); + +test("mergeAndExit in none mode remains a no-op when NOT in a worktree (#2625)", () => { + // When mode is "none" and we are genuinely not in a worktree, it should still be a no-op. + const s = makeSession({ + basePath: "/project", + originalBasePath: "/project", + }); + const deps = makeDeps({ + isInAutoWorktree: () => false, + getIsolationMode: () => "none", + }); + const ctx = makeNotifyCtx(); + const resolver = new WorktreeResolver(s, deps); + + resolver.mergeAndExit("M001", ctx); + + assert.equal(findCalls(deps.calls, "mergeMilestoneToMain").length, 0, + "must NOT merge when not in a worktree and mode is none"); +}); diff --git a/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts b/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts index c32b8fe80..7414705f5 100644 --- a/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-submodule-safety.test.ts @@ -22,7 +22,7 @@ console.log("\n=== #2337: Worktree teardown preserves submodule state ==="); const removeWorktreeIdx = src.indexOf("export function removeWorktree"); assertTrue(removeWorktreeIdx > 0, "worktree-manager.ts exports removeWorktree"); -const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 3000); +const fnBody = src.slice(removeWorktreeIdx, removeWorktreeIdx + 6000); // ── Test 2: The function checks for submodules before force removal ───── diff --git a/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts b/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts index 94cebb383..57ebe3740 100644 --- a/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts @@ -100,8 +100,8 @@ describe('worktree-sync-milestones', async () => { } } - // ─── 3. gsd.db deleted in worktree after sync ───────────────────────── - console.log('\n=== 3. gsd.db deleted in worktree after sync ==='); + // ─── 3. empty gsd.db deleted in worktree after sync ──────────────────── + console.log('\n=== 3. empty gsd.db deleted in worktree after sync ==='); { const mainBase = createBase('main'); const wtBase = createBase('wt'); @@ -111,13 +111,37 @@ describe('worktree-sync-milestones', async () => { mkdirSync(m001Dir, { recursive: true }); writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); - // Worktree has a stale gsd.db - writeFileSync(join(wtBase, '.gsd', 'gsd.db'), 'stale data'); + // Worktree has an empty (0-byte) gsd.db — stale/corrupt + writeFileSync(join(wtBase, '.gsd', 'gsd.db'), ''); assert.ok(existsSync(join(wtBase, '.gsd', 'gsd.db')), 'gsd.db exists before sync'); syncProjectRootToWorktree(mainBase, wtBase, 'M001'); - assert.ok(!existsSync(join(wtBase, '.gsd', 'gsd.db')), '#853: gsd.db deleted after sync'); + assert.ok(!existsSync(join(wtBase, '.gsd', 'gsd.db')), '#853: empty gsd.db deleted after sync'); + } finally { + cleanup(mainBase); + cleanup(wtBase); + } + } + + // ─── 3b. non-empty gsd.db preserved in worktree after sync (#2815) ─── + console.log('\n=== 3b. non-empty gsd.db preserved in worktree after sync (#2815) ==='); + { + const mainBase = createBase('main'); + const wtBase = createBase('wt'); + + try { + const m001Dir = join(mainBase, '.gsd', 'milestones', 'M001'); + mkdirSync(m001Dir, { recursive: true }); + writeFileSync(join(m001Dir, 'M001-ROADMAP.md'), '# Roadmap'); + + // Worktree has a populated gsd.db (e.g. from gsd-migrate on respawn) + writeFileSync(join(wtBase, '.gsd', 'gsd.db'), 'migrated-db-content'); + assert.ok(existsSync(join(wtBase, '.gsd', 'gsd.db')), 'gsd.db exists before sync'); + + syncProjectRootToWorktree(mainBase, wtBase, 'M001'); + + assert.ok(existsSync(join(wtBase, '.gsd', 'gsd.db')), '#2815: non-empty gsd.db preserved after sync'); } finally { cleanup(mainBase); cleanup(wtBase); @@ -197,7 +221,8 @@ describe('worktree-sync-milestones', async () => { try { // Build worktree milestone structure with slice-level and task-level files - const wtSliceDir = join(wtBase, '.gsd', 'milestones', 'M001', 'slices', 'S01'); + // Use M002 as the milestone to sync, M001 as the "current" being merged (skipped) + const wtSliceDir = join(wtBase, '.gsd', 'milestones', 'M002', 'slices', 'S01'); const wtTasksDir = join(wtSliceDir, 'tasks'); mkdirSync(wtTasksDir, { recursive: true }); writeFileSync(join(wtSliceDir, 'S01-SUMMARY.md'), '# S01 Summary'); @@ -205,11 +230,12 @@ describe('worktree-sync-milestones', async () => { writeFileSync(join(wtTasksDir, 'T02-SUMMARY.md'), '# T02 Summary'); // Main project root starts with only the milestone directory (no slices yet) - mkdirSync(join(mainBase, '.gsd', 'milestones', 'M001'), { recursive: true }); + mkdirSync(join(mainBase, '.gsd', 'milestones', 'M002'), { recursive: true }); + // Pass M001 as milestoneId (the one being merged/skipped), M002 should still sync const { synced } = syncWorktreeStateBack(mainBase, wtBase, 'M001'); - const mainSliceDir = join(mainBase, '.gsd', 'milestones', 'M001', 'slices', 'S01'); + const mainSliceDir = join(mainBase, '.gsd', 'milestones', 'M002', 'slices', 'S01'); const mainTasksDir = join(mainSliceDir, 'tasks'); assert.ok( @@ -317,16 +343,16 @@ describe('worktree-sync-milestones', async () => { 'M002 missing in main before sync', ); - // Sync with milestoneId = M001 (the current milestone) + // Sync with milestoneId = M001 (the current milestone being merged — skipped) const { synced } = syncWorktreeStateBack(mainBase, wtBase, 'M001'); - // M001 should be synced (current milestone — always synced) + // M001 should be SKIPPED (current milestone being merged — #3641) assert.ok( - existsSync(join(mainBase, '.gsd', 'milestones', 'M001', 'M001-SUMMARY.md')), - 'M001 SUMMARY synced to main', + !existsSync(join(mainBase, '.gsd', 'milestones', 'M001', 'M001-SUMMARY.md')), + 'M001 SUMMARY NOT synced (current milestone skipped to prevent merge conflicts)', ); - // M002 should ALSO be synced (next milestone — the fix) + // M002 should be synced (other milestone — not skipped) assert.ok( existsSync(join(mainBase, '.gsd', 'milestones', 'M002-abc123', 'M002-abc123-CONTEXT.md')), 'M002 CONTEXT synced to main (next-milestone fix)', @@ -383,20 +409,17 @@ describe('worktree-sync-milestones', async () => { writeFileSync(join(wtBase, '.gsd', 'REQUIREMENTS.md'), '# Requirements\n## R001-R089\n## R090 — SCIM\n## R091 — WebAuthn'); writeFileSync(join(wtBase, '.gsd', 'PROJECT.md'), '# Project\nMilestones: M001-M007'); - // Sync with milestoneId = M006 (the completing milestone) + // Sync with milestoneId = M006 (the completing milestone — skipped by sync) const { synced } = syncWorktreeStateBack(mainBase, wtBase, 'M006-589wvh'); - // Verify M006 artifacts synced + // M006 is the current milestone being merged — it should be SKIPPED (#3641) + // Its files are already in the milestone branch and would conflict with squash merge. assert.ok( - existsSync(join(mainBase, '.gsd', 'milestones', 'M006-589wvh', 'M006-589wvh-SUMMARY.md')), - 'M006 SUMMARY synced', - ); - assert.ok( - existsSync(join(mainBase, '.gsd', 'milestones', 'M006-589wvh', 'slices', 'S01', 'S01-SUMMARY.md')), - 'M006 S01 SUMMARY synced', + !existsSync(join(mainBase, '.gsd', 'milestones', 'M006-589wvh', 'M006-589wvh-SUMMARY.md')), + 'M006 SUMMARY NOT synced (current milestone skipped)', ); - // Verify M007 artifacts synced (the critical fix) + // Verify M007 artifacts synced (the critical fix — other milestones still sync) assert.ok( existsSync(join(mainBase, '.gsd', 'milestones', 'M007-wortc8', 'M007-wortc8-CONTEXT.md')), 'M007 CONTEXT synced to main (next-milestone)', diff --git a/src/resources/extensions/gsd/tests/worktree-sync-tasks.test.ts b/src/resources/extensions/gsd/tests/worktree-sync-tasks.test.ts index 43d57c59e..65717415c 100644 --- a/src/resources/extensions/gsd/tests/worktree-sync-tasks.test.ts +++ b/src/resources/extensions/gsd/tests/worktree-sync-tasks.test.ts @@ -47,7 +47,8 @@ function writeFile(dir: string, relativePath: string, content: string): void { test("syncWorktreeStateBack copies task summaries from tasks/ subdirectory (#1678)", () => { const mainBase = makeTempDir("main"); const wtBase = makeTempDir("wt"); - const mid = "M001"; + const currentMid = "M000"; // milestone being merged (skipped by sync) + const mid = "M001"; // other milestone that should be synced try { // Set up worktree with milestone, slice, and task files @@ -64,8 +65,8 @@ test("syncWorktreeStateBack copies task summaries from tasks/ subdirectory (#167 // Set up main with empty .gsd mkdirSync(join(mainBase, ".gsd"), { recursive: true }); - // Run sync - const result = syncWorktreeStateBack(mainBase, wtBase, mid); + // Run sync — currentMid is skipped, mid (M001) should be synced + const result = syncWorktreeStateBack(mainBase, wtBase, currentMid); // Verify milestone-level files synced assert.ok( @@ -126,7 +127,8 @@ test("syncWorktreeStateBack copies task summaries from tasks/ subdirectory (#167 test("syncWorktreeStateBack handles multiple slices with tasks (#1678)", () => { const mainBase = makeTempDir("main"); const wtBase = makeTempDir("wt"); - const mid = "M002"; + const currentMid = "M000"; // milestone being merged (skipped) + const mid = "M002"; // other milestone that should be synced try { // Set up two slices with tasks @@ -139,7 +141,7 @@ test("syncWorktreeStateBack handles multiple slices with tasks (#1678)", () => { mkdirSync(join(mainBase, ".gsd"), { recursive: true }); - const result = syncWorktreeStateBack(mainBase, wtBase, mid); + const result = syncWorktreeStateBack(mainBase, wtBase, currentMid); // All task summaries from both slices should be synced assert.ok(existsSync(join(mainBase, `.gsd/milestones/${mid}/slices/S01/tasks/T01-SUMMARY.md`))); @@ -160,7 +162,8 @@ test("syncWorktreeStateBack handles multiple slices with tasks (#1678)", () => { test("syncWorktreeStateBack handles slices without tasks/ directory", () => { const mainBase = makeTempDir("main"); const wtBase = makeTempDir("wt"); - const mid = "M003"; + const currentMid = "M000"; // milestone being merged (skipped) + const mid = "M003"; // other milestone that should be synced try { // Slice with no tasks/ subdirectory (legitimate case: pre-planning) @@ -168,7 +171,7 @@ test("syncWorktreeStateBack handles slices without tasks/ directory", () => { mkdirSync(join(mainBase, ".gsd"), { recursive: true }); - const result = syncWorktreeStateBack(mainBase, wtBase, mid); + const result = syncWorktreeStateBack(mainBase, wtBase, currentMid); // Should sync the slice file without errors assert.ok(existsSync(join(mainBase, `.gsd/milestones/${mid}/slices/S01/S01-RESEARCH.md`))); @@ -183,7 +186,8 @@ test("syncWorktreeStateBack handles slices without tasks/ directory", () => { test("syncWorktreeStateBack ignores non-md files in tasks/", () => { const mainBase = makeTempDir("main"); const wtBase = makeTempDir("wt"); - const mid = "M004"; + const currentMid = "M000"; // milestone being merged (skipped) + const mid = "M004"; // other milestone that should be synced try { writeFile(wtBase, `.gsd/milestones/${mid}/slices/S01/S01-PLAN.md`, "# Plan\n"); @@ -194,7 +198,7 @@ test("syncWorktreeStateBack ignores non-md files in tasks/", () => { mkdirSync(join(mainBase, ".gsd"), { recursive: true }); - const result = syncWorktreeStateBack(mainBase, wtBase, mid); + const result = syncWorktreeStateBack(mainBase, wtBase, currentMid); // Only .md files should be synced assert.ok(existsSync(join(mainBase, `.gsd/milestones/${mid}/slices/S01/tasks/T01-SUMMARY.md`))); diff --git a/src/resources/extensions/gsd/tests/worktree-teardown-safety.test.ts b/src/resources/extensions/gsd/tests/worktree-teardown-safety.test.ts new file mode 100644 index 000000000..e6f9ef134 --- /dev/null +++ b/src/resources/extensions/gsd/tests/worktree-teardown-safety.test.ts @@ -0,0 +1,148 @@ +/** + * worktree-teardown-safety.test.ts — Regression test for #2365. + * + * Ensures that removeWorktree() and teardownAutoWorktree() never delete + * directories outside .gsd/worktrees/. The bug: removeWorktree overrides + * the computed worktree path with whatever `git worktree list` reports. + * When .gsd/ was (or is) a symlink, git resolves the symlink at creation + * time, so its registered path can point to an external directory. If that + * external path happens to be a project data directory, teardown destroys it. + * + * The fix adds path validation so rmSync / nativeWorktreeRemove only operate + * on paths that are actually under .gsd/worktrees/. + */ + +import { + mkdtempSync, + mkdirSync, + writeFileSync, + rmSync, + existsSync, + realpathSync, + readFileSync, +} from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { execSync } from "node:child_process"; +import { describe, it, after } from "node:test"; + +import { createWorktree, removeWorktree, worktreePath, isInsideWorktreesDir } from "../worktree-manager.ts"; +import { createTestContext } from "./test-helpers.ts"; + +const { assertEq, assertTrue, report } = createTestContext(); + +// ─── Helpers ────────────────────────────────────────────────────────────── + +function run(command: string, cwd: string): string { + return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim(); +} + +function createTempRepo(): string { + const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-safety-test-"))); + run("git init", dir); + run("git config user.email test@test.com", dir); + run("git config user.name Test", dir); + writeFileSync(join(dir, "README.md"), "# test\n"); + run("git add .", dir); + run("git commit -m init", dir); + run("git branch -M main", dir); + return dir; +} + +// ─── Tests ──────────────────────────────────────────────────────────────── + +describe("worktree-teardown-safety", () => { + const dirs: string[] = []; + + after(() => { + for (const d of dirs) rmSync(d, { recursive: true, force: true }); + report(); + }); + + it("removeWorktree does not delete sibling data directories", () => { + const tempDir = createTempRepo(); + dirs.push(tempDir); + + // Create a project data directory that lives alongside .gsd/ + const dataDir = join(tempDir, "project-data"); + mkdirSync(dataDir, { recursive: true }); + writeFileSync(join(dataDir, "important.db"), "precious data"); + + // Create a worktree normally + const wt = createWorktree(tempDir, "test-wt"); + assertTrue(existsSync(wt.path), "worktree created successfully"); + + // Remove the worktree + removeWorktree(tempDir, "test-wt"); + + // The worktree directory should be gone + assertTrue(!existsSync(wt.path), "worktree directory removed"); + + // The project data directory MUST still exist + assertTrue(existsSync(dataDir), "project data directory survives teardown"); + assertTrue( + existsSync(join(dataDir, "important.db")), + "project data files survive teardown", + ); + }); + + it("path validation rejects paths outside .gsd/worktrees/", () => { + const tempDir = createTempRepo(); + dirs.push(tempDir); + + const externalDir = join(tempDir, "external-state"); + mkdirSync(externalDir, { recursive: true }); + writeFileSync(join(externalDir, "state.json"), '{"critical": true}'); + + // Create and then remove a worktree that has a legitimate path + const wt2 = createWorktree(tempDir, "safe-wt"); + assertTrue(existsSync(wt2.path), "second worktree created"); + + removeWorktree(tempDir, "safe-wt"); + assertTrue(!existsSync(wt2.path), "second worktree removed cleanly"); + + // External directory must be untouched + assertTrue(existsSync(externalDir), "external directory survives second teardown"); + assertEq( + readFileSync(join(externalDir, "state.json"), "utf-8"), + '{"critical": true}', + "external directory contents intact after teardown", + ); + }); + + it("worktreePath always returns paths under .gsd/worktrees/", () => { + const tempDir = createTempRepo(); + dirs.push(tempDir); + + const wtPathResult = worktreePath(tempDir, "anything"); + assertTrue( + wtPathResult.startsWith(join(tempDir, ".gsd", "worktrees")), + "worktreePath returns path under .gsd/worktrees/", + ); + }); + + it("isInsideWorktreesDir rejects path traversal attempts", () => { + const tempDir = createTempRepo(); + dirs.push(tempDir); + + assertTrue( + isInsideWorktreesDir(tempDir, join(tempDir, ".gsd", "worktrees", "my-wt")), + "path inside .gsd/worktrees/ is accepted", + ); + + assertTrue( + !isInsideWorktreesDir(tempDir, join(tempDir, "project-data")), + "path outside .gsd/worktrees/ is rejected", + ); + + assertTrue( + !isInsideWorktreesDir(tempDir, join(tempDir, ".gsd", "worktrees", "..", "..", "project-data")), + "path traversal via .. is rejected", + ); + + assertTrue( + !isInsideWorktreesDir(tempDir, "/tmp/some-other-dir"), + "completely external path is rejected", + ); + }); +}); diff --git a/src/resources/extensions/gsd/tests/worktree.test.ts b/src/resources/extensions/gsd/tests/worktree.test.ts index 71dd32be7..a23f925eb 100644 --- a/src/resources/extensions/gsd/tests/worktree.test.ts +++ b/src/resources/extensions/gsd/tests/worktree.test.ts @@ -14,9 +14,11 @@ import { resolveProjectRoot, setActiveMilestoneId, SLICE_BRANCH_RE, + _resetServiceCache, } from "../worktree.ts"; import { readIntegrationBranch } from "../git-service.ts"; import { _resetHasChangesCache } from "../native-git-bridge.ts"; +import { _clearGsdRootCache } from "../paths.ts"; import { describe, test } from 'node:test'; import assert from 'node:assert/strict'; @@ -165,15 +167,30 @@ describe('worktree', async () => { run("git checkout -b my-feature", repo); captureIntegrationBranch(repo, "M001"); - // Without milestone set, getMainBranch returns "main" - setActiveMilestoneId(repo, null); - assert.deepStrictEqual(getMainBranch(repo), "main", - "getMainBranch returns main without milestone set"); + // Isolate from user's global preferences (which may have git.main_branch set). + // Reset caches so getService() creates a fresh instance with empty preferences. + const originalHome = process.env.HOME; + const fakeHome = mkdtempSync(join(tmpdir(), "gsd-fake-home-")); + process.env.HOME = fakeHome; + _clearGsdRootCache(); + _resetServiceCache(); - // With milestone set, getMainBranch returns feature branch - setActiveMilestoneId(repo, "M001"); - assert.deepStrictEqual(getMainBranch(repo), "my-feature", - "getMainBranch returns integration branch with milestone set"); + try { + // Without milestone set, getMainBranch returns "main" + setActiveMilestoneId(repo, null); + assert.deepStrictEqual(getMainBranch(repo), "main", + "getMainBranch returns main without milestone set"); + + // With milestone set, getMainBranch returns feature branch + setActiveMilestoneId(repo, "M001"); + assert.deepStrictEqual(getMainBranch(repo), "my-feature", + "getMainBranch returns integration branch with milestone set"); + } finally { + process.env.HOME = originalHome; + _clearGsdRootCache(); + _resetServiceCache(); + rmSync(fakeHome, { recursive: true, force: true }); + } rmSync(repo, { recursive: true, force: true }); } diff --git a/src/resources/extensions/gsd/tests/write-gate.test.ts b/src/resources/extensions/gsd/tests/write-gate.test.ts index 8ca4ee7b5..04b2c4603 100644 --- a/src/resources/extensions/gsd/tests/write-gate.test.ts +++ b/src/resources/extensions/gsd/tests/write-gate.test.ts @@ -3,22 +3,23 @@ * * Exercises shouldBlockContextWrite() — a pure function that implements: * (a) toolName !== "write" → pass - * (b) milestoneId null → pass (not in discussion) + * (b) milestone context must resolve to a verified milestone * (c) path doesn't match /M\d+-CONTEXT\.md$/ → pass - * (d) depthVerified → pass + * (d) non-context files → pass * (e) else → block with actionable reason */ import test from 'node:test'; import assert from 'node:assert/strict'; import { + isDepthConfirmationAnswer, shouldBlockContextWrite, - isDepthVerified, - isQueuePhaseActive, setQueuePhaseActive, } from '../index.ts'; import { markDepthVerified, + isMilestoneDepthVerified, + shouldBlockContextArtifactSave, clearDiscussionFlowState, resetWriteGateState, } from '../bootstrap/write-gate.ts'; @@ -52,26 +53,27 @@ test('write-gate: blocks CONTEXT.md write during discussion without depth verifi // ─── Scenario 3: Allows CONTEXT.md write after depth verification ── test('write-gate: allows CONTEXT.md write after depth verification', () => { + clearDiscussionFlowState(); + markDepthVerified('M001'); const result = shouldBlockContextWrite( 'write', '/Users/dev/project/.gsd/milestones/M001/M001-CONTEXT.md', 'M001', - true, ); assert.strictEqual(result.block, false, 'should not block after depth verification'); assert.strictEqual(result.reason, undefined, 'should have no reason'); + clearDiscussionFlowState(); }); -// ─── Scenario 4: Allows CONTEXT.md write outside discussion phase (milestoneId null) ── +// ─── Scenario 4: Ambiguous session context no longer bypasses the gate ── -test('write-gate: allows CONTEXT.md write outside discussion phase', () => { +test('write-gate: blocks CONTEXT.md write when milestoneId is ambiguous', () => { const result = shouldBlockContextWrite( 'write', '.gsd/milestones/M001/M001-CONTEXT.md', null, - false, ); - assert.strictEqual(result.block, false, 'should not block outside discussion phase'); + assert.strictEqual(result.block, true, 'should block when milestone context is ambiguous'); }); // ─── Scenario 5: Allows non-CONTEXT.md writes during discussion ── @@ -82,7 +84,6 @@ test('write-gate: allows non-CONTEXT.md writes during discussion', () => { 'write', '.gsd/milestones/M001/M001-DISCUSSION.md', 'M001', - false, ); assert.strictEqual(r1.block, false, 'DISCUSSION.md should pass'); @@ -91,7 +92,6 @@ test('write-gate: allows non-CONTEXT.md writes during discussion', () => { 'write', '.gsd/milestones/M001/slices/S01/S01-PLAN.md', 'M001', - false, ); assert.strictEqual(r2.block, false, 'slice plan should pass'); @@ -100,7 +100,6 @@ test('write-gate: allows non-CONTEXT.md writes during discussion', () => { 'write', 'src/index.ts', 'M001', - false, ); assert.strictEqual(r3.block, false, 'regular code file should pass'); }); @@ -112,23 +111,23 @@ test('write-gate: regex does not match slice context files (S01-CONTEXT.md)', () 'write', '.gsd/milestones/M001/slices/S01/S01-CONTEXT.md', 'M001', - false, ); assert.strictEqual(result.block, false, 'S01-CONTEXT.md should not be blocked'); }); -// ─── Scenario 7: Error message contains actionable instruction ── +// ─── Scenario 7: Error message contains actionable instruction and anti-bypass language ── -test('write-gate: blocked reason contains depth_verification keyword', () => { +test('write-gate: blocked reason contains depth_verification keyword and anti-bypass language', () => { const result = shouldBlockContextWrite( 'write', '.gsd/milestones/M999/M999-CONTEXT.md', 'M999', - false, ); assert.strictEqual(result.block, true); assert.ok(result.reason!.includes('depth_verification'), 'reason should mention depth_verification question id'); assert.ok(result.reason!.includes('ask_user_questions'), 'reason should mention ask_user_questions tool'); + assert.ok(result.reason!.includes('MUST NOT'), 'reason should include anti-bypass language'); + assert.ok(result.reason!.includes('(Recommended)'), 'reason should specify the required confirmation option'); }); // ─── Scenario 8: Queue mode blocks CONTEXT.md write without depth verification ── @@ -138,7 +137,6 @@ test('write-gate: blocks CONTEXT.md write in queue mode without depth verificati 'write', '.gsd/milestones/M001/M001-CONTEXT.md', null, // no milestoneId in queue mode - false, // not depth-verified true, // queue phase active ); assert.strictEqual(result.block, true, 'should block in queue mode without depth verification'); @@ -148,46 +146,345 @@ test('write-gate: blocks CONTEXT.md write in queue mode without depth verificati // ─── Scenario 9: Queue mode allows CONTEXT.md write after depth verification ── test('write-gate: allows CONTEXT.md write in queue mode after depth verification', () => { + clearDiscussionFlowState(); + markDepthVerified('M001'); const result = shouldBlockContextWrite( 'write', '.gsd/milestones/M001/M001-CONTEXT.md', null, // no milestoneId in queue mode - true, // depth-verified true, // queue phase active ); assert.strictEqual(result.block, false, 'should not block in queue mode after depth verification'); + clearDiscussionFlowState(); }); -// ─── Scenario 10: markDepthVerified works in queue-only mode (no milestoneId) ── -// This is the core regression for #1812: in queue mode, the tool_result handler -// must call markDepthVerified() even when getDiscussionMilestoneId() is null. +// ─── Scenario 10: depth verification is scoped per milestone, not global ── -test('write-gate: markDepthVerified unblocks queue-mode writes when milestoneId is null', () => { +test('write-gate: markDepthVerified unlocks only the matching milestone', () => { clearDiscussionFlowState(); - setQueuePhaseActive(true); + markDepthVerified('M001'); - // Before marking: should block - const blocked = shouldBlockContextWrite( - 'write', - '.gsd/milestones/M001/M001-CONTEXT.md', - null, - isDepthVerified(), - isQueuePhaseActive(), - ); - assert.strictEqual(blocked.block, true, 'should block before markDepthVerified'); - - // Simulate what the fixed tool_result handler does - markDepthVerified(); - - // After marking: should pass const allowed = shouldBlockContextWrite( 'write', '.gsd/milestones/M001/M001-CONTEXT.md', null, - isDepthVerified(), - isQueuePhaseActive(), ); - assert.strictEqual(allowed.block, false, 'should allow after markDepthVerified in queue mode'); + assert.strictEqual(allowed.block, false, 'should allow the verified milestone'); + + const blockedOther = shouldBlockContextWrite( + 'write', + '.gsd/milestones/M002/M002-CONTEXT.md', + null, + ); + assert.strictEqual(blockedOther.block, true, 'other milestones should remain blocked'); + assert.strictEqual(isMilestoneDepthVerified('M001'), true); + assert.strictEqual(isMilestoneDepthVerified('M002'), false); clearDiscussionFlowState(); }); + +// ─── Scenario 11: gsd_summary_save CONTEXT contract is milestone-scoped ── + +test('write-gate: gsd_summary_save only blocks final milestone CONTEXT writes', () => { + clearDiscussionFlowState(); + + assert.strictEqual( + shouldBlockContextArtifactSave('CONTEXT-DRAFT', 'M001').block, + false, + 'draft CONTEXT should be allowed', + ); + assert.strictEqual( + shouldBlockContextArtifactSave('CONTEXT', 'M001', 'S01').block, + false, + 'slice CONTEXT should be allowed', + ); + assert.strictEqual( + shouldBlockContextArtifactSave('CONTEXT', 'M001').block, + true, + 'final milestone CONTEXT should block before verification', + ); + + markDepthVerified('M001'); + assert.strictEqual( + shouldBlockContextArtifactSave('CONTEXT', 'M001').block, + false, + 'final milestone CONTEXT should pass after verification', + ); + + clearDiscussionFlowState(); +}); + +// ═══════════════════════════════════════════════════════════════════════ +// Discussion gate enforcement tests (pending gate mechanism) +// ═══════════════════════════════════════════════════════════════════════ + +import { + isGateQuestionId, + shouldBlockPendingGate, + shouldBlockPendingGateBash, + setPendingGate, + clearPendingGate, + getPendingGate, +} from '../bootstrap/write-gate.ts'; + +// ─── Scenario 19: isGateQuestionId recognizes all gate patterns ── + +test('write-gate: isGateQuestionId recognizes all gate patterns', () => { + assert.strictEqual(isGateQuestionId('depth_verification'), true); + assert.strictEqual(isGateQuestionId('depth_verification_M002'), true); + assert.strictEqual(isGateQuestionId('depth_verification_confirm'), true); + // Non-gate question IDs + assert.strictEqual(isGateQuestionId('project_intent'), false); + assert.strictEqual(isGateQuestionId('feature_priority'), false); + assert.strictEqual(isGateQuestionId('layer1_scope_gate'), false); + assert.strictEqual(isGateQuestionId(''), false); +}); + +// ─── Scenario 20: setPendingGate / getPendingGate / clearPendingGate lifecycle ── + +test('write-gate: pending gate lifecycle (set, get, clear)', () => { + clearDiscussionFlowState(); + assert.strictEqual(getPendingGate(), null, 'starts null'); + + setPendingGate('depth_verification'); + assert.strictEqual(getPendingGate(), 'depth_verification', 'set correctly'); + + clearPendingGate(); + assert.strictEqual(getPendingGate(), null, 'cleared correctly'); + + // clearDiscussionFlowState also clears pending gate + setPendingGate('depth_verification_M002'); + clearDiscussionFlowState(); + assert.strictEqual(getPendingGate(), null, 'clearDiscussionFlowState clears pending gate'); +}); + +// ─── Scenario 21: shouldBlockPendingGate blocks non-safe tools when gate is pending ── + +test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate', () => { + clearDiscussionFlowState(); + setPendingGate('depth_verification'); + + // write should be blocked during discussion + const writeResult = shouldBlockPendingGate('write', 'M001', false); + assert.strictEqual(writeResult.block, true, 'write should be blocked'); + assert.ok(writeResult.reason!.includes('depth_verification'), 'reason mentions the gate'); + + // edit should be blocked + const editResult = shouldBlockPendingGate('edit', 'M001', false); + assert.strictEqual(editResult.block, true, 'edit should be blocked'); + + // gsd tools should be blocked + const gsdResult = shouldBlockPendingGate('gsd_plan_milestone', 'M001', false); + assert.strictEqual(gsdResult.block, true, 'gsd tools should be blocked'); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 22: shouldBlockPendingGate allows safe tools when gate is pending ── + +test('write-gate: shouldBlockPendingGate allows read-only and ask_user_questions during pending gate', () => { + clearDiscussionFlowState(); + setPendingGate('depth_verification'); + + // ask_user_questions is always safe (model needs to re-ask) + assert.strictEqual(shouldBlockPendingGate('ask_user_questions', 'M001').block, false); + // read-only tools are safe + assert.strictEqual(shouldBlockPendingGate('read', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGate('grep', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGate('glob', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGate('ls', 'M001').block, false); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 23: shouldBlockPendingGate still blocks when the session is ambiguous ── + +test('write-gate: shouldBlockPendingGate blocks outside discussion when a gate is pending', () => { + clearDiscussionFlowState(); + setPendingGate('depth_verification'); + + // No milestoneId and no queue phase — still block because the gate is pending + const result = shouldBlockPendingGate('write', null, false); + assert.strictEqual(result.block, true, 'should block even when milestoneId is null'); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 24: shouldBlockPendingGate blocks in queue mode ── + +test('write-gate: shouldBlockPendingGate blocks in queue mode when gate is pending', () => { + clearDiscussionFlowState(); + setQueuePhaseActive(true); + setPendingGate('depth_verification'); + + const result = shouldBlockPendingGate('write', null, true); + assert.strictEqual(result.block, true, 'should block in queue mode'); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 25: shouldBlockPendingGateBash allows read-only commands ── + +test('write-gate: shouldBlockPendingGateBash allows read-only commands during pending gate', () => { + clearDiscussionFlowState(); + setPendingGate('depth_verification'); + + assert.strictEqual(shouldBlockPendingGateBash('cat file.txt', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGateBash('git log --oneline', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGateBash('grep -r pattern .', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGateBash('ls -la', 'M001').block, false); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 26: shouldBlockPendingGateBash blocks mutating commands ── + +test('write-gate: shouldBlockPendingGateBash blocks mutating commands during pending gate', () => { + clearDiscussionFlowState(); + setPendingGate('depth_verification'); + + const result = shouldBlockPendingGateBash('npm run build', 'M001'); + assert.strictEqual(result.block, true, 'mutating bash should be blocked'); + assert.ok(result.reason!.includes('depth_verification')); + + clearDiscussionFlowState(); +}); + +// ─── Scenario 27: no pending gate means no blocking ── + +test('write-gate: no pending gate means no blocking', () => { + clearDiscussionFlowState(); + + assert.strictEqual(shouldBlockPendingGate('write', 'M001').block, false); + assert.strictEqual(shouldBlockPendingGateBash('npm run build', 'M001').block, false); +}); + +// ─── Scenario 28: resetWriteGateState clears pending gate ── + +test('write-gate: resetWriteGateState clears pending gate', () => { + setPendingGate('depth_verification'); + resetWriteGateState(); + assert.strictEqual(getPendingGate(), null); +}); + +// ─── Standard options fixture used across depth confirmation tests ── + +const STANDARD_OPTIONS = [ + { label: 'Yes, you got it (Recommended)' }, + { label: 'Not quite — let me clarify' }, +]; + +// ─── Scenario 11: accepts first option (confirmation) with structural validation ── + +test('write-gate: isDepthConfirmationAnswer accepts first option with options present', () => { + assert.strictEqual( + isDepthConfirmationAnswer('Yes, you got it (Recommended)', STANDARD_OPTIONS), + true, + 'should accept exact match of first option label', + ); +}); + +// ─── Scenario 12: rejects second option (decline) ── + +test('write-gate: isDepthConfirmationAnswer rejects decline option', () => { + assert.strictEqual( + isDepthConfirmationAnswer('Not quite — let me clarify', STANDARD_OPTIONS), + false, + 'should reject the clarification option', + ); +}); + +// ─── Scenario 13: rejects "None of the above" ── + +test('write-gate: isDepthConfirmationAnswer rejects None of the above', () => { + assert.strictEqual( + isDepthConfirmationAnswer('None of the above', STANDARD_OPTIONS), + false, + 'should reject None of the above', + ); +}); + +// ─── Scenario 14: rejects garbage/empty input ── + +test('write-gate: isDepthConfirmationAnswer rejects garbage and edge cases', () => { + assert.strictEqual(isDepthConfirmationAnswer('discord', STANDARD_OPTIONS), false, 'garbage string'); + assert.strictEqual(isDepthConfirmationAnswer('', STANDARD_OPTIONS), false, 'empty string'); + assert.strictEqual(isDepthConfirmationAnswer(undefined, STANDARD_OPTIONS), false, 'undefined'); + assert.strictEqual(isDepthConfirmationAnswer(null, STANDARD_OPTIONS), false, 'null'); + assert.strictEqual(isDepthConfirmationAnswer(42, STANDARD_OPTIONS), false, 'number'); +}); + +// ─── Scenario 15: handles array-wrapped selection ── + +test('write-gate: isDepthConfirmationAnswer handles array-wrapped selected value', () => { + assert.strictEqual( + isDepthConfirmationAnswer(['Yes, you got it (Recommended)'], STANDARD_OPTIONS), + true, + 'should accept array-wrapped confirmation', + ); + assert.strictEqual( + isDepthConfirmationAnswer(['Not quite — let me clarify'], STANDARD_OPTIONS), + false, + 'should reject array-wrapped decline', + ); + assert.strictEqual( + isDepthConfirmationAnswer([], STANDARD_OPTIONS), + false, + 'should reject empty array', + ); +}); + +// ─── Scenario 16: rejects free-form "Other" text that contains "(Recommended)" ── + +test('write-gate: isDepthConfirmationAnswer rejects free-form text containing Recommended', () => { + assert.strictEqual( + isDepthConfirmationAnswer('I think this is fine (Recommended)', STANDARD_OPTIONS), + false, + 'free-form text with (Recommended) substring must not unlock gate', + ); + assert.strictEqual( + isDepthConfirmationAnswer('(Recommended)', STANDARD_OPTIONS), + false, + 'bare (Recommended) string must not unlock gate', + ); +}); + +// ─── Scenario 17: works with changed label text (decoupled from specific copy) ── + +test('write-gate: isDepthConfirmationAnswer works with different label text', () => { + const customOptions = [ + { label: 'Looks good, proceed' }, + { label: 'Needs more discussion' }, + ]; + assert.strictEqual( + isDepthConfirmationAnswer('Looks good, proceed', customOptions), + true, + 'should accept first option regardless of label text', + ); + assert.strictEqual( + isDepthConfirmationAnswer('Needs more discussion', customOptions), + false, + 'should reject second option', + ); + // Old label should NOT work with new options + assert.strictEqual( + isDepthConfirmationAnswer('Yes, you got it (Recommended)', customOptions), + false, + 'old label text should not match new options', + ); +}); + +// ─── Scenario 18: fallback when options not available ── + +test('write-gate: isDepthConfirmationAnswer falls back to (Recommended) match without options', () => { + assert.strictEqual( + isDepthConfirmationAnswer('Yes, you got it (Recommended)'), + true, + 'should accept via fallback when no options provided', + ); + assert.strictEqual( + isDepthConfirmationAnswer('Not quite — let me clarify'), + false, + 'should reject non-Recommended via fallback', + ); +}); diff --git a/src/resources/extensions/gsd/tests/zero-slice-roadmap-guided.test.ts b/src/resources/extensions/gsd/tests/zero-slice-roadmap-guided.test.ts new file mode 100644 index 000000000..f41b8bd51 --- /dev/null +++ b/src/resources/extensions/gsd/tests/zero-slice-roadmap-guided.test.ts @@ -0,0 +1,19 @@ +/** + * Regression test for #3441: guided flow must treat a roadmap with zero + * parseable slices the same as no roadmap — offer "Create roadmap" not "Go auto". + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +test("guided-flow checks roadmap slice count before offering auto (#3441)", () => { + const src = readFileSync( + join(import.meta.dirname, "..", "guided-flow.ts"), + "utf-8", + ); + assert.ok( + src.includes("roadmapHasSlices") || src.includes("parseRoadmapSlices"), + "Guided flow must parse roadmap for slices before deciding which options to show", + ); +}); diff --git a/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts b/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts new file mode 100644 index 000000000..d18a7fcf8 --- /dev/null +++ b/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts @@ -0,0 +1,95 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +import { createTestContext } from "./test-helpers.ts"; + +const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext(); + +// ─── #2942: Zombie .gsd state skips init wizard ───────────────────────────── +// +// A partially initialized .gsd/ (symlink exists but no PREFERENCES.md or +// milestones/) causes the init wizard gate in showSmartEntry to be skipped, +// resulting in an uninitialized project session. + +console.log("\n=== #2942: zombie .gsd state must not skip init wizard ==="); + +// ── guided-flow.ts — init wizard gate must check bootstrap completeness ── + +const guidedFlowSrc = readFileSync( + join(import.meta.dirname, "..", "guided-flow.ts"), + "utf-8", +); + +// Find the showSmartEntry function +const smartEntryIdx = guidedFlowSrc.indexOf("export async function showSmartEntry("); +assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry"); + +// Extract the region between showSmartEntry and the first showProjectInit call +// This is where the init wizard gate lives. +const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : ""; + +// The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check. +// It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist. +assertTrue( + afterSmartEntry.includes("PREFERENCES.md") || afterSmartEntry.includes("PREFERENCES"), + "init wizard gate checks for PREFERENCES.md, not just .gsd/ existence (#2942)", +); + +assertTrue( + afterSmartEntry.includes("milestones"), + "init wizard gate checks for milestones/ directory, not just .gsd/ existence (#2942)", +); + +// The init wizard should be shown when .gsd/ exists but has no bootstrap artifacts. +// The old code was: if (!existsSync(gsdRoot(basePath))) { ... showProjectInit ... } +// The fix should use a compound check so zombie states trigger the wizard. +// Verify we no longer have the bare existence check as the sole gate. + +// Find the specific init wizard gate pattern — the detection preamble block. +const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble"); +const detectionRegion = detectionPreambleIdx >= 0 + ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600) + : afterSmartEntry.slice(0, 1500); + +// The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts) +assertMatch( + detectionRegion, + /PREFERENCES\.md|milestones/, + "detection preamble gate references bootstrap artifacts, not just directory existence (#2942)", +); + +// ── auto-start.ts — milestones/ dir creation must not be dead code ────────── + +console.log("\n=== #2942: auto-start milestones/ bootstrap not dead code ==="); + +const autoStartSrc = readFileSync( + join(import.meta.dirname, "..", "auto-start.ts"), + "utf-8", +); + +// After ensureGsdSymlink, the code that creates milestones/ must check for +// the milestones directory specifically (not .gsd/ which ensureGsdSymlink already created). +const symlinkIdx = autoStartSrc.indexOf("ensureGsdSymlink(base)"); +assertTrue(symlinkIdx >= 0, "auto-start.ts calls ensureGsdSymlink(base)"); + +const afterSymlink = symlinkIdx >= 0 ? autoStartSrc.slice(symlinkIdx, symlinkIdx + 800) : ""; + +// The milestones bootstrap must check milestones path, not gsdDir +// Old (dead) code: if (!existsSync(gsdDir)) { mkdirSync(join(gsdDir, "milestones"), ...) } +// Fixed code should check: if (!existsSync(milestonesPath)) or similar +assertTrue( + afterSymlink.includes("milestones") && afterSymlink.includes("mkdirSync"), + "auto-start.ts creates milestones/ directory after ensureGsdSymlink (#2942)", +); + +// The guard for milestones/ creation should NOT be `!existsSync(gsdDir)` — +// that's dead code since ensureGsdSymlink already created gsdDir. +// It should check for the milestones/ dir directly. +const mkdirRegion = afterSymlink.slice(0, afterSymlink.indexOf("mkdirSync") + 200); +assertMatch( + mkdirRegion, + /existsSync\([^)]*milestones/, + "milestones bootstrap checks milestones path existence, not .gsd/ (#2942)", +); + +report(); diff --git a/src/resources/extensions/gsd/tools/complete-milestone.ts b/src/resources/extensions/gsd/tools/complete-milestone.ts index 939e07883..f20bb69f5 100644 --- a/src/resources/extensions/gsd/tools/complete-milestone.ts +++ b/src/resources/extensions/gsd/tools/complete-milestone.ts @@ -20,24 +20,33 @@ import { resolveMilestonePath, clearPathCache } from "../paths.js"; import { isClosedStatus } from "../status-guards.js"; import { saveFile, clearParseCache } from "../files.js"; import { invalidateStateCache } from "../state.js"; -import { renderAllProjections } from "../workflow-projections.js"; +import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning, logError } from "../workflow-logger.js"; export interface CompleteMilestoneParams { milestoneId: string; title: string; oneLiner: string; narrative: string; - successCriteriaResults: string; - definitionOfDoneResults: string; - requirementOutcomes: string; - keyDecisions: string[]; - keyFiles: string[]; - lessonsLearned: string[]; - followUps: string; - deviations: string; verificationPassed: boolean; + /** @optional — defaults to "Not provided." when omitted by models with limited tool-calling */ + successCriteriaResults?: string; + /** @optional — defaults to "Not provided." when omitted */ + definitionOfDoneResults?: string; + /** @optional — defaults to "Not provided." when omitted */ + requirementOutcomes?: string; + /** @optional — defaults to [] when omitted */ + keyDecisions?: string[]; + /** @optional — defaults to [] when omitted */ + keyFiles?: string[]; + /** @optional — defaults to [] when omitted */ + lessonsLearned?: string[]; + /** @optional — defaults to "None." when omitted */ + followUps?: string; + /** @optional — defaults to "None." when omitted */ + deviations?: string; /** Optional caller-provided identity for audit trail */ actorName?: string; /** Optional caller-provided reason this action was triggered */ @@ -51,22 +60,28 @@ export interface CompleteMilestoneResult { function renderMilestoneSummaryMarkdown(params: CompleteMilestoneParams): string { const now = new Date().toISOString(); + const displayTitle = stripIdPrefix(params.title, params.milestoneId); - const keyDecisionsYaml = params.keyDecisions.length > 0 - ? params.keyDecisions.map(d => ` - ${d}`).join("\n") + // Apply defaults for optional enrichment fields (#2771) + const keyDecisions = params.keyDecisions ?? []; + const keyFiles = params.keyFiles ?? []; + const lessonsLearned = params.lessonsLearned ?? []; + + const keyDecisionsYaml = keyDecisions.length > 0 + ? keyDecisions.map(d => ` - ${d}`).join("\n") : " - (none)"; - const keyFilesYaml = params.keyFiles.length > 0 - ? params.keyFiles.map(f => ` - ${f}`).join("\n") + const keyFilesYaml = keyFiles.length > 0 + ? keyFiles.map(f => ` - ${f}`).join("\n") : " - (none)"; - const lessonsYaml = params.lessonsLearned.length > 0 - ? params.lessonsLearned.map(l => ` - ${l}`).join("\n") + const lessonsYaml = lessonsLearned.length > 0 + ? lessonsLearned.map(l => ` - ${l}`).join("\n") : " - (none)"; return `--- id: ${params.milestoneId} -title: "${params.title}" +title: "${displayTitle}" status: complete completed_at: ${now} key_decisions: @@ -77,7 +92,7 @@ lessons_learned: ${lessonsYaml} --- -# ${params.milestoneId}: ${params.title} +# ${params.milestoneId}: ${displayTitle} **${params.oneLiner}** @@ -87,15 +102,15 @@ ${params.narrative} ## Success Criteria Results -${params.successCriteriaResults} +${params.successCriteriaResults ?? "Not provided."} ## Definition of Done Results -${params.definitionOfDoneResults} +${params.definitionOfDoneResults ?? "Not provided."} ## Requirement Outcomes -${params.requirementOutcomes} +${params.requirementOutcomes ?? "Not provided."} ## Deviations @@ -191,9 +206,7 @@ export async function handleCompleteMilestone( await saveFile(summaryPath, summaryMd); } catch (renderErr) { // Disk render failed — roll back DB status so state stays consistent - process.stderr.write( - `gsd-db: complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`, - ); + logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`); updateMilestoneStatus(params.milestoneId, 'active', null); invalidateStateCache(); return { error: `disk render failed: ${(renderErr as Error).message}` }; @@ -205,9 +218,19 @@ export async function handleCompleteMilestone( clearParseCache(); // ── Post-mutation hook: projections, manifest, event log ─────────────── + // Separate try/catch per step so a projection failure doesn't prevent + // the event log entry (critical for worktree reconciliation). try { await renderAllProjections(basePath, params.milestoneId); + } catch (projErr) { + logWarning("tool", `complete-milestone projection warning: ${(projErr as Error).message}`); + } + try { writeManifest(basePath); + } catch (mfErr) { + logWarning("tool", `complete-milestone manifest warning: ${(mfErr as Error).message}`); + } + try { appendEvent(basePath, { cmd: "complete-milestone", params: { milestoneId: params.milestoneId }, @@ -216,10 +239,8 @@ export async function handleCompleteMilestone( actor_name: params.actorName, trigger_reason: params.triggerReason, }); - } catch (hookErr) { - process.stderr.write( - `gsd: complete-milestone post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + } catch (eventErr) { + logError("tool", `complete-milestone event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message }); } return { diff --git a/src/resources/extensions/gsd/tools/complete-slice.ts b/src/resources/extensions/gsd/tools/complete-slice.ts index 759513319..5863a586f 100644 --- a/src/resources/extensions/gsd/tools/complete-slice.ts +++ b/src/resources/extensions/gsd/tools/complete-slice.ts @@ -30,6 +30,7 @@ import { renderRoadmapCheckboxes } from "../markdown-renderer.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning, logError } from "../workflow-logger.js"; export interface CompleteSliceResult { sliceId: string; @@ -45,58 +46,73 @@ export interface CompleteSliceResult { function renderSliceSummaryMarkdown(params: CompleteSliceParams): string { const now = new Date().toISOString(); - const providesYaml = params.provides.length > 0 - ? params.provides.map(p => ` - ${p}`).join("\n") + // Apply defaults for optional enrichment arrays (#2771) + const provides = params.provides ?? []; + const requires = params.requires ?? []; + const affects = params.affects ?? []; + const keyFiles = params.keyFiles ?? []; + const keyDecisions = params.keyDecisions ?? []; + const patternsEstablished = params.patternsEstablished ?? []; + const observabilitySurfaces = params.observabilitySurfaces ?? []; + const drillDownPaths = params.drillDownPaths ?? []; + const requirementsAdvanced = params.requirementsAdvanced ?? []; + const requirementsValidated = params.requirementsValidated ?? []; + const requirementsSurfaced = params.requirementsSurfaced ?? []; + const requirementsInvalidated = params.requirementsInvalidated ?? []; + const filesModified = params.filesModified ?? []; + + const providesYaml = provides.length > 0 + ? provides.map(p => ` - ${p}`).join("\n") : " - (none)"; - const requiresYaml = params.requires.length > 0 - ? params.requires.map(r => ` - slice: ${r.slice}\n provides: ${r.provides}`).join("\n") + const requiresYaml = requires.length > 0 + ? requires.map(r => ` - slice: ${r.slice}\n provides: ${r.provides}`).join("\n") : " []"; - const affectsYaml = params.affects.length > 0 - ? params.affects.map(a => ` - ${a}`).join("\n") + const affectsYaml = affects.length > 0 + ? affects.map(a => ` - ${a}`).join("\n") : " []"; - const keyFilesYaml = params.keyFiles.length > 0 - ? params.keyFiles.map(f => ` - ${f}`).join("\n") + const keyFilesYaml = keyFiles.length > 0 + ? keyFiles.map(f => ` - ${f}`).join("\n") : " - (none)"; - const keyDecisionsYaml = params.keyDecisions.length > 0 - ? params.keyDecisions.map(d => ` - ${d}`).join("\n") + const keyDecisionsYaml = keyDecisions.length > 0 + ? keyDecisions.map(d => ` - ${d}`).join("\n") : " - (none)"; - const patternsYaml = params.patternsEstablished.length > 0 - ? params.patternsEstablished.map(p => ` - ${p}`).join("\n") + const patternsYaml = patternsEstablished.length > 0 + ? patternsEstablished.map(p => ` - ${p}`).join("\n") : " - (none)"; - const observabilityYaml = params.observabilitySurfaces.length > 0 - ? params.observabilitySurfaces.map(o => ` - ${o}`).join("\n") + const observabilityYaml = observabilitySurfaces.length > 0 + ? observabilitySurfaces.map(o => ` - ${o}`).join("\n") : " - none"; - const drillDownYaml = params.drillDownPaths.length > 0 - ? params.drillDownPaths.map(d => ` - ${d}`).join("\n") + const drillDownYaml = drillDownPaths.length > 0 + ? drillDownPaths.map(d => ` - ${d}`).join("\n") : " []"; // Requirements sections - const reqAdvanced = params.requirementsAdvanced.length > 0 - ? params.requirementsAdvanced.map(r => `- ${r.id} — ${r.how}`).join("\n") + const reqAdvanced = requirementsAdvanced.length > 0 + ? requirementsAdvanced.map(r => `- ${r.id} — ${r.how}`).join("\n") : "None."; - const reqValidated = params.requirementsValidated.length > 0 - ? params.requirementsValidated.map(r => `- ${r.id} — ${r.proof}`).join("\n") + const reqValidated = requirementsValidated.length > 0 + ? requirementsValidated.map(r => `- ${r.id} — ${r.proof}`).join("\n") : "None."; - const reqSurfaced = params.requirementsSurfaced.length > 0 - ? params.requirementsSurfaced.map(r => `- ${r}`).join("\n") + const reqSurfaced = requirementsSurfaced.length > 0 + ? requirementsSurfaced.map(r => `- ${r}`).join("\n") : "None."; - const reqInvalidated = params.requirementsInvalidated.length > 0 - ? params.requirementsInvalidated.map(r => `- ${r.id} — ${r.what}`).join("\n") + const reqInvalidated = requirementsInvalidated.length > 0 + ? requirementsInvalidated.map(r => `- ${r.id} — ${r.what}`).join("\n") : "None."; // Files modified - const filesMod = params.filesModified.length > 0 - ? params.filesModified.map(f => `- \`${f.path}\` — ${f.description}`).join("\n") + const filesMod = filesModified.length > 0 + ? filesModified.map(f => `- \`${f.path}\` — ${f.description}`).join("\n") : "None."; return `--- @@ -217,8 +233,18 @@ export async function handleCompleteSlice( return { error: ownershipErr }; } + // ── Verification content gate (#3580) ────────────────────────────────── + // Reject completion when the provided verification/UAT clearly indicates + // the slice is blocked or failed. Prevents prompt regressions from + // silently advancing blocked slices. + const BLOCKED_SIGNALS = /\b(status:\s*blocked|verification_result:\s*failed|slice is blocked|cannot complete|verification failed)\b/i; + if (BLOCKED_SIGNALS.test(params.verification || "") || BLOCKED_SIGNALS.test(params.uatContent || "")) { + return { error: `slice verification indicates blocked/failed state — do not complete a slice that has not passed verification. Address the blockers and re-verify first.` }; + } + // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ─── const completedAt = new Date().toISOString(); + const originalSliceStatus = getSlice(params.milestoneId, params.sliceId)?.status ?? "pending"; let guardError: string | null = null; transaction(() => { @@ -252,8 +278,8 @@ export async function handleCompleteSlice( } // All guards passed — perform writes - insertMilestone({ id: params.milestoneId }); - insertSlice({ id: params.sliceId, milestoneId: params.milestoneId }); + insertMilestone({ id: params.milestoneId, title: params.milestoneId }); + insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId }); updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt); }); @@ -291,16 +317,12 @@ export async function handleCompleteSlice( // Toggle roadmap checkbox via renderer module const roadmapToggled = await renderRoadmapCheckboxes(basePath, params.milestoneId); if (!roadmapToggled) { - process.stderr.write( - `gsd-db: complete_slice — could not find roadmap for ${params.milestoneId}, skipping checkbox toggle\n`, - ); + logWarning("tool", `complete_slice — could not find roadmap for ${params.milestoneId}, skipping checkbox toggle`); } } catch (renderErr) { // Disk render failed — roll back DB status so state stays consistent - process.stderr.write( - `gsd-db: complete_slice — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`, - ); - updateSliceStatus(params.milestoneId, params.sliceId, 'pending'); + logWarning("tool", `complete_slice — disk render failed for ${params.milestoneId}/${params.sliceId}, rolling back DB status`, { error: (renderErr as Error).message }); + updateSliceStatus(params.milestoneId, params.sliceId, originalSliceStatus); invalidateStateCache(); return { error: `disk render failed: ${(renderErr as Error).message}` }; } @@ -314,9 +336,19 @@ export async function handleCompleteSlice( clearParseCache(); // ── Post-mutation hook: projections, manifest, event log ─────────────── + // Separate try/catch per step so a projection failure doesn't prevent + // the event log entry (critical for worktree reconciliation). try { await renderAllProjections(basePath, params.milestoneId); + } catch (projErr) { + logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`); + } + try { writeManifest(basePath); + } catch (mfErr) { + logWarning("tool", `complete-slice manifest warning: ${(mfErr as Error).message}`); + } + try { appendEvent(basePath, { cmd: "complete-slice", params: { milestoneId: params.milestoneId, sliceId: params.sliceId }, @@ -325,10 +357,8 @@ export async function handleCompleteSlice( actor_name: params.actorName, trigger_reason: params.triggerReason, }); - } catch (hookErr) { - process.stderr.write( - `gsd: complete-slice post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + } catch (eventErr) { + logError("tool", `complete-slice event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message }); } return { diff --git a/src/resources/extensions/gsd/tools/complete-task.ts b/src/resources/extensions/gsd/tools/complete-task.ts index d7805b20d..00cfa78d8 100644 --- a/src/resources/extensions/gsd/tools/complete-task.ts +++ b/src/resources/extensions/gsd/tools/complete-task.ts @@ -30,9 +30,10 @@ import { checkOwnership, taskUnitKey } from "../unit-ownership.js"; import { saveFile, clearParseCache } from "../files.js"; import { invalidateStateCache } from "../state.js"; import { renderPlanCheckboxes } from "../markdown-renderer.js"; -import { renderAllProjections } from "../workflow-projections.js"; +import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning, logError } from "../workflow-logger.js"; export interface CompleteTaskResult { taskId: string; @@ -41,79 +42,52 @@ export interface CompleteTaskResult { summaryPath: string; } +import type { TaskRow } from "../gsd-db.js"; + /** - * Render task summary markdown matching the template format. - * YAML frontmatter uses snake_case keys for parseSummary() compatibility. + * Normalize a list parameter that may arrive as a string (newline-delimited + * bullet list from the LLM) into a string array (#3361). */ -function renderSummaryMarkdown(params: CompleteTaskParams): string { - const now = new Date().toISOString(); - const keyFilesYaml = params.keyFiles.length > 0 - ? params.keyFiles.map(f => ` - ${f}`).join("\n") - : " - (none)"; - const keyDecisionsYaml = params.keyDecisions.length > 0 - ? params.keyDecisions.map(d => ` - ${d}`).join("\n") - : " - (none)"; - - // Build verification evidence table rows - let evidenceTable = "| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n"; - if (params.verificationEvidence.length > 0) { - params.verificationEvidence.forEach((e, i) => { - evidenceTable += `| ${i + 1} | \`${e.command}\` | ${e.exitCode} | ${e.verdict} | ${e.durationMs}ms |\n`; - }); - } else { - evidenceTable += "| — | No verification commands discovered | — | — | — |\n"; +function normalizeListParam(value: unknown): string[] { + if (Array.isArray(value)) return value.map(String); + if (typeof value === "string" && value.trim()) { + return value.split(/\n/).map(s => s.replace(/^[\s\-*•]+/, "").trim()).filter(Boolean); } + return []; +} - // Determine verification_result from evidence - const allPassed = params.verificationEvidence.length > 0 && - params.verificationEvidence.every(e => e.exitCode === 0 || e.verdict.includes("✅") || e.verdict.toLowerCase().includes("pass")); - const verificationResult = allPassed ? "passed" : (params.verificationEvidence.length === 0 ? "untested" : "mixed"); - - // Extract a title from the oneLiner or taskId - const title = params.oneLiner || params.taskId; - - return `--- -id: ${params.taskId} -parent: ${params.sliceId} -milestone: ${params.milestoneId} -key_files: -${keyFilesYaml} -key_decisions: -${keyDecisionsYaml} -duration: "" -verification_result: ${verificationResult} -completed_at: ${now} -blocker_discovered: ${params.blockerDiscovered} ---- - -# ${params.taskId}: ${title} - -**${params.oneLiner}** - -## What Happened - -${params.narrative} - -## Verification - -${params.verification} - -## Verification Evidence - -${evidenceTable} - -## Deviations - -${params.deviations || "None."} - -## Known Issues - -${params.knownIssues || "None."} - -## Files Created/Modified - -${params.keyFiles.map(f => `- \`${f}\``).join("\n") || "None."} -`; +/** + * Build a TaskRow-shaped object from CompleteTaskParams so the unified + * renderSummaryContent() can be used at completion time (#2720). + */ +function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskRow { + return { + milestone_id: params.milestoneId, + slice_id: params.sliceId, + id: params.taskId, + title: params.oneLiner || params.taskId, + status: "complete", + one_liner: params.oneLiner, + narrative: params.narrative, + verification_result: params.verification, + duration: "", + completed_at: completedAt, + blocker_discovered: params.blockerDiscovered ?? false, + deviations: params.deviations ?? "", + known_issues: params.knownIssues ?? "", + key_files: normalizeListParam(params.keyFiles), + key_decisions: normalizeListParam(params.keyDecisions), + full_summary_md: "", + description: "", + estimate: "", + files: [], + verify: "", + inputs: [], + expected_output: [], + observability_impact: "", + full_plan_md: "", + sequence: 0, + }; } /** @@ -178,8 +152,8 @@ export async function handleCompleteTask( } // All guards passed — perform writes - insertMilestone({ id: params.milestoneId }); - insertSlice({ id: params.sliceId, milestoneId: params.milestoneId }); + insertMilestone({ id: params.milestoneId, title: params.milestoneId }); + insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceId }); insertTask({ id: params.taskId, sliceId: params.sliceId, @@ -190,14 +164,14 @@ export async function handleCompleteTask( narrative: params.narrative, verificationResult: params.verification, duration: "", - blockerDiscovered: params.blockerDiscovered, - deviations: params.deviations, - knownIssues: params.knownIssues, - keyFiles: params.keyFiles, - keyDecisions: params.keyDecisions, + blockerDiscovered: params.blockerDiscovered ?? false, + deviations: params.deviations ?? "None.", + knownIssues: params.knownIssues ?? "None.", + keyFiles: params.keyFiles ?? [], + keyDecisions: params.keyDecisions ?? [], }); - for (const evidence of params.verificationEvidence) { + for (const evidence of (params.verificationEvidence ?? [])) { insertVerificationEvidence({ taskId: params.taskId, sliceId: params.sliceId, @@ -218,8 +192,9 @@ export async function handleCompleteTask( // If disk render fails, roll back the DB status so deriveState() and // verifyExpectedArtifact() stay consistent (both say "not done"). - // Render summary markdown - const summaryMd = renderSummaryMarkdown(params); + // Render summary markdown via the single source of truth (#2720) + const taskRow = paramsToTaskRow(params, completedAt); + const summaryMd = renderSummaryContent(taskRow, params.sliceId, params.milestoneId, params.verificationEvidence ?? []); // Resolve and write summary to disk let summaryPath: string; @@ -248,9 +223,7 @@ export async function handleCompleteTask( } } catch (renderErr) { // Disk render failed — roll back DB status so state stays consistent - process.stderr.write( - `gsd-db: complete_task — disk render failed, rolling back DB status: ${(renderErr as Error).message}\n`, - ); + logWarning("tool", `complete_task — disk render failed, rolling back DB status: ${(renderErr as Error).message}`); // Delete orphaned verification_evidence rows first (FK constraint // references tasks, so evidence must go before status change). // Without this, retries accumulate duplicate evidence rows (#2724). @@ -269,9 +242,19 @@ export async function handleCompleteTask( clearParseCache(); // ── Post-mutation hook: projections, manifest, event log ─────────────── + // Separate try/catch per step so a projection failure doesn't prevent + // the event log entry (critical for worktree reconciliation). try { await renderAllProjections(basePath, params.milestoneId); + } catch (projErr) { + logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`); + } + try { writeManifest(basePath); + } catch (mfErr) { + logWarning("tool", `complete-task manifest warning: ${(mfErr as Error).message}`); + } + try { appendEvent(basePath, { cmd: "complete-task", params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId }, @@ -280,10 +263,8 @@ export async function handleCompleteTask( actor_name: params.actorName, trigger_reason: params.triggerReason, }); - } catch (hookErr) { - process.stderr.write( - `gsd: complete-task post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + } catch (eventErr) { + logError("tool", `complete-task event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message }); } return { diff --git a/src/resources/extensions/gsd/tools/plan-milestone.ts b/src/resources/extensions/gsd/tools/plan-milestone.ts index 6a09d4163..cc24aeb2a 100644 --- a/src/resources/extensions/gsd/tools/plan-milestone.ts +++ b/src/resources/extensions/gsd/tools/plan-milestone.ts @@ -4,6 +4,8 @@ import { isNonEmptyString, validateStringArray } from "../validation.js"; import { transaction, getMilestone, + getMilestoneSlices, + getSlice, insertMilestone, insertSlice, upsertMilestonePlanning, @@ -14,6 +16,7 @@ import { renderRoadmapFromDb } from "../markdown-renderer.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; export interface PlanMilestoneSliceInput { sliceId: string; @@ -31,24 +34,34 @@ export interface PlanMilestoneSliceInput { export interface PlanMilestoneParams { milestoneId: string; title: string; + vision: string; + slices: PlanMilestoneSliceInput[]; status?: string; dependsOn?: string[]; /** Optional caller-provided identity for audit trail */ actorName?: string; /** Optional caller-provided reason this action was triggered */ triggerReason?: string; - vision: string; - successCriteria: string[]; - keyRisks: Array<{ risk: string; whyItMatters: string }>; - proofStrategy: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>; - verificationContract: string; - verificationIntegration: string; - verificationOperational: string; - verificationUat: string; - definitionOfDone: string[]; - requirementCoverage: string; - boundaryMapMarkdown: string; - slices: PlanMilestoneSliceInput[]; + /** @optional — defaults to [] when omitted by models with limited tool-calling */ + successCriteria?: string[]; + /** @optional — defaults to [] when omitted */ + keyRisks?: Array<{ risk: string; whyItMatters: string }>; + /** @optional — defaults to [] when omitted */ + proofStrategy?: Array<{ riskOrUnknown: string; retireIn: string; whatWillBeProven: string }>; + /** @optional — defaults to "" when omitted */ + verificationContract?: string; + /** @optional — defaults to "" when omitted */ + verificationIntegration?: string; + /** @optional — defaults to "" when omitted */ + verificationOperational?: string; + /** @optional — defaults to "" when omitted */ + verificationUat?: string; + /** @optional — defaults to [] when omitted */ + definitionOfDone?: string[]; + /** @optional — defaults to "Not provided." when omitted */ + requirementCoverage?: string; + /** @optional — defaults to "Not provided." when omitted */ + boundaryMapMarkdown?: string; } export interface PlanMilestoneResult { @@ -147,20 +160,21 @@ function validateParams(params: PlanMilestoneParams): PlanMilestoneParams { if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required"); if (!isNonEmptyString(params?.title)) throw new Error("title is required"); if (!isNonEmptyString(params?.vision)) throw new Error("vision is required"); - if (!isNonEmptyString(params?.verificationContract)) throw new Error("verificationContract is required"); - if (!isNonEmptyString(params?.verificationIntegration)) throw new Error("verificationIntegration is required"); - if (!isNonEmptyString(params?.verificationOperational)) throw new Error("verificationOperational is required"); - if (!isNonEmptyString(params?.verificationUat)) throw new Error("verificationUat is required"); - if (!isNonEmptyString(params?.requirementCoverage)) throw new Error("requirementCoverage is required"); - if (!isNonEmptyString(params?.boundaryMapMarkdown)) throw new Error("boundaryMapMarkdown is required"); return { ...params, dependsOn: params.dependsOn ? validateStringArray(params.dependsOn, "dependsOn") : [], - successCriteria: validateStringArray(params.successCriteria, "successCriteria"), - keyRisks: validateRiskEntries(params.keyRisks), - proofStrategy: validateProofStrategy(params.proofStrategy), - definitionOfDone: validateStringArray(params.definitionOfDone, "definitionOfDone"), + // Apply defaults for optional enrichment fields (#2771) + successCriteria: params.successCriteria ? validateStringArray(params.successCriteria, "successCriteria") : [], + keyRisks: params.keyRisks ? validateRiskEntries(params.keyRisks) : [], + proofStrategy: params.proofStrategy ? validateProofStrategy(params.proofStrategy) : [], + verificationContract: params.verificationContract ?? "", + verificationIntegration: params.verificationIntegration ?? "", + verificationOperational: params.verificationOperational ?? "", + verificationUat: params.verificationUat ?? "", + definitionOfDone: params.definitionOfDone ? validateStringArray(params.definitionOfDone, "definitionOfDone") : [], + requirementCoverage: params.requirementCoverage ?? "Not provided.", + boundaryMapMarkdown: params.boundaryMapMarkdown ?? "Not provided.", slices: validateSlices(params.slices), }; } @@ -189,6 +203,21 @@ export async function handlePlanMilestone( return; } + // Guard: refuse to re-plan a milestone that would drop completed slices (#2960). + // Allow re-planning when all completed slices are still present in the + // incoming plan — their status is preserved below (#2558). Block only when + // the new plan omits a completed slice, which could shadow completed work. + const existingSlices = getMilestoneSlices(params.milestoneId); + const completedSlices = existingSlices.filter(s => isClosedStatus(s.status)); + if (completedSlices.length > 0) { + const incomingSliceIds = new Set(params.slices.map(s => s.sliceId)); + const droppedCompleted = completedSlices.filter(s => !incomingSliceIds.has(s.id)); + if (droppedCompleted.length > 0) { + guardError = `cannot re-plan milestone ${params.milestoneId}: ${droppedCompleted.length} completed slice(s) would be dropped (${droppedCompleted.map(s => s.id).join(", ")}). Use gsd_reassess_roadmap to modify the roadmap.`; + return; + } + } + // Validate depends_on: all dependencies must exist and be complete if (params.dependsOn && params.dependsOn.length > 0) { for (const depId of params.dependsOn) { @@ -212,6 +241,8 @@ export async function handlePlanMilestone( }); upsertMilestonePlanning(params.milestoneId, { + title: params.title, + status: params.status ?? "active", vision: params.vision, successCriteria: params.successCriteria, keyRisks: params.keyRisks, @@ -225,15 +256,24 @@ export async function handlePlanMilestone( boundaryMapMarkdown: params.boundaryMapMarkdown, }); - for (const slice of params.slices) { + for (let i = 0; i < params.slices.length; i++) { + const slice = params.slices[i]!; + // Preserve completed/done status on re-plan (#2558). + // Without this, a re-plan after milestone transition would reset + // already-completed slices back to "pending". + const existing = getSlice(params.milestoneId, slice.sliceId); + const status = existing && (existing.status === "complete" || existing.status === "done") + ? existing.status + : "pending"; insertSlice({ id: slice.sliceId, milestoneId: params.milestoneId, title: slice.title, - status: "pending", + status, risk: slice.risk, depends: slice.depends, demo: slice.demo, + sequence: i + 1, // Preserve agent-ordered sequence (#3356) }); upsertSlicePlanning(params.milestoneId, slice.sliceId, { goal: slice.goal, @@ -257,9 +297,7 @@ export async function handlePlanMilestone( const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId); roadmapPath = renderResult.roadmapPath; } catch (renderErr) { - process.stderr.write( - `gsd-db: plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}\n`, - ); + logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`); invalidateStateCache(); return { error: `render failed: ${(renderErr as Error).message}` }; } @@ -280,9 +318,7 @@ export async function handlePlanMilestone( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: plan-milestone post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `plan-milestone post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/plan-slice.ts b/src/resources/extensions/gsd/tools/plan-slice.ts index fa345a975..8324bdc82 100644 --- a/src/resources/extensions/gsd/tools/plan-slice.ts +++ b/src/resources/extensions/gsd/tools/plan-slice.ts @@ -16,6 +16,7 @@ import { renderPlanFromDb } from "../markdown-renderer.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; export interface PlanSliceTaskInput { taskId: string; @@ -34,11 +35,15 @@ export interface PlanSliceParams { milestoneId: string; sliceId: string; goal: string; - successCriteria: string; - proofLevel: string; - integrationClosure: string; - observabilityImpact: string; tasks: PlanSliceTaskInput[]; + /** @optional — defaults to "Not provided." when omitted by models with limited tool-calling */ + successCriteria?: string; + /** @optional — defaults to "Not provided." when omitted */ + proofLevel?: string; + /** @optional — defaults to "Not provided." when omitted */ + integrationClosure?: string; + /** @optional — defaults to "Not provided." when omitted */ + observabilityImpact?: string; /** Optional caller-provided identity for audit trail */ actorName?: string; /** Optional caller-provided reason this action was triggered */ @@ -111,13 +116,14 @@ function validateParams(params: PlanSliceParams): PlanSliceParams { if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required"); if (!isNonEmptyString(params?.sliceId)) throw new Error("sliceId is required"); if (!isNonEmptyString(params?.goal)) throw new Error("goal is required"); - if (!isNonEmptyString(params?.successCriteria)) throw new Error("successCriteria is required"); - if (!isNonEmptyString(params?.proofLevel)) throw new Error("proofLevel is required"); - if (!isNonEmptyString(params?.integrationClosure)) throw new Error("integrationClosure is required"); - if (!isNonEmptyString(params?.observabilityImpact)) throw new Error("observabilityImpact is required"); return { ...params, + // Apply defaults for optional enrichment fields (#2771) + successCriteria: params.successCriteria ?? "Not provided.", + proofLevel: params.proofLevel ?? "Not provided.", + integrationClosure: params.integrationClosure ?? "Not provided.", + observabilityImpact: params.observabilityImpact ?? "Not provided.", tasks: validateTasks(params.tasks), }; } @@ -229,9 +235,7 @@ export async function handlePlanSlice( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: plan-slice post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `plan-slice post-mutation hook warning: ${(hookErr as Error).message}`); } return { @@ -241,9 +245,7 @@ export async function handlePlanSlice( taskPlanPaths: renderResult.taskPlanPaths, }; } catch (renderErr) { - process.stderr.write( - `gsd-db: plan_slice — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}\n`, - ); + logWarning("tool", `plan_slice — render failed (DB rows preserved for debugging): ${(renderErr as Error).message}`); invalidateStateCache(); return { error: `render failed: ${(renderErr as Error).message}` }; } diff --git a/src/resources/extensions/gsd/tools/plan-task.ts b/src/resources/extensions/gsd/tools/plan-task.ts index 57b91ae0a..329ab6cd4 100644 --- a/src/resources/extensions/gsd/tools/plan-task.ts +++ b/src/resources/extensions/gsd/tools/plan-task.ts @@ -7,6 +7,7 @@ import { renderTaskPlanFromDb } from "../markdown-renderer.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; export interface PlanTaskParams { milestoneId: string; @@ -135,9 +136,7 @@ export async function handlePlanTask( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: plan-task post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `plan-task post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/reassess-roadmap.ts b/src/resources/extensions/gsd/tools/reassess-roadmap.ts index 040aacf56..ab0f492fa 100644 --- a/src/resources/extensions/gsd/tools/reassess-roadmap.ts +++ b/src/resources/extensions/gsd/tools/reassess-roadmap.ts @@ -1,4 +1,5 @@ import { join } from "node:path"; +import { existsSync, unlinkSync } from "node:fs"; import { clearParseCache } from "../files.js"; import { isClosedStatus } from "../status-guards.js"; import { isNonEmptyString } from "../validation.js"; @@ -10,6 +11,7 @@ import { insertSlice, updateSliceFields, insertAssessment, + deleteAssessmentByScope, deleteSlice, } from "../gsd-db.js"; import { invalidateStateCache } from "../state.js"; @@ -17,6 +19,7 @@ import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-rendere import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; export interface SliceChangeInput { sliceId: string; @@ -183,8 +186,10 @@ export async function handleReassessRoadmap( }); } - // Insert new slices - for (const added of params.sliceChanges.added) { + // Insert new slices — assign sequence after existing slices (#3356) + const existingCount = getMilestoneSlices(params.milestoneId).length; + for (let i = 0; i < params.sliceChanges.added.length; i++) { + const added = params.sliceChanges.added[i]!; insertSlice({ id: added.sliceId, milestoneId: params.milestoneId, @@ -193,6 +198,7 @@ export async function handleReassessRoadmap( risk: added.risk, depends: added.depends, demo: added.demo ?? "", + sequence: existingCount + i + 1, }); } @@ -200,6 +206,21 @@ export async function handleReassessRoadmap( for (const removedId of params.sliceChanges.removed) { deleteSlice(params.milestoneId, removedId); } + + // ── Invalidate stale milestone validation (#2957) ────────────── + // When roadmap structure changes (slices added/modified/removed), + // any prior milestone-validation verdict is stale. Delete the DB + // row so deriveState() returns phase: 'validating-milestone' once + // the new slices complete, rather than advancing directly to + // 'completing-milestone' with a stale needs-remediation verdict. + const hasStructuralChanges = + params.sliceChanges.added.length > 0 || + params.sliceChanges.modified.length > 0 || + params.sliceChanges.removed.length > 0; + + if (hasStructuralChanges) { + deleteAssessmentByScope(params.milestoneId, "milestone-validation"); + } }); } catch (err) { return { error: `db write failed: ${(err as Error).message}` }; @@ -218,6 +239,24 @@ export async function handleReassessRoadmap( completedSliceId: params.completedSliceId, }); + // ── Remove stale VALIDATION file from disk (#2957) ──────────── + const hasStructuralChanges = + params.sliceChanges.added.length > 0 || + params.sliceChanges.modified.length > 0 || + params.sliceChanges.removed.length > 0; + + if (hasStructuralChanges) { + const validationFile = join( + basePath, ".gsd", "milestones", params.milestoneId, + `${params.milestoneId}-VALIDATION.md`, + ); + try { + if (existsSync(validationFile)) unlinkSync(validationFile); + } catch (e) { + logWarning("tool", `validation file cleanup failed: ${(e as Error).message}`); + } + } + // ── Invalidate caches ───────────────────────────────────────── invalidateStateCache(); clearParseCache(); @@ -235,9 +274,7 @@ export async function handleReassessRoadmap( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: reassess-roadmap post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `reassess-roadmap post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/reopen-milestone.ts b/src/resources/extensions/gsd/tools/reopen-milestone.ts new file mode 100644 index 000000000..d2e67ac3e --- /dev/null +++ b/src/resources/extensions/gsd/tools/reopen-milestone.ts @@ -0,0 +1,152 @@ +// GSD — reopen-milestone tool handler + +/** + * reopen-milestone handler — the core operation behind gsd_milestone_reopen. + * + * Resets a closed milestone back to "active", all of its slices to + * "in_progress", and all tasks to "pending". Cleans up stale filesystem + * artifacts so the DB-filesystem reconciler does not auto-correct + * entities back to "complete". + */ + +import { + getMilestone, + getMilestoneSlices, + getSliceTasks, + updateMilestoneStatus, + updateSliceStatus, + updateTaskStatus, + transaction, +} from "../gsd-db.js"; +import { invalidateStateCache } from "../state.js"; +import { isClosedStatus } from "../status-guards.js"; +import { renderAllProjections } from "../workflow-projections.js"; +import { writeManifest } from "../workflow-manifest.js"; +import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; +import { debugLog } from "../debug-logger.js"; +import { existsSync, unlinkSync } from "node:fs"; +import { join } from "node:path"; +import { resolveMilestonePath, resolveSlicePath, resolveTasksDir, clearPathCache } from "../paths.js"; + +export interface ReopenMilestoneParams { + milestoneId: string; + reason?: string; + /** Optional caller-provided identity for audit trail */ + actorName?: string; + /** Optional caller-provided reason this action was triggered */ + triggerReason?: string; +} + +export interface ReopenMilestoneResult { + milestoneId: string; + slicesReset: number; + tasksReset: number; +} + +export async function handleReopenMilestone( + params: ReopenMilestoneParams, + basePath: string, +): Promise { + // ── Validate required fields ──────────────────────────────────────────── + if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") { + return { error: "milestoneId is required and must be a non-empty string" }; + } + + // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ─── + let guardError: string | null = null; + let slicesResetCount = 0; + let tasksResetCount = 0; + + transaction(() => { + const milestone = getMilestone(params.milestoneId); + if (!milestone) { + guardError = `milestone not found: ${params.milestoneId}`; + return; + } + if (!isClosedStatus(milestone.status)) { + guardError = `milestone ${params.milestoneId} is not closed (status: ${milestone.status}) — nothing to reopen`; + return; + } + + updateMilestoneStatus(params.milestoneId, "active", null); + + const slices = getMilestoneSlices(params.milestoneId); + slicesResetCount = slices.length; + + for (const slice of slices) { + updateSliceStatus(params.milestoneId, slice.id, "in_progress"); + const tasks = getSliceTasks(params.milestoneId, slice.id); + tasksResetCount += tasks.length; + for (const task of tasks) { + updateTaskStatus(params.milestoneId, slice.id, task.id, "pending"); + } + } + }); + + if (guardError) { + return { error: guardError }; + } + + // ── Invalidate caches ──────────────────────────────────────────────────── + invalidateStateCache(); + + // ── Clean up stale filesystem artifacts (M12 fix) ──────────────────────── + // Without this, the DB-filesystem reconciler sees SUMMARY.md files and + // auto-corrects entities back to "complete", making reopen a no-op (#3161). + try { + const milestoneDir = resolveMilestonePath(basePath, params.milestoneId); + if (milestoneDir) { + const milestoneSummary = join(milestoneDir, `${params.milestoneId}-SUMMARY.md`); + if (existsSync(milestoneSummary)) unlinkSync(milestoneSummary); + } + + const slices = getMilestoneSlices(params.milestoneId); + for (const slice of slices) { + const sliceDir = resolveSlicePath(basePath, params.milestoneId, slice.id); + if (sliceDir) { + const sliceSummary = join(sliceDir, `${slice.id}-SUMMARY.md`); + if (existsSync(sliceSummary)) unlinkSync(sliceSummary); + const sliceUat = join(sliceDir, `${slice.id}-UAT.md`); + if (existsSync(sliceUat)) unlinkSync(sliceUat); + } + + const tasksDir = resolveTasksDir(basePath, params.milestoneId, slice.id); + if (tasksDir) { + const tasks = getSliceTasks(params.milestoneId, slice.id); + for (const task of tasks) { + const taskSummary = join(tasksDir, `${task.id}-SUMMARY.md`); + if (existsSync(taskSummary)) unlinkSync(taskSummary); + } + } + } + } catch (err) { debugLog("reopen-milestone-cleanup-failed", { milestoneId: params.milestoneId, error: String(err) }); } + clearPathCache(); + + // ── Post-mutation hook ─────────────────────────────────────────────────── + try { + await renderAllProjections(basePath, params.milestoneId); + writeManifest(basePath); + appendEvent(basePath, { + cmd: "reopen-milestone", + params: { + milestoneId: params.milestoneId, + reason: params.reason ?? null, + slicesReset: slicesResetCount, + tasksReset: tasksResetCount, + }, + ts: new Date().toISOString(), + actor: "agent", + actor_name: params.actorName, + trigger_reason: params.triggerReason, + }); + } catch (hookErr) { + logWarning("tool", `reopen-milestone post-mutation hook warning: ${(hookErr as Error).message}`); + } + + return { + milestoneId: params.milestoneId, + slicesReset: slicesResetCount, + tasksReset: tasksResetCount, + }; +} diff --git a/src/resources/extensions/gsd/tools/reopen-slice.ts b/src/resources/extensions/gsd/tools/reopen-slice.ts index 9064167fd..f03a4905e 100644 --- a/src/resources/extensions/gsd/tools/reopen-slice.ts +++ b/src/resources/extensions/gsd/tools/reopen-slice.ts @@ -24,6 +24,10 @@ import { isClosedStatus } from "../status-guards.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; +import { existsSync, unlinkSync } from "node:fs"; +import { join } from "node:path"; +import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js"; export interface ReopenSliceParams { milestoneId: string; @@ -95,6 +99,30 @@ export async function handleReopenSlice( // ── Invalidate caches ──────────────────────────────────────────────────── invalidateStateCache(); + // ── Clean up stale filesystem artifacts (M12 fix) ──────────────────────── + // Without this, the DB-filesystem reconciler sees SUMMARY.md files and + // auto-corrects tasks back to "complete", making reopen a no-op (#3161). + try { + const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId); + if (tasksDir) { + const tasks = getSliceTasks(params.milestoneId, params.sliceId); + for (const task of tasks) { + const summaryPath = join(tasksDir, `${task.id}-SUMMARY.md`); + if (existsSync(summaryPath)) unlinkSync(summaryPath); + } + } + const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId); + if (sliceDir) { + const sliceSummary = join(sliceDir, `${params.sliceId}-SUMMARY.md`); + if (existsSync(sliceSummary)) unlinkSync(sliceSummary); + const sliceUat = join(sliceDir, `${params.sliceId}-UAT.md`); + if (existsSync(sliceUat)) unlinkSync(sliceUat); + } + } catch (cleanupErr) { + logWarning("tool", `reopen-slice artifact cleanup warning: ${(cleanupErr as Error).message}`); + } + clearPathCache(); + // ── Post-mutation hook ─────────────────────────────────────────────────── try { await renderAllProjections(basePath, params.milestoneId); @@ -113,9 +141,7 @@ export async function handleReopenSlice( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: reopen-slice post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `reopen-slice post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/reopen-task.ts b/src/resources/extensions/gsd/tools/reopen-task.ts index 5f5af1ddc..14dbf377e 100644 --- a/src/resources/extensions/gsd/tools/reopen-task.ts +++ b/src/resources/extensions/gsd/tools/reopen-task.ts @@ -22,6 +22,10 @@ import { isClosedStatus } from "../status-guards.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; +import { existsSync, unlinkSync } from "node:fs"; +import { join } from "node:path"; +import { resolveTasksDir, clearPathCache } from "../paths.js"; export interface ReopenTaskParams { milestoneId: string; @@ -99,6 +103,20 @@ export async function handleReopenTask( // ── Invalidate caches ──────────────────────────────────────────────────── invalidateStateCache(); + // ── Clean up stale filesystem artifacts (M12 fix) ──────────────────────── + // Without this, the DB-filesystem reconciler sees the SUMMARY.md and + // auto-corrects the task back to "complete", making reopen a no-op (#3161). + try { + const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId); + if (tasksDir) { + const summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`); + if (existsSync(summaryPath)) unlinkSync(summaryPath); + } + } catch (cleanupErr) { + logWarning("tool", `reopen-task artifact cleanup warning: ${(cleanupErr as Error).message}`); + } + clearPathCache(); + // ── Post-mutation hook ─────────────────────────────────────────────────── try { await renderAllProjections(basePath, params.milestoneId); @@ -117,9 +135,7 @@ export async function handleReopenTask( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: reopen-task post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `reopen-task post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/replan-slice.ts b/src/resources/extensions/gsd/tools/replan-slice.ts index b55dae238..9b323c79c 100644 --- a/src/resources/extensions/gsd/tools/replan-slice.ts +++ b/src/resources/extensions/gsd/tools/replan-slice.ts @@ -16,6 +16,7 @@ import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js"; import { renderAllProjections } from "../workflow-projections.js"; import { writeManifest } from "../workflow-manifest.js"; import { appendEvent } from "../workflow-events.js"; +import { logWarning } from "../workflow-logger.js"; export interface ReplanSliceTaskInput { taskId: string; @@ -226,9 +227,7 @@ export async function handleReplanSlice( trigger_reason: params.triggerReason, }); } catch (hookErr) { - process.stderr.write( - `gsd: replan-slice post-mutation hook warning: ${(hookErr as Error).message}\n`, - ); + logWarning("tool", `replan-slice post-mutation hook warning: ${(hookErr as Error).message}`); } return { diff --git a/src/resources/extensions/gsd/tools/validate-milestone.ts b/src/resources/extensions/gsd/tools/validate-milestone.ts index 305b75c06..b5e62acb9 100644 --- a/src/resources/extensions/gsd/tools/validate-milestone.ts +++ b/src/resources/extensions/gsd/tools/validate-milestone.ts @@ -1,8 +1,12 @@ /** * validate-milestone handler — the core operation behind gsd_validate_milestone. * - * Persists milestone validation results to the assessments table, - * renders VALIDATION.md to disk, and invalidates caches. + * Persists milestone validation results to the assessments table and + * quality_gates table, renders VALIDATION.md to disk, and invalidates caches. + * + * #2945 Bug 4: Previously only wrote to assessments — quality_gates records + * were never persisted, causing M002+ milestones to have zero gate records + * despite passing validation. */ import { join } from "node:path"; @@ -11,11 +15,14 @@ import { transaction, insertAssessment, deleteAssessmentByScope, + getMilestoneSlices, } from "../gsd-db.js"; import { resolveMilestonePath, clearPathCache } from "../paths.js"; import { saveFile, clearParseCache } from "../files.js"; import { invalidateStateCache } from "../state.js"; import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js"; +import { insertMilestoneValidationGates } from "../milestone-validation-gates.js"; +import { logWarning } from "../workflow-logger.js"; export interface ValidateMilestoneParams { milestoneId: string; @@ -112,6 +119,18 @@ export async function handleValidateMilestone( scope: 'milestone-validation', fullContent: validationMd, }); + + // #2945 Bug 4: persist quality_gates records alongside the assessment. + // Previously only the assessment was written, leaving M002+ milestones + // with zero quality_gate records despite passing validation. + const slices = getMilestoneSlices(params.milestoneId); + const sliceId = slices.length > 0 ? slices[0].id : "_milestone"; + insertMilestoneValidationGates( + params.milestoneId, + sliceId, + params.verdict, + validatedAt, + ); }); // ── Filesystem render (outside transaction) ──────────────────────────── @@ -119,9 +138,7 @@ export async function handleValidateMilestone( try { await saveFile(validationPath, validationMd); } catch (renderErr) { - process.stderr.write( - `gsd-db: validate_milestone — disk render failed, rolling back DB row: ${(renderErr as Error).message}\n`, - ); + logWarning("tool", `validate_milestone — disk render failed, rolling back DB row: ${(renderErr as Error).message}`); deleteAssessmentByScope(params.milestoneId, 'milestone-validation'); return { error: `disk render failed: ${(renderErr as Error).message}` }; } diff --git a/src/resources/extensions/gsd/tools/workflow-tool-executors.ts b/src/resources/extensions/gsd/tools/workflow-tool-executors.ts new file mode 100644 index 000000000..14f179bff --- /dev/null +++ b/src/resources/extensions/gsd/tools/workflow-tool-executors.ts @@ -0,0 +1,664 @@ +import { ensureDbOpen } from "../bootstrap/dynamic-tools.js"; +import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js"; +import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot } from "../bootstrap/write-gate.js"; +import { + getMilestone, + getSliceStatusSummary, + getSliceTaskCounts, + _getAdapter, + saveGateResult, +} from "../gsd-db.js"; +import { saveArtifactToDb } from "../db-writer.js"; +import type { CompleteMilestoneParams } from "./complete-milestone.js"; +import { handleCompleteMilestone } from "./complete-milestone.js"; +import { handleCompleteTask } from "./complete-task.js"; +import type { CompleteSliceParams } from "../types.js"; +import { handleCompleteSlice } from "./complete-slice.js"; +import type { PlanMilestoneParams } from "./plan-milestone.js"; +import { handlePlanMilestone } from "./plan-milestone.js"; +import type { PlanSliceParams } from "./plan-slice.js"; +import { handlePlanSlice } from "./plan-slice.js"; +import type { ReplanSliceParams } from "./replan-slice.js"; +import { handleReplanSlice } from "./replan-slice.js"; +import type { ReassessRoadmapParams } from "./reassess-roadmap.js"; +import { handleReassessRoadmap } from "./reassess-roadmap.js"; +import type { ValidateMilestoneParams } from "./validate-milestone.js"; +import { handleValidateMilestone } from "./validate-milestone.js"; +import { logError, logWarning } from "../workflow-logger.js"; +import { invalidateStateCache } from "../state.js"; + +export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = ["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT"] as const; + +export function isSupportedSummaryArtifactType( + artifactType: string, +): artifactType is (typeof SUPPORTED_SUMMARY_ARTIFACT_TYPES)[number] { + return (SUPPORTED_SUMMARY_ARTIFACT_TYPES as readonly string[]).includes(artifactType); +} + +export interface ToolExecutionResult { + content: Array<{ type: "text"; text: string }>; + details: Record; + isError?: boolean; +} + +export interface SummarySaveParams { + milestone_id: string; + slice_id?: string; + task_id?: string; + artifact_type: string; + content: string; +} + +export async function executeSummarySave( + params: SummarySaveParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot save artifact." }], + details: { operation: "save_summary", error: "db_unavailable" }, + isError: true, + }; + } + if (!isSupportedSummaryArtifactType(params.artifact_type)) { + return { + content: [{ type: "text", text: `Error: Invalid artifact_type "${params.artifact_type}". Must be one of: ${SUPPORTED_SUMMARY_ARTIFACT_TYPES.join(", ")}` }], + details: { operation: "save_summary", error: "invalid_artifact_type" }, + isError: true, + }; + } + const contextGuard = shouldBlockContextArtifactSaveInSnapshot( + loadWriteGateSnapshot(basePath), + params.artifact_type, + params.milestone_id ?? null, + params.slice_id ?? null, + ); + if (contextGuard.block) { + return { + content: [{ type: "text", text: `Error saving artifact: ${contextGuard.reason ?? "context write blocked"}` }], + details: { operation: "save_summary", error: "context_write_blocked" }, + isError: true, + }; + } + try { + let relativePath: string; + if (params.task_id && params.slice_id) { + relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`; + } else if (params.slice_id) { + relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`; + } else { + relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`; + } + + await saveArtifactToDb( + { + path: relativePath, + artifact_type: params.artifact_type, + content: params.content, + milestone_id: params.milestone_id, + slice_id: params.slice_id, + task_id: params.task_id, + }, + basePath, + ); + return { + content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }], + details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `gsd_summary_save tool failed: ${msg}`, { tool: "gsd_summary_save", error: String(err) }); + return { + content: [{ type: "text", text: `Error saving artifact: ${msg}` }], + details: { operation: "save_summary", error: msg }, + isError: true, + }; + } +} + +type VerificationEvidenceInput = + | { + command: string; + exitCode: number; + verdict: string; + durationMs: number; + } + | string; + +export interface TaskCompleteParams { + taskId: string; + sliceId: string; + milestoneId: string; + oneLiner: string; + narrative: string; + verification: string; + deviations?: string; + knownIssues?: string; + keyFiles?: string[]; + keyDecisions?: string[]; + blockerDiscovered?: boolean; + verificationEvidence?: VerificationEvidenceInput[]; +} + +export type CompleteMilestoneExecutorParams = Partial & Record; +export type SliceCompleteExecutorParams = CompleteSliceParams; +export type PlanMilestoneExecutorParams = PlanMilestoneParams; +export type PlanSliceExecutorParams = PlanSliceParams; +export type ReplanSliceExecutorParams = ReplanSliceParams; +export type ValidateMilestoneExecutorParams = ValidateMilestoneParams; +export type ReassessRoadmapExecutorParams = ReassessRoadmapParams; + +export interface SaveGateResultParams { + milestoneId: string; + sliceId: string; + gateId: string; + taskId?: string; + verdict: "pass" | "flag" | "omitted"; + rationale: string; + findings?: string; +} + +export async function executeTaskComplete( + params: TaskCompleteParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot complete task." }], + details: { operation: "complete_task", error: "db_unavailable" }, + isError: true, + }; + } + try { + const coerced = { ...params }; + coerced.verificationEvidence = (params.verificationEvidence ?? []).map((v) => + typeof v === "string" ? { command: v, exitCode: -1, verdict: "unknown (coerced from string)", durationMs: 0 } : v, + ); + + const result = await handleCompleteTask(coerced as any, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error completing task: ${result.error}` }], + details: { operation: "complete_task", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Completed task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }], + details: { + operation: "complete_task", + taskId: result.taskId, + sliceId: result.sliceId, + milestoneId: result.milestoneId, + summaryPath: result.summaryPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `complete_task tool failed: ${msg}`, { tool: "gsd_task_complete", error: String(err) }); + return { + content: [{ type: "text", text: `Error completing task: ${msg}` }], + details: { operation: "complete_task", error: msg }, + isError: true, + }; + } +} + +export async function executeSliceComplete( + params: SliceCompleteExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot complete slice." }], + details: { operation: "complete_slice", error: "db_unavailable" }, + isError: true, + }; + } + try { + const splitPair = (s: string): [string, string] => { + const m = s.match(/^(.+?)\s*(?:—|-)\s+(.+)$/); + return m ? [m[1].trim(), m[2].trim()] : [s.trim(), ""]; + }; + const wrapArray = (v: unknown): unknown[] => + v == null ? [] : Array.isArray(v) ? v : [v]; + + const coerced = { ...params } as CompleteSliceParams & Record; + coerced.provides = wrapArray(params.provides) as string[]; + coerced.keyFiles = wrapArray(params.keyFiles) as string[]; + coerced.keyDecisions = wrapArray(params.keyDecisions) as string[]; + coerced.patternsEstablished = wrapArray(params.patternsEstablished) as string[]; + coerced.observabilitySurfaces = wrapArray(params.observabilitySurfaces) as string[]; + coerced.requirementsSurfaced = wrapArray(params.requirementsSurfaced) as string[]; + coerced.drillDownPaths = wrapArray(params.drillDownPaths) as string[]; + coerced.affects = wrapArray(params.affects) as string[]; + coerced.filesModified = wrapArray(params.filesModified).map((f) => { + if (typeof f !== "string") return f; + const [path, description] = splitPair(f); + return { path, description }; + }) as Array<{ path: string; description: string }>; + coerced.requires = wrapArray(params.requires).map((r) => { + if (typeof r !== "string") return r; + const [slice, provides] = splitPair(r); + return { slice, provides }; + }) as Array<{ slice: string; provides: string }>; + coerced.requirementsAdvanced = wrapArray(params.requirementsAdvanced).map((r) => { + if (typeof r !== "string") return r; + const [id, how] = splitPair(r); + return { id, how }; + }) as Array<{ id: string; how: string }>; + coerced.requirementsValidated = wrapArray(params.requirementsValidated).map((r) => { + if (typeof r !== "string") return r; + const [id, proof] = splitPair(r); + return { id, proof }; + }) as Array<{ id: string; proof: string }>; + coerced.requirementsInvalidated = wrapArray(params.requirementsInvalidated).map((r) => { + if (typeof r !== "string") return r; + const [id, what] = splitPair(r); + return { id, what }; + }) as Array<{ id: string; what: string }>; + + const result = await handleCompleteSlice(coerced as CompleteSliceParams, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error completing slice: ${result.error}` }], + details: { operation: "complete_slice", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Completed slice ${result.sliceId} (${result.milestoneId})` }], + details: { + operation: "complete_slice", + sliceId: result.sliceId, + milestoneId: result.milestoneId, + summaryPath: result.summaryPath, + uatPath: result.uatPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `complete_slice tool failed: ${msg}`, { tool: "gsd_slice_complete", error: String(err) }); + return { + content: [{ type: "text", text: `Error completing slice: ${msg}` }], + details: { operation: "complete_slice", error: msg }, + isError: true, + }; + } +} + +export async function executeCompleteMilestone( + params: CompleteMilestoneExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot complete milestone." }], + details: { operation: "complete_milestone", error: "db_unavailable" }, + isError: true, + }; + } + try { + const sanitized = sanitizeCompleteMilestoneParams(params); + const result = await handleCompleteMilestone(sanitized, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error completing milestone: ${result.error}` }], + details: { operation: "complete_milestone", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Completed milestone ${result.milestoneId}. Summary written to ${result.summaryPath}` }], + details: { + operation: "complete_milestone", + milestoneId: result.milestoneId, + summaryPath: result.summaryPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `complete_milestone tool failed: ${msg}`, { tool: "gsd_complete_milestone", error: String(err) }); + return { + content: [{ type: "text", text: `Error completing milestone: ${msg}` }], + details: { operation: "complete_milestone", error: msg }, + isError: true, + }; + } +} + +export async function executeValidateMilestone( + params: ValidateMilestoneExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot validate milestone." }], + details: { operation: "validate_milestone", error: "db_unavailable" }, + isError: true, + }; + } + try { + const result = await handleValidateMilestone(params, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error validating milestone: ${result.error}` }], + details: { operation: "validate_milestone", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Validated milestone ${result.milestoneId} — verdict: ${result.verdict}. Written to ${result.validationPath}` }], + details: { + operation: "validate_milestone", + milestoneId: result.milestoneId, + verdict: result.verdict, + validationPath: result.validationPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `validate_milestone tool failed: ${msg}`, { tool: "gsd_validate_milestone", error: String(err) }); + return { + content: [{ type: "text", text: `Error validating milestone: ${msg}` }], + details: { operation: "validate_milestone", error: msg }, + isError: true, + }; + } +} + +export async function executeReassessRoadmap( + params: ReassessRoadmapExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot reassess roadmap." }], + details: { operation: "reassess_roadmap", error: "db_unavailable" }, + isError: true, + }; + } + try { + const result = await handleReassessRoadmap(params, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error reassessing roadmap: ${result.error}` }], + details: { operation: "reassess_roadmap", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Reassessed roadmap for milestone ${result.milestoneId} after ${result.completedSliceId}` }], + details: { + operation: "reassess_roadmap", + milestoneId: result.milestoneId, + completedSliceId: result.completedSliceId, + assessmentPath: result.assessmentPath, + roadmapPath: result.roadmapPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `reassess_roadmap tool failed: ${msg}`, { tool: "gsd_reassess_roadmap", error: String(err) }); + return { + content: [{ type: "text", text: `Error reassessing roadmap: ${msg}` }], + details: { operation: "reassess_roadmap", error: msg }, + isError: true, + }; + } +} + +export async function executeSaveGateResult( + params: SaveGateResultParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available." }], + details: { operation: "save_gate_result", error: "db_unavailable" }, + isError: true, + }; + } + + const validGates = ["Q3", "Q4", "Q5", "Q6", "Q7", "Q8"]; + if (!validGates.includes(params.gateId)) { + return { + content: [{ type: "text", text: `Error: Invalid gateId "${params.gateId}". Must be one of: ${validGates.join(", ")}` }], + details: { operation: "save_gate_result", error: "invalid_gate_id" }, + isError: true, + }; + } + + const validVerdicts = ["pass", "flag", "omitted"]; + if (!validVerdicts.includes(params.verdict)) { + return { + content: [{ type: "text", text: `Error: Invalid verdict "${params.verdict}". Must be one of: ${validVerdicts.join(", ")}` }], + details: { operation: "save_gate_result", error: "invalid_verdict" }, + isError: true, + }; + } + + try { + saveGateResult({ + milestoneId: params.milestoneId, + sliceId: params.sliceId, + gateId: params.gateId, + taskId: params.taskId ?? "", + verdict: params.verdict, + rationale: params.rationale, + findings: params.findings ?? "", + }); + invalidateStateCache(); + return { + content: [{ type: "text", text: `Gate ${params.gateId} result saved: verdict=${params.verdict}` }], + details: { operation: "save_gate_result", gateId: params.gateId, verdict: params.verdict }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `gsd_save_gate_result failed: ${msg}`, { tool: "gsd_save_gate_result", error: String(err) }); + return { + content: [{ type: "text", text: `Error saving gate result: ${msg}` }], + details: { operation: "save_gate_result", error: msg }, + isError: true, + }; + } +} + +export async function executePlanMilestone( + params: PlanMilestoneExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot plan milestone." }], + details: { operation: "plan_milestone", error: "db_unavailable" }, + isError: true, + }; + } + try { + const result = await handlePlanMilestone(params, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error planning milestone: ${result.error}` }], + details: { operation: "plan_milestone", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Planned milestone ${result.milestoneId}` }], + details: { + operation: "plan_milestone", + milestoneId: result.milestoneId, + roadmapPath: result.roadmapPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `plan_milestone tool failed: ${msg}`, { tool: "gsd_plan_milestone", error: String(err) }); + return { + content: [{ type: "text", text: `Error planning milestone: ${msg}` }], + details: { operation: "plan_milestone", error: msg }, + isError: true, + }; + } +} + +export async function executePlanSlice( + params: PlanSliceExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot plan slice." }], + details: { operation: "plan_slice", error: "db_unavailable" }, + isError: true, + }; + } + try { + const result = await handlePlanSlice(params, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error planning slice: ${result.error}` }], + details: { operation: "plan_slice", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Planned slice ${result.sliceId} (${result.milestoneId})` }], + details: { + operation: "plan_slice", + milestoneId: result.milestoneId, + sliceId: result.sliceId, + planPath: result.planPath, + taskPlanPaths: result.taskPlanPaths, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `plan_slice tool failed: ${msg}`, { tool: "gsd_plan_slice", error: String(err) }); + return { + content: [{ type: "text", text: `Error planning slice: ${msg}` }], + details: { operation: "plan_slice", error: msg }, + isError: true, + }; + } +} + +export async function executeReplanSlice( + params: ReplanSliceExecutorParams, + basePath: string = process.cwd(), +): Promise { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available. Cannot replan slice." }], + details: { operation: "replan_slice", error: "db_unavailable" }, + isError: true, + }; + } + try { + const result = await handleReplanSlice(params, basePath); + if ("error" in result) { + return { + content: [{ type: "text", text: `Error replanning slice: ${result.error}` }], + details: { operation: "replan_slice", error: result.error }, + isError: true, + }; + } + return { + content: [{ type: "text", text: `Replanned slice ${result.sliceId} (${result.milestoneId})` }], + details: { + operation: "replan_slice", + milestoneId: result.milestoneId, + sliceId: result.sliceId, + replanPath: result.replanPath, + planPath: result.planPath, + }, + }; + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logError("tool", `replan_slice tool failed: ${msg}`, { tool: "gsd_replan_slice", error: String(err) }); + return { + content: [{ type: "text", text: `Error replanning slice: ${msg}` }], + details: { operation: "replan_slice", error: msg }, + isError: true, + }; + } +} + +export interface MilestoneStatusParams { + milestoneId: string; +} + +export async function executeMilestoneStatus( + params: MilestoneStatusParams, + basePath: string = process.cwd(), +): Promise { + try { + const dbAvailable = await ensureDbOpen(basePath); + if (!dbAvailable) { + return { + content: [{ type: "text", text: "Error: GSD database is not available." }], + details: { operation: "milestone_status", error: "db_unavailable" }, + isError: true, + }; + } + + const adapter = _getAdapter()!; + adapter.exec("BEGIN"); + try { + const milestone = getMilestone(params.milestoneId); + if (!milestone) { + adapter.exec("COMMIT"); + return { + content: [{ type: "text", text: `Milestone ${params.milestoneId} not found in database.` }], + details: { operation: "milestone_status", milestoneId: params.milestoneId, found: false }, + }; + } + + const sliceStatuses = getSliceStatusSummary(params.milestoneId); + const slices = sliceStatuses.map((s) => ({ + id: s.id, + status: s.status, + taskCounts: getSliceTaskCounts(params.milestoneId, s.id), + })); + + adapter.exec("COMMIT"); + + const result = { + milestoneId: milestone.id, + title: milestone.title, + status: milestone.status, + createdAt: milestone.created_at, + completedAt: milestone.completed_at, + sliceCount: slices.length, + slices, + }; + + return { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + details: { operation: "milestone_status", milestoneId: milestone.id, sliceCount: slices.length }, + }; + } catch (txErr) { + try { adapter.exec("ROLLBACK"); } catch { /* swallow */ } + throw txErr; + } + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + logWarning("tool", `gsd_milestone_status tool failed: ${msg}`); + return { + content: [{ type: "text", text: `Error querying milestone status: ${msg}` }], + details: { operation: "milestone_status", error: msg }, + isError: true, + }; + } +} diff --git a/src/resources/extensions/gsd/triage-resolution.ts b/src/resources/extensions/gsd/triage-resolution.ts index eefb2caa8..4befa1ad6 100644 --- a/src/resources/extensions/gsd/triage-resolution.ts +++ b/src/resources/extensions/gsd/triage-resolution.ts @@ -10,7 +10,8 @@ * Also provides detectFileOverlap() for surfacing downstream impact on quick tasks. */ -import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs"; +import { atomicWriteSync } from "./atomic-write.js"; import { join } from "node:path"; import { createRequire } from "node:module"; import { gsdRoot, milestonesDir } from "./paths.js"; @@ -22,6 +23,7 @@ import { loadActionableCaptures, markCaptureResolved, markCaptureExecuted, + stampCaptureMilestone, } from "./captures.js"; // ─── Resolution Executors ───────────────────────────────────────────────────── @@ -64,10 +66,10 @@ export function executeInject( const filesSection = content.indexOf("## Files Likely Touched"); if (filesSection !== -1) { const updated = content.slice(0, filesSection) + newTask + "\n\n" + content.slice(filesSection); - writeFileSync(planPath, updated, "utf-8"); + atomicWriteSync(planPath, updated, "utf-8"); } else { // No Files section — append at end - writeFileSync(planPath, content.trimEnd() + "\n\n" + newTask + "\n", "utf-8"); + atomicWriteSync(planPath, content.trimEnd() + "\n\n" + newTask + "\n", "utf-8"); } return newId; @@ -104,7 +106,7 @@ export function executeReplan( `will detect it and enter the replanning-slice phase.`, ].join("\n"); - writeFileSync(triggerPath, content, "utf-8"); + atomicWriteSync(triggerPath, content, "utf-8"); // Also write replan_triggered_at column for DB-backed detection try { @@ -128,6 +130,136 @@ export function executeReplan( } } +// ─── Backtrack (Milestone Regression) ──────────────────────────────────────── + +/** + * Execute a backtrack directive — user wants to abandon current milestone + * and return to a previous one (milestone regression). + * + * Writes a BACKTRACK-TRIGGER.md marker at `.gsd/BACKTRACK-TRIGGER.md` with + * the target milestone, reason, and timestamp. The state machine (deriveState) + * detects this and transitions the project to the target milestone, resetting + * its slices to allow re-planning. + * + * Returns the extracted target milestone ID, or null if extraction failed. + */ +export function executeBacktrack( + basePath: string, + currentMilestoneId: string, + capture: CaptureEntry, +): string | null { + try { + // Extract target milestone from capture text or resolution. + // Filter out the current milestone ID to avoid picking it as the backtrack target + // when the text mentions both current and target milestones (e.g. "backtrack from M004 to M003"). + const sourceText = capture.resolution ?? capture.text; + const allMatches = [...sourceText.matchAll(/\b(M\d{3}(?:-[a-z0-9]{6})?)\b/g)] + .map(m => m[1]) + .filter(id => id !== currentMilestoneId); + // Reject ambiguous multi-target strings — if more than one distinct target remains, + // don't guess; let the user clarify. + const uniqueTargets = [...new Set(allMatches)]; + const targetMilestoneId = uniqueTargets.length === 1 ? uniqueTargets[0] : null; + + const ts = new Date().toISOString(); + const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md"); + const content = [ + `# Backtrack Trigger`, + ``, + `**Source:** Capture ${capture.id}`, + `**Capture:** ${capture.text}`, + `**Rationale:** ${capture.rationale ?? "User-initiated milestone backtrack"}`, + `**From:** ${currentMilestoneId}`, + `**Target:** ${targetMilestoneId ?? "(user to specify)"}`, + `**Triggered:** ${ts}`, + ``, + `Auto-mode was paused by this backtrack directive. The user directed`, + `that the current milestone (${currentMilestoneId}) be abandoned and work`, + `should return to ${targetMilestoneId ?? "a previous milestone"}.`, + ``, + `## Recovery Steps`, + ``, + `1. Review what went wrong in ${currentMilestoneId}`, + `2. Identify missing features/requirements from the target milestone`, + `3. Resume auto-mode — the state machine will re-enter discussion for the target`, + ].join("\n"); + + atomicWriteSync(triggerPath, content, "utf-8"); + + // If we have a valid target, also reset that milestone's completion status + // so deriveState() will re-enter it as the active milestone. + if (targetMilestoneId) { + try { + const targetDir = join(milestonesDir(basePath), targetMilestoneId); + if (existsSync(targetDir)) { + // Write a regression marker so the state machine knows this milestone + // needs re-discussion, not just re-execution + const regressionPath = join(targetDir, `${targetMilestoneId}-REGRESSION.md`); + atomicWriteSync(regressionPath, [ + `# Milestone Regression`, + ``, + `**From:** ${currentMilestoneId}`, + `**Reason:** ${capture.text}`, + `**Triggered:** ${ts}`, + ``, + `This milestone is being revisited because downstream milestone`, + `${currentMilestoneId} failed or missed critical features that should`, + `have been part of this milestone's scope.`, + ``, + `The discuss phase should re-evaluate requirements and identify gaps.`, + ].join("\n"), "utf-8"); + } + } catch { /* best-effort */ } + } + + return targetMilestoneId; + } catch { + return null; + } +} + +/** + * Read the backtrack trigger file if it exists. + * Returns the parsed target milestone and metadata, or null. + */ +export function readBacktrackTrigger(basePath: string): { + target: string | null; + from: string | null; + capture: string; + triggeredAt: string; +} | null { + const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md"); + if (!existsSync(triggerPath)) return null; + + try { + const content = readFileSync(triggerPath, "utf-8"); + const target = content.match(/\*\*Target:\*\*\s*(.+)/)?.[1]?.trim() ?? null; + const from = content.match(/\*\*From:\*\*\s*(.+)/)?.[1]?.trim() ?? null; + const capture = content.match(/\*\*Capture:\*\*\s*(.+)/)?.[1]?.trim() ?? ""; + const triggeredAt = content.match(/\*\*Triggered:\*\*\s*(.+)/)?.[1]?.trim() ?? ""; + return { + target: target === "(user to specify)" ? null : target, + from, + capture, + triggeredAt, + }; + } catch { + return null; + } +} + +/** + * Remove the backtrack trigger after it has been processed. + */ +export function clearBacktrackTrigger(basePath: string): void { + const triggerPath = join(gsdRoot(basePath), "BACKTRACK-TRIGGER.md"); + try { + if (existsSync(triggerPath)) { + unlinkSync(triggerPath); + } + } catch { /* best-effort */ } +} + // ─── File Overlap Detection ─────────────────────────────────────────────────── /** @@ -230,7 +362,7 @@ export function ensureDeferMilestoneDir( ``, ].join("\n"); - writeFileSync( + atomicWriteSync( join(msDir, `${targetMilestone}-CONTEXT-DRAFT.md`), draftContent, "utf-8", @@ -271,11 +403,15 @@ export function buildQuickTaskPrompt(capture: CaptureEntry): string { ``, `## Instructions`, ``, - `1. Execute this task as a small, self-contained change.`, - `2. Do NOT modify any \`.gsd/\` plan files — this is a one-off, not a planned task.`, - `3. Commit your changes with a descriptive message.`, - `4. Keep changes minimal and focused on the capture text.`, - `5. When done, say: "Quick task complete."`, + `1. **Verify the issue still exists.** Before making any changes, inspect the`, + ` relevant code to confirm the problem described above is actually present in`, + ` the current codebase. If the issue has already been fixed (e.g., by planned`, + ` milestone work), report "Already resolved — no changes needed." and stop.`, + `2. Execute this task as a small, self-contained change.`, + `3. Do NOT modify any \`.gsd/\` plan files — this is a one-off, not a planned task.`, + `4. Commit your changes with a descriptive message.`, + `5. Keep changes minimal and focused on the capture text.`, + `6. When done, say: "Quick task complete."`, ].join("\n"); } @@ -293,6 +429,10 @@ export interface TriageExecutionResult { deferredMilestones: number; /** Captures classified as quick-task that need dispatch */ quickTasks: CaptureEntry[]; + /** Number of stop directives (will pause auto-mode via guard) */ + stopped: number; + /** Backtrack captures (will trigger milestone regression via guard) */ + backtracks: CaptureEntry[]; /** Details of each action taken, for logging */ actions: string[]; } @@ -321,20 +461,37 @@ export function executeTriageResolutions( replanned: 0, deferredMilestones: 0, quickTasks: [], + stopped: 0, + backtracks: [], actions: [], }; - const actionable = loadActionableCaptures(basePath); + const actionable = loadActionableCaptures(basePath, mid || undefined); - // Also process deferred captures that target milestone IDs — create - // milestone directories so deriveState() discovers them. - const deferred = loadAllCaptures(basePath).filter( - c => c.status === "resolved" && !c.executed && c.classification === "defer", + // Reconciliation: stamp actionable captures that are missing the Milestone field + // with the current milestone ID. This covers captures resolved by the triage LLM + // before the prompt included the Milestone instruction, and acts as a safety net + // when the LLM omits the field (#2872). + if (mid) { + for (const capture of actionable) { + if (!capture.resolvedInMilestone) { + stampCaptureMilestone(basePath, capture.id, mid); + } + } + } + + // Also process deferred and milestone-class captures (#3542). + // A defer/milestone capture's "action" is the triage decision itself — + // once classified and resolved, the capture is done. The target milestone + // picks up the work naturally from its planning context. + const deferrable = loadAllCaptures(basePath).filter( + c => c.status === "resolved" && !c.executed && + (c.classification === "defer" || (c.classification as string) === "milestone"), ); - if (deferred.length > 0) { - // Group deferred captures by target milestone + if (deferrable.length > 0) { + // Group captures that reference a specific milestone — create dirs as needed. const byMilestone = new Map(); - for (const cap of deferred) { + for (const cap of deferrable) { const target = cap.resolution?.match(/\b(M\d{3}(?:-[a-z0-9]{6})?)\b/)?.[1]; if (target) { const list = byMilestone.get(target) ?? []; @@ -349,12 +506,28 @@ export function executeTriageResolutions( if (created) { result.deferredMilestones++; result.actions.push(`Created milestone ${milestoneId} for ${captures.length} deferred capture(s)`); - for (const cap of captures) { - markCaptureExecuted(basePath, cap.id); - } } } } + // Stamp ALL defer/milestone captures as executed (#3542 gaps 1-3). + // Previously only captures that triggered dir creation were stamped. + // Captures without a milestone ID in resolution text, or targeting an + // existing directory, were silently dropped — never stamped. + for (const cap of deferrable) { + if (!cap.executed) { + markCaptureExecuted(basePath, cap.id); + } + } + } + + // Mark note captures as executed — they're informational only, no action + // needed. Without this they stay in "resolved but not executed" limbo (#3578). + const notes = loadAllCaptures(basePath).filter( + c => c.status === "resolved" && !c.executed && c.classification === "note", + ); + for (const cap of notes) { + markCaptureExecuted(basePath, cap.id); + result.actions.push(`Note acknowledged: ${cap.id} — "${cap.text}"`); } if (actionable.length === 0) return result; @@ -392,5 +565,19 @@ export function executeTriageResolutions( } } + // Count stop/backtrack captures — these are handled by the pre-dispatch guard + // in runGuards(), not here. We just report them for logging purposes. + const allCaptures = loadAllCaptures(basePath); + for (const cap of allCaptures) { + if (cap.status !== "resolved" || cap.executed) continue; + if (cap.classification === "stop") { + result.stopped++; + result.actions.push(`Stop directive from ${cap.id}: "${cap.text}" — will pause on next dispatch`); + } else if (cap.classification === "backtrack") { + result.backtracks.push(cap); + result.actions.push(`Backtrack directive from ${cap.id}: "${cap.text}" — will trigger milestone regression on next dispatch`); + } + } + return result; } diff --git a/src/resources/extensions/gsd/triage-ui.ts b/src/resources/extensions/gsd/triage-ui.ts index a9b81f46f..b2ea7cf4f 100644 --- a/src/resources/extensions/gsd/triage-ui.ts +++ b/src/resources/extensions/gsd/triage-ui.ts @@ -49,10 +49,18 @@ const CLASSIFICATION_LABELS: Record; - requirementsValidated: Array<{ id: string; proof: string }>; - requirementsSurfaced: string[]; - requirementsInvalidated: Array<{ id: string; what: string }>; - filesModified: Array<{ path: string; description: string }>; uatContent: string; - provides: string[]; - requires: Array<{ slice: string; provides: string }>; - affects: string[]; - drillDownPaths: string[]; + /** @optional — defaults to [] when omitted by models with limited tool-calling */ + keyFiles?: string[]; + /** @optional — defaults to [] when omitted */ + keyDecisions?: string[]; + /** @optional — defaults to [] when omitted */ + patternsEstablished?: string[]; + /** @optional — defaults to [] when omitted */ + observabilitySurfaces?: string[]; + /** @optional — defaults to "None." when omitted */ + deviations?: string; + /** @optional — defaults to "None." when omitted */ + knownLimitations?: string; + /** @optional — defaults to "None." when omitted */ + followUps?: string; + /** @optional — defaults to [] when omitted */ + requirementsAdvanced?: Array<{ id: string; how: string }>; + /** @optional — defaults to [] when omitted */ + requirementsValidated?: Array<{ id: string; proof: string }>; + /** @optional — defaults to [] when omitted */ + requirementsSurfaced?: string[]; + /** @optional — defaults to [] when omitted */ + requirementsInvalidated?: Array<{ id: string; what: string }>; + /** @optional — defaults to [] when omitted */ + filesModified?: Array<{ path: string; description: string }>; + /** @optional — defaults to [] when omitted */ + provides?: string[]; + /** @optional — defaults to [] when omitted */ + requires?: Array<{ slice: string; provides: string }>; + /** @optional — defaults to [] when omitted */ + affects?: string[]; + /** @optional — defaults to [] when omitted */ + drillDownPaths?: string[]; /** Optional caller-provided identity for audit trail */ actorName?: string; /** Optional caller-provided reason this action was triggered */ @@ -563,8 +592,8 @@ export interface CompleteSliceParams { // ─── Quality Gates ─────────────────────────────────────────────────────── -export type GateId = "Q3" | "Q4" | "Q5" | "Q6" | "Q7" | "Q8"; -export type GateScope = "slice" | "task"; +export type GateId = "Q3" | "Q4" | "Q5" | "Q6" | "Q7" | "Q8" | "MV01" | "MV02" | "MV03" | "MV04"; +export type GateScope = "slice" | "task" | "milestone"; export type GateStatus = "pending" | "complete" | "omitted"; export type GateVerdict = "pass" | "flag" | "omitted" | ""; diff --git a/src/resources/extensions/gsd/undo.ts b/src/resources/extensions/gsd/undo.ts index 3d0c589b2..6443634c6 100644 --- a/src/resources/extensions/gsd/undo.ts +++ b/src/resources/extensions/gsd/undo.ts @@ -4,9 +4,10 @@ // handleResetSlice: Reset a slice and all its tasks, re-rendering plan + roadmap. import type { ExtensionCommandContext, ExtensionAPI } from "@gsd/pi-coding-agent"; -import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs"; -import { join } from "node:path"; +import { existsSync, readFileSync, unlinkSync, readdirSync } from "node:fs"; +import { join, basename } from "node:path"; import { nativeRevertCommit, nativeRevertAbort } from "./native-git-bridge.js"; +import { atomicWriteSync } from "./atomic-write.js"; import { parseUnitId } from "./unit-id.js"; import { deriveState } from "./state.js"; import { invalidateAllCaches } from "./cache.js"; @@ -133,7 +134,7 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi } ctx.ui.notify(results.join("\n"), "success"); - sendDesktopNotification("GSD", `Undone: ${unitType} (${unitId})`, "info", "complete"); + sendDesktopNotification("GSD", `Undone: ${unitType} (${unitId})`, "info", "complete", basename(basePath)); } // ─── Targeted State Reset ──────────────────────────────────────────────────── @@ -393,7 +394,7 @@ export function uncheckTaskInPlan(basePath: string, mid: string, sid: string, ti const regex = new RegExp(`^(\\s*-\\s*)\\[x\\](\\s*\\**${tid}\\**[:\\s])`, "mi"); if (regex.test(content)) { content = content.replace(regex, "$1[ ]$2"); - writeFileSync(planFile, content, "utf-8"); + atomicWriteSync(planFile, content); return true; } return false; diff --git a/src/resources/extensions/gsd/unit-ownership.ts b/src/resources/extensions/gsd/unit-ownership.ts index 9bbeb4f22..acae94999 100644 --- a/src/resources/extensions/gsd/unit-ownership.ts +++ b/src/resources/extensions/gsd/unit-ownership.ts @@ -3,18 +3,20 @@ // // An agent can claim a unit (task, slice) before working on it. // complete-task and complete-slice enforce ownership when claims exist. -// If no claim file is present, ownership is not enforced (backward compatible). +// Claims are stored in SQLite (.gsd/unit-claims.db) for atomic +// first-writer-wins semantics via INSERT OR IGNORE. // -// Claim file location: .gsd/unit-claims.json // Unit key format: // task: "//" // slice: "/" // // Copyright (c) 2026 Jeremy McSpadden -import { existsSync, readFileSync, mkdirSync } from "node:fs"; +import { createRequire } from "node:module"; +import { mkdirSync } from "node:fs"; import { join } from "node:path"; -import { atomicWriteSync } from "./atomic-write.js"; + +const _require = createRequire(import.meta.url); // ─── Types ─────────────────────────────────────────────────────────────── @@ -23,7 +25,133 @@ export interface UnitClaim { claimed_at: string; } -type ClaimsMap = Record; +// ─── SQLite Provider (mirrors gsd-db.ts pattern) ───────────────────────── + +interface StmtLike { + run(...params: unknown[]): unknown; + get(...params: unknown[]): Record | undefined; +} + +interface DbLike { + exec(sql: string): void; + prepare(sql: string): StmtLike; + close(): void; +} + +type ProviderName = "node:sqlite" | "better-sqlite3"; + +let providerName: ProviderName | null = null; +let providerModule: unknown = null; +let loadAttempted = false; + +function suppressSqliteWarning(): void { + const origEmit = process.emit; + // @ts-expect-error overriding process.emit for warning filter + process.emit = function (event: string, ...args: unknown[]): boolean { + if ( + event === "warning" && + args[0] && + typeof args[0] === "object" && + "name" in args[0] && + (args[0] as { name: string }).name === "ExperimentalWarning" && + "message" in args[0] && + typeof (args[0] as { message: string }).message === "string" && + (args[0] as { message: string }).message.includes("SQLite") + ) { + return false; + } + return origEmit.apply(process, [event, ...args] as Parameters) as unknown as boolean; + }; +} + +function loadProvider(): void { + if (loadAttempted) return; + loadAttempted = true; + + try { + suppressSqliteWarning(); + const mod = _require("node:sqlite"); + if (mod.DatabaseSync) { + providerModule = mod; + providerName = "node:sqlite"; + return; + } + } catch { + // unavailable + } + + try { + const mod = _require("better-sqlite3"); + if (typeof mod === "function" || (mod && mod.default)) { + providerModule = mod.default || mod; + providerName = "better-sqlite3"; + return; + } + } catch { + // unavailable + } +} + +function normalizeRow(row: unknown): Record | undefined { + if (row == null) return undefined; + if (Object.getPrototypeOf(row) === null) { + return { ...(row as Record) }; + } + return row as Record; +} + +function openRawDb(path: string): unknown { + loadProvider(); + if (!providerModule || !providerName) return null; + + if (providerName === "node:sqlite") { + const { DatabaseSync } = providerModule as { + DatabaseSync: new (path: string) => unknown; + }; + return new DatabaseSync(path); + } + + const Database = providerModule as new (path: string) => unknown; + return new Database(path); +} + +function wrapDb(rawDb: unknown): DbLike { + const db = rawDb as { + exec(sql: string): void; + prepare(sql: string): { + run(...args: unknown[]): unknown; + get(...args: unknown[]): unknown; + }; + close(): void; + }; + return { + exec(sql: string): void { db.exec(sql); }, + prepare(sql: string): StmtLike { + const raw = db.prepare(sql); + return { + run(...params: unknown[]): unknown { return raw.run(...params); }, + get(...params: unknown[]): Record | undefined { + return normalizeRow(raw.get(...params)); + }, + }; + }, + close(): void { db.close(); }, + }; +} + +// ─── Per-basePath DB pool ──────────────────────────────────────────────── + +const dbPool = new Map(); + +function claimsDbPath(basePath: string): string { + return join(basePath, ".gsd", "unit-claims.db"); +} + +function getDb(basePath: string): DbLike | null { + const existing = dbPool.get(basePath); + if (existing) return existing; + return null; +} // ─── Key Builders ──────────────────────────────────────────────────────── @@ -35,60 +163,103 @@ export function sliceUnitKey(milestoneId: string, sliceId: string): string { return `${milestoneId}/${sliceId}`; } -// ─── File Path ─────────────────────────────────────────────────────────── +// ─── Lifecycle ─────────────────────────────────────────────────────────── -function claimsPath(basePath: string): string { - return join(basePath, ".gsd", "unit-claims.json"); +/** + * Initialize the ownership SQLite database for a given basePath. + * Creates .gsd/ directory and unit-claims.db with the unit_claims table. + * Safe to call multiple times (idempotent). + */ +export function initOwnershipTable(basePath: string): void { + if (dbPool.has(basePath)) return; + + const dir = join(basePath, ".gsd"); + mkdirSync(dir, { recursive: true }); + + const raw = openRawDb(claimsDbPath(basePath)); + if (!raw) { + throw new Error("No SQLite provider available for unit-ownership"); + } + + const db = wrapDb(raw); + + db.exec("PRAGMA journal_mode=WAL"); + db.exec("PRAGMA busy_timeout = 5000"); + db.exec("PRAGMA synchronous = NORMAL"); + + db.exec(` + CREATE TABLE IF NOT EXISTS unit_claims ( + unit_key TEXT PRIMARY KEY, + agent_name TEXT NOT NULL, + claimed_at TEXT NOT NULL + ) + `); + + dbPool.set(basePath, db); } -// ─── Read Claims ───────────────────────────────────────────────────────── - -function readClaims(basePath: string): ClaimsMap | null { - const path = claimsPath(basePath); - if (!existsSync(path)) return null; - try { - return JSON.parse(readFileSync(path, "utf-8")) as ClaimsMap; - } catch { - return null; - } +/** + * Close the ownership database for a given basePath. + * Safe to call even if not initialized. + */ +export function closeOwnershipDb(basePath: string): void { + const db = dbPool.get(basePath); + if (!db) return; + try { db.close(); } catch { /* swallow */ } + dbPool.delete(basePath); } // ─── Public API ────────────────────────────────────────────────────────── /** * Claim a unit for an agent. - * Overwrites any existing claim for this unit (last writer wins). + * Uses INSERT OR IGNORE for atomic first-writer-wins semantics. + * Returns true if the claim was acquired (or the same agent already owns it). + * Returns false if a different agent already owns the unit. */ -export function claimUnit(basePath: string, unitKey: string, agentName: string): void { - const claims = readClaims(basePath) ?? {}; - claims[unitKey] = { agent: agentName, claimed_at: new Date().toISOString() }; - const dir = join(basePath, ".gsd"); - mkdirSync(dir, { recursive: true }); - atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n"); +export function claimUnit(basePath: string, unitKey: string, agentName: string): boolean { + const db = getDb(basePath); + if (!db) { + // Auto-init if not already initialized (backward compat) + initOwnershipTable(basePath); + return claimUnit(basePath, unitKey, agentName); + } + + // INSERT OR IGNORE: if the row already exists, this is a no-op. + // The PRIMARY KEY constraint on unit_key prevents duplicate claims. + db.prepare( + "INSERT OR IGNORE INTO unit_claims (unit_key, agent_name, claimed_at) VALUES (?, ?, ?)", + ).run(unitKey, agentName, new Date().toISOString()); + + // Check who owns it now + const row = db.prepare("SELECT agent_name FROM unit_claims WHERE unit_key = ?").get(unitKey); + const owner = row?.agent_name as string | undefined; + + return owner === agentName; } /** - * Release a unit claim (remove it from the claims map). + * Release a unit claim (remove it from the claims table). */ export function releaseUnit(basePath: string, unitKey: string): void { - const claims = readClaims(basePath); - if (!claims || !(unitKey in claims)) return; - delete claims[unitKey]; - atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n"); + const db = getDb(basePath); + if (!db) return; + db.prepare("DELETE FROM unit_claims WHERE unit_key = ?").run(unitKey); } /** - * Get the current owner of a unit, or null if unclaimed / no claims file. + * Get the current owner of a unit, or null if unclaimed. */ export function getOwner(basePath: string, unitKey: string): string | null { - const claims = readClaims(basePath); - if (!claims) return null; - return claims[unitKey]?.agent ?? null; + const db = getDb(basePath); + if (!db) return null; + const row = db.prepare("SELECT agent_name FROM unit_claims WHERE unit_key = ?").get(unitKey); + return (row?.agent_name as string) ?? null; } /** * Check if an actor is authorized to operate on a unit. - * Returns null if ownership passes (or is unclaimed / no file). + * Returns null if ownership passes (or is unclaimed). * Returns an error string if a different agent owns the unit. */ export function checkOwnership( @@ -98,7 +269,7 @@ export function checkOwnership( ): string | null { if (!actorName) return null; // no actor identity provided — opt-in, so allow const owner = getOwner(basePath, unitKey); - if (owner === null) return null; // unit unclaimed or no claims file + if (owner === null) return null; // unit unclaimed if (owner === actorName) return null; // actor is the owner return `Unit ${unitKey} is owned by ${owner}, not ${actorName}`; } diff --git a/src/resources/extensions/gsd/validate-directory.ts b/src/resources/extensions/gsd/validate-directory.ts index 4341826c2..6923abd49 100644 --- a/src/resources/extensions/gsd/validate-directory.ts +++ b/src/resources/extensions/gsd/validate-directory.ts @@ -61,6 +61,33 @@ const WINDOWS_BLOCKED_PATHS = new Set([ "C:\\Program Files (x86)", ]); +const WINDOWS_BLOCKED_SUFFIXES = new Set([ + "\\", + "\\windows", + "\\windows\\system32", + "\\program files", + "\\program files (x86)", +]); + +function normalizePathForComparison(dirPath: string): string { + let normalized = dirPath.replace(/[/\\]+$/, ""); + if (normalized === "") { + normalized = "/"; + } else if (/^[A-Za-z]:$/.test(normalized)) { + normalized += "\\"; + } + return platform() === "win32" ? normalized.toLowerCase() : normalized; +} + +function isBlockedWindowsPath(normalized: string): boolean { + if (!/^[a-z]:\\/.test(normalized)) { + return false; + } + + const suffix = normalized.slice(2); + return WINDOWS_BLOCKED_SUFFIXES.has(suffix); +} + // ─── Core Validation ──────────────────────────────────────────────────────────── /** @@ -84,16 +111,11 @@ export function validateDirectory(dirPath: string): DirectoryValidationResult { // Normalize trailing slashes for consistent comparison. // Special cases: "/" → "/" (not ""), "C:\" → "C:\" (not "C:") - let normalized = resolved.replace(/[/\\]+$/, ""); - if (normalized === "") { - normalized = "/"; - } else if (/^[A-Za-z]:$/.test(normalized)) { - normalized = normalized + "\\"; - } + const normalized = normalizePathForComparison(resolved); // ── Check 1: Blocked system paths ────────────────────────────────────── const blockedPaths = platform() === "win32" ? WINDOWS_BLOCKED_PATHS : UNIX_BLOCKED_PATHS; - if (blockedPaths.has(normalized)) { + if (platform() === "win32" ? isBlockedWindowsPath(normalized) : blockedPaths.has(normalized)) { return { safe: false, severity: "blocked", @@ -104,9 +126,9 @@ export function validateDirectory(dirPath: string): DirectoryValidationResult { // ── Check 2: Home directory itself (not subdirs) ─────────────────────── let resolvedHome: string; try { - resolvedHome = realpathSync(resolve(homedir())).replace(/[/\\]+$/, ""); + resolvedHome = normalizePathForComparison(realpathSync(resolve(homedir()))); } catch { - resolvedHome = resolve(homedir()).replace(/[/\\]+$/, ""); + resolvedHome = normalizePathForComparison(resolve(homedir())); } if (normalized === resolvedHome) { @@ -120,9 +142,9 @@ export function validateDirectory(dirPath: string): DirectoryValidationResult { // ── Check 3: Temp directory root ─────────────────────────────────────── let resolvedTmp: string; try { - resolvedTmp = realpathSync(resolve(tmpdir())).replace(/[/\\]+$/, ""); + resolvedTmp = normalizePathForComparison(realpathSync(resolve(tmpdir()))); } catch { - resolvedTmp = resolve(tmpdir()).replace(/[/\\]+$/, ""); + resolvedTmp = normalizePathForComparison(resolve(tmpdir())); } if (normalized === resolvedTmp) { diff --git a/src/resources/extensions/gsd/verdict-parser.ts b/src/resources/extensions/gsd/verdict-parser.ts index 18794436a..b0c0826b8 100644 --- a/src/resources/extensions/gsd/verdict-parser.ts +++ b/src/resources/extensions/gsd/verdict-parser.ts @@ -20,13 +20,28 @@ import type { UatType } from "./files.js"; * Returns `undefined` when frontmatter is absent or has no `verdict` field. */ export function extractVerdict(content: string): string | undefined { + // Primary: YAML frontmatter verdict (canonical format) const fmMatch = content.match(/^---\n([\s\S]*?)\n---/); - if (!fmMatch) return undefined; - const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i); - if (!verdictMatch) return undefined; - let v = verdictMatch[1].toLowerCase(); - if (v === "passed") v = "pass"; - return v; + if (fmMatch) { + const verdictMatch = fmMatch[1].match(/verdict:\s*([\w-]+)/i); + if (verdictMatch) { + let v = verdictMatch[1].toLowerCase(); + if (v === "passed") v = "pass"; + return v; + } + return undefined; + } + + // Fallback: detect verdict in markdown body (LLM manual writes, #2960). + // Matches patterns like: **Verdict:** PASS, **Verdict:** ✅ PASS, **Verdict** needs-remediation + const bodyMatch = content.match(/\*\*Verdict:?\*\*\s*(?:✅\s*)?(\w[\w-]*)/i); + if (bodyMatch) { + let v = bodyMatch[1].toLowerCase(); + if (v === "passed") v = "pass"; + return v; + } + + return undefined; } /** diff --git a/src/resources/extensions/gsd/verification-evidence.ts b/src/resources/extensions/gsd/verification-evidence.ts index e6cf431ff..3154ff36c 100644 --- a/src/resources/extensions/gsd/verification-evidence.ts +++ b/src/resources/extensions/gsd/verification-evidence.ts @@ -52,6 +52,32 @@ export interface BrowserEvidenceJSON { duration: number; } +export interface PreExecutionCheckJSON { + /** Check category: package, file, tool, endpoint, schema */ + category: "package" | "file" | "tool" | "endpoint" | "schema"; + /** What was checked (e.g., package name, file path) */ + target: string; + /** Whether the check passed */ + passed: boolean; + /** Human-readable message explaining the result */ + message: string; + /** Whether this failure should block execution (only meaningful when passed=false) */ + blocking?: boolean; +} + +export interface PostExecutionCheckJSON { + /** Check category: import, signature, pattern */ + category: "import" | "signature" | "pattern"; + /** What was checked (e.g., file:line, function name) */ + target: string; + /** Whether the check passed */ + passed: boolean; + /** Human-readable message explaining the result */ + message: string; + /** Whether this failure should block completion (only meaningful when passed=false) */ + blocking?: boolean; +} + export interface EvidenceJSON { schemaVersion: 1; taskId: string; @@ -65,6 +91,10 @@ export interface EvidenceJSON { runtimeErrors?: RuntimeErrorJSON[]; auditWarnings?: AuditWarningJSON[]; browser?: BrowserEvidenceJSON; + /** Pre-execution checks run before task execution (package existence, file refs, etc.) */ + preExecutionChecks?: PreExecutionCheckJSON[]; + /** Post-execution checks run after task completion (import resolution, signature drift, pattern consistency) */ + postExecutionChecks?: PostExecutionCheckJSON[]; } /** @@ -124,6 +154,44 @@ export function writeVerificationJSON( writeFileSync(filePath, JSON.stringify(evidence, null, 2) + "\n", "utf-8"); } +// ─── Pre-Execution Evidence ────────────────────────────────────────────────── + +export interface PreExecutionEvidenceJSON { + schemaVersion: 1; + milestoneId: string; + sliceId: string; + timestamp: number; + status: "pass" | "warn" | "fail"; + durationMs: number; + checks: PreExecutionCheckJSON[]; +} + +/** + * Write pre-execution check results to a PRE-EXEC-VERIFY.json artifact + * in the slice directory. + */ +export function writePreExecutionEvidence( + result: { status: "pass" | "warn" | "fail"; checks: PreExecutionCheckJSON[]; durationMs: number }, + sliceDir: string, + milestoneId: string, + sliceId: string, +): void { + mkdirSync(sliceDir, { recursive: true }); + + const evidence: PreExecutionEvidenceJSON = { + schemaVersion: 1, + milestoneId, + sliceId, + timestamp: Date.now(), + status: result.status, + durationMs: result.durationMs, + checks: result.checks, + }; + + const filePath = join(sliceDir, `${sliceId}-PRE-EXEC-VERIFY.json`); + writeFileSync(filePath, JSON.stringify(evidence, null, 2) + "\n", "utf-8"); +} + // ─── Markdown Evidence Table ───────────────────────────────────────────────── /** diff --git a/src/resources/extensions/gsd/visualizer-overlay.ts b/src/resources/extensions/gsd/visualizer-overlay.ts index 68c41d81a..32a98346d 100644 --- a/src/resources/extensions/gsd/visualizer-overlay.ts +++ b/src/resources/extensions/gsd/visualizer-overlay.ts @@ -34,6 +34,24 @@ const TAB_LABELS = [ "0 Export", ]; +type TabBarEntry = { label: string; width: number }; + +function buildTabBarEntries(activeTab: number, filterText: string, capturesPendingCount?: number): TabBarEntry[] { + return TAB_LABELS.map((label, i) => { + let displayLabel = label; + if (i === activeTab && filterText) { + displayLabel += " \u2731"; + } + if (i === 8 && capturesPendingCount) { + displayLabel += ` (${capturesPendingCount})`; + } + return { + label: displayLabel, + width: visibleWidth(displayLabel) + 2, + }; + }); +} + export class GSDVisualizerOverlay { private tui: { requestRender: () => void }; private theme: Theme; @@ -116,15 +134,14 @@ export class GSDVisualizerOverlay { } handleInput(data: string): void { + if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) { + this.dispose(); + this.onClose(); + return; + } + // Filter mode input routing if (this.filterMode) { - if (matchesKey(data, Key.escape)) { - this.filterMode = false; - this.filterText = ""; - this.invalidate(); - this.tui.requestRender(); - return; - } if (matchesKey(data, Key.enter)) { this.filterMode = false; this.invalidate(); @@ -179,8 +196,9 @@ export class GSDVisualizerOverlay { // Left click — check if on tab bar row if (mouse.y === 2) { let xPos = 3; - for (let i = 0; i < TAB_LABELS.length; i++) { - const tabWidth = TAB_LABELS[i].length + 2; + const tabs = buildTabBarEntries(this.activeTab, this.filterText, this.data?.captures?.pendingCount); + for (let i = 0; i < tabs.length; i++) { + const tabWidth = tabs[i]!.width; if (mouse.x >= xPos && mouse.x < xPos + tabWidth) { this.activeTab = i; this.invalidate(); @@ -194,12 +212,6 @@ export class GSDVisualizerOverlay { return; } - if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) { - this.dispose(); - this.onClose(); - return; - } - if (matchesKey(data, Key.shift("tab"))) { this.activeTab = (this.activeTab - 1 + TAB_COUNT) % TAB_COUNT; this.invalidate(); @@ -442,20 +454,12 @@ export class GSDVisualizerOverlay { const content: string[] = []; // Tab bar - const tabs = TAB_LABELS.map((label, i) => { - let displayLabel = label; - // Show filter indicator on active tab with filter - if (i === this.activeTab && this.filterText) { - displayLabel += " \u2731"; - } - // Show captures badge - if (i === 8 && this.data?.captures?.pendingCount) { - displayLabel += ` (${this.data.captures.pendingCount})`; - } + const tabEntries = buildTabBarEntries(this.activeTab, this.filterText, this.data?.captures?.pendingCount); + const tabs = tabEntries.map((entry, i) => { if (i === this.activeTab) { - return th.fg("accent", `[${displayLabel}]`); + return th.fg("accent", `[${entry.label}]`); } - return th.fg("dim", `[${displayLabel}]`); + return th.fg("dim", `[${entry.label}]`); }); content.push(" " + tabs.join(" ")); content.push(""); diff --git a/src/resources/extensions/gsd/watch/header-renderer.ts b/src/resources/extensions/gsd/watch/header-renderer.ts new file mode 100644 index 000000000..27d84f9aa --- /dev/null +++ b/src/resources/extensions/gsd/watch/header-renderer.ts @@ -0,0 +1,275 @@ +// GSD Watch — Header renderer: ASCII logo, session info, MCP status, remote questions +// Copyright (c) 2026 Jeremy McSpadden + +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; +import { visibleWidth, truncateToWidth } from "@gsd/pi-tui"; +import { loadEffectiveGSDPreferences } from "../preferences.js"; + +// ─── Constants ──────────────────────────────────────────────────────────────── + +/** + * GSD ASCII logo — inlined here because the canonical src/logo.ts is outside + * the resources rootDir and cannot be imported directly. + */ +const GSD_LOGO: readonly string[] = [ + ' ██████╗ ███████╗██████╗ ', + ' ██╔════╝ ██╔════╝██╔══██╗', + ' ██║ ███╗███████╗██║ ██║', + ' ██║ ██║╚════██║██║ ██║', + ' ╚██████╔╝███████║██████╔╝', + ' ╚═════╝ ╚══════╝╚═════╝ ', +]; + +/** Separator character for the horizontal divider line. */ +const SEPARATOR_CHAR = "─"; + +/** Vertical bar between logo and info panel. */ +const PANEL_DIVIDER = "│"; + +/** Label column width for Model/Provider/Directory/Branch rows. */ +const LABEL_COL_WIDTH = 10; + +// ─── Data Readers ───────────────────────────────────────────────────────────── + +/** + * Read the configured execution model from GSD preferences. + * Falls back through execution -> planning -> research -> first found. + * Returns "default" if nothing is configured. + */ +export function readModelFromPreferences(): string { + try { + const prefs = loadEffectiveGSDPreferences(); + if (!prefs?.preferences.models) return "default"; + const m = prefs.preferences.models as Record; + // Try common phases in priority order + for (const phase of ["execution", "planning", "research", "discuss", "subagent"]) { + const val = m[phase]; + if (typeof val === "string") return val; + if (val && typeof val === "object" && "model" in val) { + const model = (val as { model: string }).model; + if (typeof model === "string") return model; + } + } + } catch { + // Non-fatal + } + return "default"; +} + +/** + * Derive provider name from model ID prefix. + */ +export function deriveProvider(modelId: string): string { + if (modelId.startsWith("claude")) return "anthropic"; + if (modelId.startsWith("gpt") || modelId.startsWith("o1") || modelId.startsWith("o3")) return "openai"; + if (modelId.startsWith("gemini")) return "google"; + if (modelId.startsWith("deepseek")) return "deepseek"; + if (modelId === "default") return "anthropic"; + return "unknown"; +} + +/** + * Shorten a directory path by replacing the home directory with ~. + */ +export function shortenPath(fullPath: string): string { + const home = homedir(); + if (fullPath.startsWith(home)) { + return "~" + fullPath.slice(home.length); + } + return fullPath; +} + +/** + * Read the current git branch name. Returns "unknown" on failure. + */ +export function readGitBranch(projectRoot: string): string { + try { + return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { + cwd: projectRoot, + encoding: "utf-8", + timeout: 2000, + }).trim(); + } catch { + return "unknown"; + } +} + +/** + * Read MCP server names from .mcp.json or .gsd/mcp.json. + * Returns array of server name strings. + */ +export function readMcpServerNames(projectRoot: string): string[] { + const configPaths = [ + join(projectRoot, ".mcp.json"), + join(projectRoot, ".gsd", "mcp.json"), + ]; + const names: string[] = []; + const seen = new Set(); + + for (const configPath of configPaths) { + try { + if (!existsSync(configPath)) continue; + const raw = readFileSync(configPath, "utf-8"); + const data = JSON.parse(raw) as Record; + const mcpServers = (data.mcpServers ?? data.servers) as + | Record + | undefined; + if (!mcpServers || typeof mcpServers !== "object") continue; + for (const name of Object.keys(mcpServers)) { + if (!seen.has(name)) { + seen.add(name); + names.push(name); + } + } + } catch { + // Non-fatal + } + } + + return names; +} + +// ─── Header Layout ──────────────────────────────────────────────────────────── + +export interface HeaderData { + model: string; + provider: string; + directory: string; + branch: string; + mcpServers: string[]; +} + +/** + * Gather all header data from filesystem and preferences. + */ +export function gatherHeaderData(projectRoot: string): HeaderData { + const model = readModelFromPreferences(); + const provider = deriveProvider(model); + const directory = shortenPath(projectRoot); + const branch = readGitBranch(projectRoot); + const mcpServers = readMcpServerNames(projectRoot); + + return { model, provider, directory, branch, mcpServers }; +} + +/** + * Build an info panel line: "Label value" with proper padding. + * Returns empty string if value is empty. + */ +function formatInfoLine(label: string, value: string, availableWidth: number): string { + const bold = `\x1b[1m${label}\x1b[0m`; + const labelVis = visibleWidth(bold); + const padding = " ".repeat(Math.max(1, LABEL_COL_WIDTH - labelVis)); + const maxValueWidth = Math.max(1, availableWidth - LABEL_COL_WIDTH); + const truncValue = truncateToWidth(value, maxValueWidth, "…"); + return bold + padding + truncValue; +} + +/** + * Format MCP server names as a dot-separated row with checkmarks. + * e.g. "Brave ✓ · Answers ✓ · Context7 ✓" + */ +export function formatMcpRow(servers: string[], width: number): string { + if (servers.length === 0) return ""; + + // Capitalize first letter of each server name + const items = servers.map(s => { + const cap = s.charAt(0).toUpperCase() + s.slice(1); + return `${cap} ✓`; + }); + + const full = items.join(" · "); + if (visibleWidth(full) <= width) return full; + + // Truncate if too wide + return truncateToWidth(full, width, "…"); +} + +/** + * Render the full header as an array of terminal-safe strings. + * + * Layout: GSD ASCII logo on the left, info panel on the right separated by │. + * Below: MCP server row, remote questions row, separator line. + */ +export function renderHeaderLines(data: HeaderData, width: number): string[] { + const lines: string[] = []; + + // Logo is 6 lines tall. Info panel has: title + blank + model + provider + directory + branch = 6 lines + const logoLines = GSD_LOGO; + const logoWidth = Math.max(...logoLines.map(l => visibleWidth(l))); + + // Calculate available width for the info panel + // Layout: logo + " " + "│" + " " = logoWidth + 3 + const dividerOverhead = 3; // " │ " + const infoPanelWidth = width - logoWidth - dividerOverhead; + + // If terminal is too narrow for side-by-side, fall back to stacked layout + if (infoPanelWidth < 20) { + return renderStackedHeader(data, width); + } + + // Build info panel lines (6 lines to match logo height) + const infoLines: string[] = [ + `\x1b[1mGet Shit Done\x1b[0m`, + "", + formatInfoLine("Model", data.model, infoPanelWidth), + formatInfoLine("Provider", data.provider, infoPanelWidth), + formatInfoLine("Directory", data.directory, infoPanelWidth), + formatInfoLine("Branch", data.branch, infoPanelWidth), + ]; + + // Merge logo and info panel side by side + const maxLines = Math.max(logoLines.length, infoLines.length); + for (let i = 0; i < maxLines; i++) { + const logoLine = i < logoLines.length ? logoLines[i] : ""; + const infoLine = i < infoLines.length ? infoLines[i] : ""; + + // Pad logo line to consistent width + const logoPad = " ".repeat(Math.max(0, logoWidth - visibleWidth(logoLine))); + lines.push(`${logoLine}${logoPad} ${PANEL_DIVIDER} ${infoLine}`); + } + + // Blank line after logo+info block + lines.push(""); + + // MCP server row + const mcpRow = formatMcpRow(data.mcpServers, width); + if (mcpRow) { + lines.push(` ${mcpRow}`); + } + + // Separator line + lines.push(SEPARATOR_CHAR.repeat(width)); + + return lines; +} + +/** + * Fallback stacked layout for narrow terminals (< 20 cols for info panel). + */ +function renderStackedHeader(data: HeaderData, width: number): string[] { + const lines: string[] = []; + + // Title + lines.push(`\x1b[1mGet Shit Done\x1b[0m`); + lines.push(""); + + // Info + lines.push(formatInfoLine("Model", data.model, width)); + lines.push(formatInfoLine("Provider", data.provider, width)); + lines.push(formatInfoLine("Directory", data.directory, width)); + lines.push(formatInfoLine("Branch", data.branch, width)); + lines.push(""); + + // MCP + const mcpRow = formatMcpRow(data.mcpServers, width); + if (mcpRow) lines.push(` ${mcpRow}`); + + // Separator + lines.push(SEPARATOR_CHAR.repeat(width)); + + return lines; +} diff --git a/src/resources/extensions/gsd/workflow-events.ts b/src/resources/extensions/gsd/workflow-events.ts index 87bac5efb..40bdab31f 100644 --- a/src/resources/extensions/gsd/workflow-events.ts +++ b/src/resources/extensions/gsd/workflow-events.ts @@ -2,6 +2,8 @@ import { createHash, randomUUID } from "node:crypto"; import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs"; import { join } from "node:path"; import { atomicWriteSync } from "./atomic-write.js"; +import { withFileLockSync } from "./file-lock.js"; +import { logWarning } from "./workflow-logger.js"; // ─── Session ID ─────────────────────────────────────────────────────────── @@ -18,10 +20,11 @@ export function getSessionId(): string { // ─── Event Types ───────────────────────────────────────────────────────── export interface WorkflowEvent { - cmd: string; // e.g. "complete_task" + v?: number; // schema version — omitted in v1 (legacy), 2 for current format + cmd: string; // e.g. "complete-task" (canonical: hyphens; legacy: underscores — both accepted by replay) params: Record; - ts: string; // ISO 8601 - hash: string; // content hash (hex, 16 chars) + ts: string; // ISO 8601 + hash: string; // content hash (hex, 16 chars) actor: "agent" | "system"; actor_name?: string; // e.g. "executor-agent-01" — caller-provided identity trigger_reason?: string; // e.g. "plan-phase complete" — caller-provided causation @@ -45,6 +48,7 @@ export function appendEvent( .slice(0, 16); const fullEvent: WorkflowEvent = { + v: 2, ...event, hash, session_id: ENGINE_SESSION_ID, @@ -74,7 +78,7 @@ export function readEvents(logPath: string): WorkflowEvent[] { try { events.push(JSON.parse(line) as WorkflowEvent); } catch { - process.stderr.write(`workflow-events: skipping corrupted event line: ${line.slice(0, 80)}\n`); + logWarning("event-log", `skipping corrupted event line (${line.length} bytes)`); } } @@ -124,31 +128,39 @@ export function compactMilestoneEvents( const logPath = join(basePath, ".gsd", "event-log.jsonl"); const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`); - const allEvents = readEvents(logPath); - const toArchive = allEvents.filter( - (e) => (e.params as { milestoneId?: string }).milestoneId === milestoneId, - ); - const remaining = allEvents.filter( - (e) => (e.params as { milestoneId?: string }).milestoneId !== milestoneId, - ); + return withFileLockSync(logPath, () => { + const allEvents = readEvents(logPath); + + // Single-pass partition to halve the work (per reviewer agent) + const toArchive: WorkflowEvent[] = []; + const remaining: WorkflowEvent[] = []; + + for (const e of allEvents) { + if ((e.params as { milestoneId?: string }).milestoneId === milestoneId) { + toArchive.push(e); + } else { + remaining.push(e); + } + } - if (toArchive.length === 0) { - return { archived: 0 }; - } + if (toArchive.length === 0) { + return { archived: 0 }; + } - // Write archived events to .jsonl.archived file (crash-safe) - atomicWriteSync( - archivePath, - toArchive.map((e) => JSON.stringify(e)).join("\n") + "\n", - ); + // Write archived events to .jsonl.archived file (crash-safe) + atomicWriteSync( + archivePath, + toArchive.map((e) => JSON.stringify(e)).join("\n") + "\n", + ); - // Truncate active log to remaining events only - atomicWriteSync( - logPath, - remaining.length > 0 - ? remaining.map((e) => JSON.stringify(e)).join("\n") + "\n" - : "", - ); + // Truncate active log to remaining events only + atomicWriteSync( + logPath, + remaining.length > 0 + ? remaining.map((e) => JSON.stringify(e)).join("\n") + "\n" + : "", + ); - return { archived: toArchive.length }; + return { archived: toArchive.length }; + }); } diff --git a/src/resources/extensions/gsd/workflow-logger.ts b/src/resources/extensions/gsd/workflow-logger.ts index 0770408d0..cdff396a3 100644 --- a/src/resources/extensions/gsd/workflow-logger.ts +++ b/src/resources/extensions/gsd/workflow-logger.ts @@ -2,7 +2,9 @@ // Centralized warning/error accumulator for the workflow engine pipeline. // Captures structured entries that the auto-loop can drain after each unit // to surface root causes for stuck loops, silent degradation, and blocked writes. -// All entries are also persisted to .gsd/audit-log.jsonl for post-mortem analysis. +// Error-severity entries are persisted to .gsd/audit-log.jsonl (sanitized) for +// post-mortem analysis. Warnings are ephemeral (stderr + buffer only) to avoid +// log amplification from expected-control-flow catch paths. // // Stderr policy: every logWarning/logError call writes immediately to stderr // for terminal visibility. This is intentional — unlike debug-logger (which is @@ -17,6 +19,8 @@ import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs"; import { join } from "node:path"; +import { appendNotification } from "./notification-store.js"; + // ─── Types ────────────────────────────────────────────────────────────── export type LogSeverity = "warn" | "error"; @@ -31,7 +35,23 @@ export type LogComponent = | "state" // deriveState fallback/degradation | "tool" // Tool handler errors | "compaction" // Event compaction - | "reconcile"; // Worktree reconciliation + | "reconcile" // Worktree reconciliation + | "db" // Database operations (gsd-db) + | "dispatch" // Auto-dispatch rule evaluation + | "recovery" // Auto-recovery and timeout recovery + | "session" // Session lock and session state I/O + | "prompt" // Prompt construction and context injection + | "dashboard" // Auto-dashboard rendering + | "timer" // Auto-timers (idle watchdog, hard timeout) + | "worktree" // Worktree lifecycle (create, sync, merge) + | "command" // Slash command execution and maintenance + | "parallel" // Parallel orchestrator and merge + | "fs" // Safe filesystem operations + | "bootstrap" // Extension bootstrap (system-context, agent-end) + | "guided" // Guided flow (discuss, plan wizards) + | "registry" // Rule registry hook state + | "renderer" // Markdown renderer and projections + | "safety"; // LLM safety harness export interface LogEntry { ts: string; @@ -47,6 +67,7 @@ export interface LogEntry { const MAX_BUFFER = 100; let _buffer: LogEntry[] = []; let _auditBasePath: string | null = null; +let _stderrEnabled = true; /** * Set the base path for persistent audit log writes. @@ -57,6 +78,16 @@ export function setLogBasePath(basePath: string): void { _auditBasePath = basePath; } +/** + * Enable or disable immediate stderr writes for workflow logs. + * Returns the previous setting so callers can restore it. + */ +export function setStderrLoggingEnabled(enabled: boolean): boolean { + const previous = _stderrEnabled; + _stderrEnabled = enabled; + return previous; +} + // ─── Public API ───────────────────────────────────────────────────────── /** @@ -157,17 +188,22 @@ export function summarizeLogs(): string | null { /** * Format entries for display (used by auto-loop post-unit notification). - * Note: context fields are not included in the formatted output. + * Includes key context fields (file paths, commands) when present. */ export function formatForNotification(entries: readonly LogEntry[]): string { if (entries.length === 0) return ""; - if (entries.length === 1) { - const e = entries[0]; - return `[${e.component}] ${e.message}`; - } - return entries - .map((e) => `[${e.component}] ${e.message}`) - .join("\n"); + return entries.map((e) => { + let line = `[${e.component}] ${e.message}`; + if (e.context) { + const ctxParts = Object.entries(e.context) + .filter(([k]) => k !== "error") // error is redundant with message + .map(([k, v]) => v.includes(",") ? `${k}: "${v}"` : `${k}: ${v}`); + if (ctxParts.length > 0) { + line += ` (${ctxParts.join(", ")})`; + } + } + return line; + }).join("\n"); } /** @@ -220,7 +256,18 @@ function _push( // Always forward to stderr so terminal watchers see it (see module header for policy) const prefix = severity === "error" ? "ERROR" : "WARN"; const ctxStr = context ? ` ${JSON.stringify(context)}` : ""; - process.stderr.write(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`); + _writeStderr(`[gsd:${component}] ${prefix}: ${message}${ctxStr}\n`); + + // Persist to notification store (both warnings and errors) + try { + appendNotification( + `[${component}] ${message}`, + severity === "error" ? "error" : "warning", + "workflow-logger", + ); + } catch (notifErr) { + _writeStderr(`[gsd:workflow-logger] notification-store append failed: ${(notifErr as Error).message}\n`); + } // Buffer for auto-loop to drain _buffer.push(entry); @@ -228,15 +275,52 @@ function _push( _buffer.shift(); } - // Persist to .gsd/audit-log.jsonl so entries survive context resets - if (_auditBasePath) { + // Persist errors to .gsd/audit-log.jsonl so they survive context resets. + // Only error-severity entries are persisted — warnings are ephemeral (stderr + buffer) + // to avoid log amplification from expected-control-flow catch paths. + if (_auditBasePath && severity === "error") { try { const auditDir = join(_auditBasePath, ".gsd"); mkdirSync(auditDir, { recursive: true }); - appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(entry) + "\n", "utf-8"); + const sanitized = _sanitizeForAudit(entry); + appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8"); } catch (auditErr) { // Best-effort — never let audit write failures bubble up - process.stderr.write(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`); + _writeStderr(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`); } } } + +function _writeStderr(message: string): void { + if (!_stderrEnabled) return; + process.stderr.write(message); +} + +/** + * Sanitize a log entry before persisting to the audit JSONL file. + * Strips potentially sensitive context (raw paths, cwd, full error text) + * to avoid leaking local environment details into durable telemetry. + */ +function _sanitizeForAudit(entry: LogEntry): LogEntry { + const sanitized: LogEntry = { + ts: entry.ts, + severity: entry.severity, + component: entry.component, + // Truncate message to avoid persisting oversized raw error dumps + message: entry.message.length > 200 ? entry.message.slice(0, 200) + "…[truncated]" : entry.message, + }; + if (entry.context) { + // Allowlist: only persist known-safe structured keys + const SAFE_KEYS = new Set(["fn", "tool", "mid", "sid", "tid", "worktree", "id", "error", "count"]); + const filtered: Record = {}; + for (const [k, v] of Object.entries(entry.context)) { + if (SAFE_KEYS.has(k)) { + filtered[k] = v; + } + } + if (Object.keys(filtered).length > 0) { + sanitized.context = filtered; + } + } + return sanitized; +} diff --git a/src/resources/extensions/gsd/workflow-manifest.ts b/src/resources/extensions/gsd/workflow-manifest.ts index d88dda8e9..3d6af0327 100644 --- a/src/resources/extensions/gsd/workflow-manifest.ts +++ b/src/resources/extensions/gsd/workflow-manifest.ts @@ -42,6 +42,23 @@ function requireDb() { return db; } +/** + * Coerce a raw DB value to a number, returning `fallback` for + * null/undefined/non-numeric strings (e.g. "-", "N/A", ""). + * SQLite can store TEXT in INTEGER columns after migrations or manual inserts. + */ +export function toNumeric(value: unknown, fallback: number | null = null): number | null { + if (value === null || value === undefined) return fallback; + if (typeof value === "number") return Number.isFinite(value) ? value : fallback; + if (typeof value === "string") { + const trimmed = value.trim(); + if (trimmed === "" || trimmed === "-" || trimmed === "N/A") return fallback; + const n = Number(trimmed); + return Number.isFinite(n) ? n : fallback; + } + return fallback; +} + // ─── snapshotState ─────────────────────────────────────────────────────── /** @@ -99,7 +116,7 @@ export function snapshotState(): StateManifest { proof_level: (r["proof_level"] as string) ?? "", integration_closure: (r["integration_closure"] as string) ?? "", observability_impact: (r["observability_impact"] as string) ?? "", - sequence: (r["sequence"] as number) ?? 0, + sequence: toNumeric(r["sequence"], 0) as number, replan_triggered_at: (r["replan_triggered_at"] as string) ?? null, })); @@ -129,12 +146,12 @@ export function snapshotState(): StateManifest { expected_output: JSON.parse((r["expected_output"] as string) || "[]"), observability_impact: (r["observability_impact"] as string) ?? "", full_plan_md: (r["full_plan_md"] as string) ?? "", - sequence: (r["sequence"] as number) ?? 0, + sequence: toNumeric(r["sequence"], 0) as number, })); const rawDecisions = db.prepare("SELECT * FROM decisions ORDER BY seq").all() as Record[]; const decisions: Decision[] = rawDecisions.map((r) => ({ - seq: r["seq"] as number, + seq: toNumeric(r["seq"], 0) as number, id: r["id"] as string, when_context: (r["when_context"] as string) ?? "", scope: (r["scope"] as string) ?? "", @@ -153,9 +170,9 @@ export function snapshotState(): StateManifest { slice_id: r["slice_id"] as string, milestone_id: r["milestone_id"] as string, command: r["command"] as string, - exit_code: (r["exit_code"] as number) ?? null, + exit_code: toNumeric(r["exit_code"]), verdict: (r["verdict"] as string) ?? "", - duration_ms: (r["duration_ms"] as number) ?? null, + duration_ms: toNumeric(r["duration_ms"]), created_at: r["created_at"] as string, })); diff --git a/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts b/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts new file mode 100644 index 000000000..1d69ebc00 --- /dev/null +++ b/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts @@ -0,0 +1,76 @@ +import type { ExtensionContext } from "@gsd/pi-coding-agent"; + +import { + type EnsureProjectWorkflowMcpConfigResult, + ensureProjectWorkflowMcpConfig, +} from "./mcp-project-config.js"; +import { usesWorkflowMcpTransport } from "./workflow-mcp.js"; + +interface WorkflowMcpAutoPrepContext { + model?: { provider?: string; baseUrl?: string }; + modelRegistry?: { + getProviderAuthMode?: (provider: string) => string; + isProviderRequestReady?: (provider: string) => boolean; + }; + ui?: Pick; +} + +function getAuthModeSafe( + ctx: WorkflowMcpAutoPrepContext, + provider: string | undefined, +): string | undefined { + if (!provider) return undefined; + const getAuthMode = ctx.modelRegistry?.getProviderAuthMode; + if (typeof getAuthMode !== "function") return undefined; + try { + return getAuthMode(provider); + } catch { + return undefined; + } +} + +function hasClaudeCodeProvider(ctx: WorkflowMcpAutoPrepContext): boolean { + return getAuthModeSafe(ctx, "claude-code") === "externalCli"; +} + +function isClaudeCodeProviderReady(ctx: WorkflowMcpAutoPrepContext): boolean { + const readyCheck = ctx.modelRegistry?.isProviderRequestReady; + if (typeof readyCheck !== "function") return false; + try { + return readyCheck("claude-code"); + } catch { + return false; + } +} + +export function shouldAutoPrepareWorkflowMcp(ctx: WorkflowMcpAutoPrepContext): boolean { + const provider = ctx.model?.provider; + const baseUrl = ctx.model?.baseUrl; + const authMode = getAuthModeSafe(ctx, provider); + + if (usesWorkflowMcpTransport(authMode as any, baseUrl)) return true; + if (provider === "claude-code") return true; + if (hasClaudeCodeProvider(ctx)) return true; + return isClaudeCodeProviderReady(ctx); +} + +export function prepareWorkflowMcpForProject( + ctx: WorkflowMcpAutoPrepContext, + projectRoot: string, +): EnsureProjectWorkflowMcpConfigResult | null { + if (!shouldAutoPrepareWorkflowMcp(ctx)) return null; + + try { + const result = ensureProjectWorkflowMcpConfig(projectRoot); + if (result.status !== "unchanged") { + ctx.ui?.notify?.(`Claude Code MCP prepared at ${result.configPath}`, "info"); + } + return result; + } catch (err) { + ctx.ui?.notify?.( + `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root.`, + "warning", + ); + return null; + } +} diff --git a/src/resources/extensions/gsd/workflow-mcp.ts b/src/resources/extensions/gsd/workflow-mcp.ts new file mode 100644 index 000000000..9e4bb90c7 --- /dev/null +++ b/src/resources/extensions/gsd/workflow-mcp.ts @@ -0,0 +1,389 @@ +import { execSync } from "node:child_process"; +import { existsSync } from "node:fs"; +import { dirname, resolve } from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; + +export interface WorkflowMcpLaunchConfig { + name: string; + command: string; + args?: string[]; + cwd?: string; + env?: Record; +} + +export interface WorkflowCapabilityOptions { + projectRoot?: string; + env?: NodeJS.ProcessEnv; + surface?: string; + unitType?: string; + authMode?: "apiKey" | "oauth" | "externalCli" | "none"; + baseUrl?: string; +} + +const MCP_WORKFLOW_TOOL_SURFACE = new Set([ + "ask_user_questions", + "gsd_decision_save", + "gsd_complete_milestone", + "gsd_complete_task", + "gsd_complete_slice", + "gsd_generate_milestone_id", + "gsd_journal_query", + "gsd_milestone_complete", + "gsd_milestone_generate_id", + "gsd_milestone_status", + "gsd_milestone_validate", + "gsd_plan_task", + "gsd_plan_milestone", + "gsd_plan_slice", + "gsd_replan_slice", + "gsd_reassess_roadmap", + "gsd_requirement_save", + "gsd_requirement_update", + "gsd_roadmap_reassess", + "gsd_save_decision", + "gsd_save_gate_result", + "gsd_save_requirement", + "gsd_skip_slice", + "gsd_slice_replan", + "gsd_slice_complete", + "gsd_summary_save", + "gsd_task_plan", + "gsd_task_complete", + "gsd_update_requirement", + "gsd_validate_milestone", +]); + +function parseLookupOutput(output: Buffer | string): string { + return output + .toString() + .trim() + .split(/\r?\n/)[0] ?? ""; +} + +function parseJsonEnv(env: NodeJS.ProcessEnv, name: string): T | undefined { + const raw = env[name]; + if (!raw) return undefined; + try { + return JSON.parse(raw) as T; + } catch { + throw new Error(`Invalid JSON in ${name}`); + } +} + +function lookupCommand(command: string, platform: NodeJS.Platform = process.platform): string | null { + const lookup = platform === "win32" ? `where ${command}` : `which ${command}`; + try { + const resolved = parseLookupOutput(execSync(lookup, { timeout: 5_000, stdio: "pipe" })); + return resolved || null; + } catch { + return null; + } +} + +function findWorkflowCliFromAncestorPath(startPath: string): string | null { + let current = resolve(startPath); + + while (true) { + const candidate = resolve(current, "packages", "mcp-server", "dist", "cli.js"); + if (existsSync(candidate)) return candidate; + + const parent = dirname(current); + if (parent === current) break; + current = parent; + } + + return null; +} + +function getBundledWorkflowMcpCliPath(env: NodeJS.ProcessEnv): string | null { + const envAnchors = [ + env.GSD_BIN_PATH?.trim(), + env.GSD_CLI_PATH?.trim(), + env.GSD_WORKFLOW_PATH?.trim(), + ].filter((value): value is string => typeof value === "string" && value.length > 0); + + for (const anchor of envAnchors) { + const candidate = findWorkflowCliFromAncestorPath(anchor); + if (candidate) return candidate; + } + + const candidates = [ + resolve(fileURLToPath(new URL("../../../../packages/mcp-server/src/cli.ts", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../../packages/mcp-server/src/cli.ts", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../packages/mcp-server/dist/cli.js", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../../packages/mcp-server/dist/cli.js", import.meta.url))), + ]; + + for (const bundledCli of candidates) { + if (existsSync(bundledCli)) return bundledCli; + } + + return null; +} + +function getBundledWorkflowExecutorModulePath(): string | null { + const candidates = [ + resolve(fileURLToPath(new URL("./tools/workflow-tool-executors.js", import.meta.url))), + resolve(fileURLToPath(new URL("./tools/workflow-tool-executors.ts", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../dist/resources/extensions/gsd/tools/workflow-tool-executors.js", import.meta.url))), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + return null; +} + +function getBundledWorkflowWriteGateModulePath(): string | null { + const candidates = [ + resolve(fileURLToPath(new URL("./bootstrap/write-gate.js", import.meta.url))), + resolve(fileURLToPath(new URL("./bootstrap/write-gate.ts", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../dist/resources/extensions/gsd/bootstrap/write-gate.js", import.meta.url))), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + return null; +} + +function getResolveTsHookPath(): string | null { + const candidates = [ + resolve(fileURLToPath(new URL("./tests/resolve-ts.mjs", import.meta.url))), + resolve(fileURLToPath(new URL("../../../../src/resources/extensions/gsd/tests/resolve-ts.mjs", import.meta.url))), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + return null; +} + +function mergeNodeOptions(existing: string | undefined, additions: string[]): string | undefined { + const tokens = (existing ?? "").split(/\s+/).map((value) => value.trim()).filter(Boolean); + for (const addition of additions) { + if (!tokens.includes(addition)) { + tokens.push(addition); + } + } + return tokens.length > 0 ? tokens.join(" ") : undefined; +} + +function buildWorkflowLaunchEnv( + projectRoot: string, + gsdCliPath: string | undefined, + explicitEnv?: Record, + workflowCliPath?: string, +): Record { + const executorModulePath = getBundledWorkflowExecutorModulePath(); + const writeGateModulePath = getBundledWorkflowWriteGateModulePath(); + const resolveTsHookPath = getResolveTsHookPath(); + const wantsSourceTs = + Boolean(resolveTsHookPath) && + ( + (workflowCliPath?.endsWith(".ts") ?? false) || + (executorModulePath?.endsWith(".ts") ?? false) || + (writeGateModulePath?.endsWith(".ts") ?? false) + ); + const nodeOptions = wantsSourceTs + ? mergeNodeOptions(explicitEnv?.NODE_OPTIONS, [ + "--experimental-strip-types", + `--import=${pathToFileURL(resolveTsHookPath!).href}`, + ]) + : explicitEnv?.NODE_OPTIONS; + + return { + ...(explicitEnv ?? {}), + ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}), + ...(executorModulePath ? { GSD_WORKFLOW_EXECUTORS_MODULE: executorModulePath } : {}), + ...(writeGateModulePath ? { GSD_WORKFLOW_WRITE_GATE_MODULE: writeGateModulePath } : {}), + ...(nodeOptions ? { NODE_OPTIONS: nodeOptions } : {}), + GSD_PERSIST_WRITE_GATE_STATE: "1", + GSD_WORKFLOW_PROJECT_ROOT: projectRoot, + }; +} + +export function detectWorkflowMcpLaunchConfig( + projectRoot = process.cwd(), + env: NodeJS.ProcessEnv = process.env, +): WorkflowMcpLaunchConfig | null { + const name = env.GSD_WORKFLOW_MCP_NAME?.trim() || "gsd-workflow"; + const explicitCommand = env.GSD_WORKFLOW_MCP_COMMAND?.trim(); + const explicitArgs = parseJsonEnv(env, "GSD_WORKFLOW_MCP_ARGS"); + const explicitEnv = parseJsonEnv>(env, "GSD_WORKFLOW_MCP_ENV"); + const explicitCwd = env.GSD_WORKFLOW_MCP_CWD?.trim(); + const gsdCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim(); + const workflowProjectRoot = + explicitEnv?.GSD_WORKFLOW_PROJECT_ROOT?.trim() || + env.GSD_WORKFLOW_PROJECT_ROOT?.trim() || + env.GSD_PROJECT_ROOT?.trim() || + explicitCwd || + projectRoot; + const resolvedWorkflowProjectRoot = resolve(workflowProjectRoot); + + if (explicitCommand) { + const launchEnv = buildWorkflowLaunchEnv(resolve(workflowProjectRoot), gsdCliPath, explicitEnv); + return { + name, + command: explicitCommand, + args: Array.isArray(explicitArgs) && explicitArgs.length > 0 ? explicitArgs.map(String) : undefined, + cwd: explicitCwd || undefined, + env: Object.keys(launchEnv).length > 0 ? launchEnv : undefined, + }; + } + + const distCli = resolve(resolvedWorkflowProjectRoot, "packages", "mcp-server", "dist", "cli.js"); + if (existsSync(distCli)) { + return { + name, + command: process.execPath, + args: [distCli], + cwd: resolvedWorkflowProjectRoot, + env: buildWorkflowLaunchEnv(resolvedWorkflowProjectRoot, gsdCliPath, undefined, distCli), + }; + } + + const bundledCli = getBundledWorkflowMcpCliPath(env); + if (bundledCli) { + return { + name, + command: process.execPath, + args: [bundledCli], + cwd: resolvedWorkflowProjectRoot, + env: buildWorkflowLaunchEnv(resolvedWorkflowProjectRoot, gsdCliPath, undefined, bundledCli), + }; + } + + const binPath = lookupCommand("gsd-mcp-server"); + if (binPath) { + return { + name, + command: binPath, + env: buildWorkflowLaunchEnv(resolvedWorkflowProjectRoot, gsdCliPath), + }; + } + + return null; +} + +export function buildWorkflowMcpServers( + projectRoot = process.cwd(), + env: NodeJS.ProcessEnv = process.env, +): Record> | undefined { + const launch = detectWorkflowMcpLaunchConfig(projectRoot, env); + if (!launch) return undefined; + + return { + [launch.name]: { + command: launch.command, + ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}), + ...(launch.env ? { env: launch.env } : {}), + ...(launch.cwd ? { cwd: launch.cwd } : {}), + }, + }; +} + +export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[] { + switch (unitType) { + case "discuss-milestone": + return ["gsd_summary_save", "gsd_plan_milestone"]; + case "discuss-slice": + return ["gsd_summary_save"]; + case "research-milestone": + case "research-slice": + return ["gsd_summary_save"]; + case "plan-milestone": + return ["gsd_plan_milestone"]; + case "plan-slice": + return ["gsd_plan_slice"]; + case "execute-task": + return ["gsd_task_complete"]; + case "complete-slice": + return ["gsd_slice_complete"]; + default: + return []; + } +} + +export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[] { + switch (unitType) { + case "discuss-milestone": + return ["gsd_summary_save", "gsd_plan_milestone"]; + case "research-milestone": + case "research-slice": + case "run-uat": + return ["gsd_summary_save"]; + case "plan-milestone": + return ["gsd_plan_milestone"]; + case "plan-slice": + return ["gsd_plan_slice"]; + case "execute-task": + case "execute-task-simple": + case "reactive-execute": + return ["gsd_complete_task"]; + case "complete-slice": + return ["gsd_complete_slice"]; + case "replan-slice": + return ["gsd_replan_slice"]; + case "reassess-roadmap": + return ["gsd_milestone_status", "gsd_reassess_roadmap"]; + case "gate-evaluate": + return ["gsd_save_gate_result"]; + case "validate-milestone": + return ["gsd_milestone_status", "gsd_validate_milestone"]; + case "complete-milestone": + return ["gsd_milestone_status", "gsd_complete_milestone"]; + default: + return []; + } +} + +export function usesWorkflowMcpTransport( + authMode: WorkflowCapabilityOptions["authMode"], + baseUrl: string | undefined, +): boolean { + return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://"); +} + +export function supportsStructuredQuestions( + activeTools: string[], + options: Pick = {}, +): boolean { + if (!activeTools.includes("ask_user_questions")) return false; + + // Workflow MCP currently exposes ask_user_questions via MCP form elicitation. + // Local external CLI transports such as Claude Code can invoke the tool, but + // do not reliably complete that elicitation round-trip yet, so guided discuss + // prompts must fall back to plain-text questioning. + if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) return false; + + return true; +} + +export function getWorkflowTransportSupportError( + provider: string | undefined, + requiredTools: string[], + options: WorkflowCapabilityOptions = {}, +): string | null { + if (!provider || requiredTools.length === 0) return null; + if (!usesWorkflowMcpTransport(options.authMode, options.baseUrl)) return null; + + const projectRoot = options.projectRoot ?? process.cwd(); + const env = options.env ?? process.env; + const launch = detectWorkflowMcpLaunchConfig(projectRoot, env); + const surface = options.surface ?? "workflow dispatch"; + const unitLabel = options.unitType ? ` for ${options.unitType}` : ""; + const providerLabel = `"${provider}"`; + + if (!launch) { + return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: the GSD workflow MCP server is not configured or discoverable. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root. You can also configure GSD_WORKFLOW_MCP_COMMAND, build packages/mcp-server/dist/cli.js, or install gsd-mcp-server on PATH.`; + } + + const missing = [...new Set(requiredTools)].filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool)); + if (missing.length === 0) return null; + + return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`; +} diff --git a/src/resources/extensions/gsd/workflow-migration.ts b/src/resources/extensions/gsd/workflow-migration.ts index 4c8a9f071..7112e74b7 100644 --- a/src/resources/extensions/gsd/workflow-migration.ts +++ b/src/resources/extensions/gsd/workflow-migration.ts @@ -7,6 +7,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { _getAdapter, transaction } from "./gsd-db.js"; import { parseRoadmap, parsePlan } from "./parsers-legacy.js"; +import { logWarning } from "./workflow-logger.js"; // ─── needsAutoMigration ─────────────────────────────────────────────────── @@ -23,8 +24,8 @@ export function needsAutoMigration(basePath: string): boolean { try { const row = db.prepare("SELECT COUNT(*) as cnt FROM milestones").get(); if (row && (row["cnt"] as number) > 0) return false; - } catch { - // Table might not exist yet — that's fine, we can still migrate + } catch (e) { + logWarning("migration", `DB probe failed: ${(e as Error).message}`); return false; } @@ -71,7 +72,7 @@ export function migrateFromMarkdown(basePath: string): void { .filter(e => e.isDirectory()) .map(e => e.name); } catch { - process.stderr.write("workflow-migration: failed to read milestones directory\n"); + logWarning("migration", "failed to read milestones directory"); return; } @@ -141,7 +142,7 @@ export function migrateFromMarkdown(basePath: string): void { risk: s.risk || "low", })); } catch (err) { - process.stderr.write(`workflow-migration: failed to parse ROADMAP.md for ${mId}: ${(err as Error).message}\n`); + logWarning("migration", `failed to parse ROADMAP.md for ${mId}: ${(err as Error).message}`); // Still add milestone with ID as title milestoneInserts.push({ id: mId, title: mId, status: milestoneStatus }); } @@ -191,7 +192,7 @@ export function migrateFromMarkdown(basePath: string): void { }); } } catch (err) { - process.stderr.write(`workflow-migration: failed to parse ${slice.id}-PLAN.md for ${mId}: ${(err as Error).message}\n`); + logWarning("migration", `failed to parse ${slice.id}-PLAN.md for ${mId}: ${(err as Error).message}`); } } } @@ -206,8 +207,8 @@ export function migrateFromMarkdown(basePath: string): void { process.stderr.write(`workflow-migration: orphaned summary file ${summaryFile} in ${mId} (slice not found in ROADMAP.md), skipping\n`); } } - } catch { - // Non-fatal + } catch (e) { + logWarning("migration", `Orphaned summary check failed for ${mId}: ${(e as Error).message}`); } } @@ -308,17 +309,18 @@ export function validateMigration(basePath: string): { discrepancies: string[] } const planContent = readFileSync(planPath, "utf-8"); const plan = parsePlan(planContent); mdTaskCount += plan.tasks.length; - } catch { - // Skip unreadable plan + } catch (e) { + logWarning("migration", `Failed to read plan ${slice.id}-PLAN.md: ${(e as Error).message}`); } } } - } catch { - // Skip unreadable roadmap + } catch (e) { + logWarning("migration", `Failed to read roadmap for ${mId}: ${(e as Error).message}`); } } } - } catch { + } catch (e) { + logWarning("migration", `Validation failed to read markdown: ${(e as Error).message}`); return { discrepancies: ["Failed to read markdown for validation"] }; } diff --git a/src/resources/extensions/gsd/workflow-projections.ts b/src/resources/extensions/gsd/workflow-projections.ts index 4affbec8a..dfa8b170e 100644 --- a/src/resources/extensions/gsd/workflow-projections.ts +++ b/src/resources/extensions/gsd/workflow-projections.ts @@ -9,15 +9,33 @@ import { getMilestone, getMilestoneSlices, getSliceTasks, + getVerificationEvidence, } from "./gsd-db.js"; -import type { MilestoneRow, SliceRow, TaskRow } from "./gsd-db.js"; +import type { MilestoneRow, SliceRow, TaskRow, VerificationEvidenceRow } from "./gsd-db.js"; import { atomicWriteSync } from "./atomic-write.js"; import { join } from "node:path"; import { mkdirSync, existsSync } from "node:fs"; import { logWarning } from "./workflow-logger.js"; +import { isClosedStatus } from "./status-guards.js"; import { deriveState } from "./state.js"; import type { GSDState } from "./types.js"; +// ─── Helpers ───────────────────────────────────────────────────────────── + +/** + * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title + * to prevent double-prefixing when the renderer adds its own prefix. + * Handles repeated prefixes (e.g. "M001: M001: M001: Title" → "Title"). + */ +export function stripIdPrefix(title: string, id: string): string { + const prefix = `${id}: `; + let result = title; + while (result.startsWith(prefix)) { + result = result.slice(prefix.length); + } + return result.trim() || title; +} + // ─── PLAN.md Projection ────────────────────────────────────────────────── /** @@ -27,15 +45,18 @@ import type { GSDState } from "./types.js"; export function renderPlanContent(sliceRow: SliceRow, taskRows: TaskRow[]): string { const lines: string[] = []; - lines.push(`# ${sliceRow.id}: ${sliceRow.title}`); + const displayTitle = stripIdPrefix(sliceRow.title, sliceRow.id); + lines.push(`# ${sliceRow.id}: ${displayTitle}`); lines.push(""); - lines.push(`**Goal:** ${sliceRow.goal || sliceRow.full_summary_md || "TBD"}`); - lines.push(`**Demo:** After this: ${sliceRow.demo || sliceRow.full_uat_md || "TBD"}`); + // #2945: never use full_summary_md/full_uat_md as display fallbacks — + // they contain multi-line rendered markdown that corrupts single-line fields. + lines.push(`**Goal:** ${sliceRow.goal || "TBD"}`); + lines.push(`**Demo:** After this: ${sliceRow.demo || "TBD"}`); lines.push(""); lines.push("## Tasks"); for (const task of taskRows) { - const checkbox = task.status === "done" || task.status === "complete" ? "[x]" : "[ ]"; + const checkbox = isClosedStatus(task.status) ? "[x]" : "[ ]"; lines.push(`- ${checkbox} **${task.id}: ${task.title}** \u2014 ${task.description}`); // Estimate subline (always present if non-empty) @@ -94,7 +115,8 @@ export function renderPlanProjection(basePath: string, milestoneId: string, slic export function renderRoadmapContent(milestoneRow: MilestoneRow, sliceRows: SliceRow[]): string { const lines: string[] = []; - lines.push(`# ${milestoneRow.id}: ${milestoneRow.title}`); + const displayTitle = stripIdPrefix(milestoneRow.title, milestoneRow.id); + lines.push(`# ${milestoneRow.id}: ${displayTitle}`); lines.push(""); lines.push("## Vision"); lines.push(milestoneRow.vision || milestoneRow.title || "TBD"); @@ -104,7 +126,7 @@ export function renderRoadmapContent(milestoneRow: MilestoneRow, sliceRows: Slic lines.push("|----|-------|------|---------|------|------------|"); for (const slice of sliceRows) { - const done = slice.status === "done" || slice.status === "complete" ? "\u2705" : "\u2B1C"; + const done = isClosedStatus(slice.status) ? "\u2705" : "\u2B1C"; // depends is already parsed to string[] by rowToSlice let depends = "\u2014"; @@ -113,7 +135,10 @@ export function renderRoadmapContent(milestoneRow: MilestoneRow, sliceRows: Slic } const risk = (slice.risk || "low").toLowerCase(); - const demo = slice.demo || slice.full_uat_md || "TBD"; + // #2945 Bug 1: never use full_uat_md as a table cell fallback — it contains + // multi-line UAT content (preconditions, steps, expected results) that + // corrupts the markdown table and makes subsequent slices invisible. + const demo = slice.demo || "TBD"; lines.push(`| ${slice.id} | ${slice.title} | ${risk} | ${depends} | ${done} | ${demo} |`); } @@ -142,71 +167,93 @@ export function renderRoadmapProjection(basePath: string, milestoneId: string): /** * Render SUMMARY.md content from a task row. - * Pure function — no side effects. + * Single source of truth for summary rendering — used both at completion + * time and at projection regeneration time (#2720). + * + * @param evidence - Optional verification evidence rows. When called from + * complete-task, these are passed directly. When called from projection + * regeneration, they are queried from the DB by renderSummaryProjection. */ -export function renderSummaryContent(taskRow: TaskRow, sliceId: string, milestoneId: string): string { - const lines: string[] = []; +export function renderSummaryContent( + taskRow: TaskRow, + sliceId: string, + milestoneId: string, + evidence?: Array<{ command: string; exitCode?: number; exit_code?: number; verdict: string; durationMs?: number; duration_ms?: number }>, +): string { + // ── Frontmatter (YAML list format, matches parseSummary() expectations) ── + const keyFilesYaml = taskRow.key_files && taskRow.key_files.length > 0 + ? taskRow.key_files.map(f => ` - ${f}`).join("\n") + : " - (none)"; + const keyDecisionsYaml = taskRow.key_decisions && taskRow.key_decisions.length > 0 + ? taskRow.key_decisions.map(d => ` - ${d}`).join("\n") + : " - (none)"; - // Frontmatter - lines.push("---"); - lines.push(`id: ${taskRow.id}`); - lines.push(`parent: ${sliceId}`); - lines.push(`milestone: ${milestoneId}`); - lines.push("provides: []"); - lines.push("requires: []"); - lines.push("affects: []"); + // Derive verification_result from evidence if available + const evidenceList = evidence ?? []; + const allPassed = evidenceList.length > 0 && + evidenceList.every(e => { + const code = e.exitCode ?? e.exit_code ?? -1; + return code === 0 || e.verdict.includes("\u2705") || e.verdict.toLowerCase().includes("pass"); + }); + const verificationResult = taskRow.verification_result + ? (allPassed ? "passed" : (evidenceList.length === 0 ? "untested" : "mixed")) + : (allPassed ? "passed" : (evidenceList.length === 0 ? "untested" : "mixed")); - // key_files is already parsed to string[] - if (taskRow.key_files && taskRow.key_files.length > 0) { - lines.push(`key_files: [${taskRow.key_files.map(f => `"${f}"`).join(", ")}]`); + // Build verification evidence table + let evidenceTable = "| # | Command | Exit Code | Verdict | Duration |\n|---|---------|-----------|---------|----------|\n"; + if (evidenceList.length > 0) { + evidenceList.forEach((e, i) => { + const code = e.exitCode ?? e.exit_code ?? 0; + const dur = e.durationMs ?? e.duration_ms ?? 0; + evidenceTable += `| ${i + 1} | \`${e.command}\` | ${code} | ${e.verdict} | ${dur}ms |\n`; + }); } else { - lines.push("key_files: []"); + evidenceTable += "| \u2014 | No verification commands discovered | \u2014 | \u2014 | \u2014 |\n"; } - // key_decisions is already parsed to string[] - if (taskRow.key_decisions && taskRow.key_decisions.length > 0) { - lines.push(`key_decisions: [${taskRow.key_decisions.map(d => `"${d}"`).join(", ")}]`); - } else { - lines.push("key_decisions: []"); - } + const title = taskRow.one_liner || taskRow.title || taskRow.id; - lines.push("patterns_established: []"); - lines.push("drill_down_paths: []"); - lines.push("observability_surfaces: []"); - lines.push(`duration: "${taskRow.duration || ""}"`); - lines.push(`verification_result: "${taskRow.verification_result || ""}"`); - lines.push(`completed_at: ${taskRow.completed_at || ""}`); - lines.push(`blocker_discovered: ${taskRow.blocker_discovered ? "true" : "false"}`); - lines.push("---"); - lines.push(""); - lines.push(`# ${taskRow.id}: ${taskRow.title}`); - lines.push(""); + return `--- +id: ${taskRow.id} +parent: ${sliceId} +milestone: ${milestoneId} +key_files: +${keyFilesYaml} +key_decisions: +${keyDecisionsYaml} +duration: ${taskRow.duration || ""} +verification_result: ${verificationResult} +completed_at: ${taskRow.completed_at || ""} +blocker_discovered: ${taskRow.blocker_discovered ? "true" : "false"} +--- - // One-liner (if present) - if (taskRow.one_liner) { - lines.push(`> ${taskRow.one_liner}`); - lines.push(""); - } +# ${taskRow.id}: ${title} - lines.push("## What Happened"); - lines.push(taskRow.full_summary_md || taskRow.narrative || "No summary recorded."); - lines.push(""); +**${taskRow.one_liner || ""}** - // Deviations (if present) - if (taskRow.deviations) { - lines.push("## Deviations"); - lines.push(taskRow.deviations); - lines.push(""); - } +## What Happened - // Known issues (if present) - if (taskRow.known_issues) { - lines.push("## Known Issues"); - lines.push(taskRow.known_issues); - lines.push(""); - } +${taskRow.narrative || "No summary recorded."} - return lines.join("\n"); +## Verification + +${taskRow.verification_result || "No verification recorded."} + +## Verification Evidence + +${evidenceTable} +## Deviations + +${taskRow.deviations || "None."} + +## Known Issues + +${taskRow.known_issues || "None."} + +## Files Created/Modified + +${taskRow.key_files && taskRow.key_files.length > 0 ? taskRow.key_files.map(f => `- \`${f}\``).join("\n") : "None."} +`; } /** @@ -218,7 +265,8 @@ export function renderSummaryProjection(basePath: string, milestoneId: string, s const taskRow = taskRows.find(t => t.id === taskId); if (!taskRow) return; - const content = renderSummaryContent(taskRow, sliceId, milestoneId); + const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId); + const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows); const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks"); mkdirSync(dir, { recursive: true }); atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content); @@ -235,14 +283,18 @@ export function renderStateContent(state: GSDState): string { const lines: string[] = []; lines.push("# GSD State", ""); - const activeMilestone = state.activeMilestone - ? `${state.activeMilestone.id}: ${state.activeMilestone.title}` - : "None"; const activeSlice = state.activeSlice - ? `${state.activeSlice.id}: ${state.activeSlice.title}` + ? `${state.activeSlice.id}: ${stripIdPrefix(state.activeSlice.title, state.activeSlice.id)}` : "None"; - lines.push(`**Active Milestone:** ${activeMilestone}`); + if (state.phase === 'complete' && state.lastCompletedMilestone) { + lines.push(`**Last Completed Milestone:** ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}`); + } else { + const activeMilestone = state.activeMilestone + ? `${state.activeMilestone.id}: ${stripIdPrefix(state.activeMilestone.title, state.activeMilestone.id)}` + : "None"; + lines.push(`**Active Milestone:** ${activeMilestone}`); + } lines.push(`**Active Slice:** ${activeSlice}`); lines.push(`**Phase:** ${state.phase}`); if (state.requirements) { @@ -253,7 +305,7 @@ export function renderStateContent(state: GSDState): string { for (const entry of state.registry) { const glyph = entry.status === "complete" ? "\u2705" : entry.status === "active" ? "\uD83D\uDD04" : entry.status === "parked" ? "\u23F8\uFE0F" : "\u2B1C"; - lines.push(`- ${glyph} **${entry.id}:** ${entry.title}`); + lines.push(`- ${glyph} **${entry.id}:** ${stripIdPrefix(entry.title, entry.id)}`); } lines.push(""); @@ -319,12 +371,10 @@ export async function renderAllProjections(basePath: string, milestoneId: string const sliceRows = getMilestoneSlices(milestoneId); for (const slice of sliceRows) { - // Render PLAN.md for each slice - try { - renderPlanProjection(basePath, milestoneId, slice.id); - } catch (err) { - logWarning("projection", `renderPlanProjection failed for ${milestoneId}/${slice.id}: ${(err as Error).message}`); - } + // PLAN.md is rendered by the authoritative markdown-renderer.js in + // plan-slice/replan-slice tools. Do NOT overwrite it here — the simplified + // projection is missing key sections (Must-Haves, Verification, Files + // Likely Touched) and corrupts multi-line task descriptions (#3651). // Render SUMMARY.md for each completed task const taskRows = getSliceTasks(milestoneId, slice.id); @@ -390,7 +440,7 @@ export function regenerateIfMissing( renderSummaryProjection(basePath, milestoneId, sliceId, task.id); regenerated++; } catch (err) { - console.error(`[projections] regenerateIfMissing SUMMARY failed for ${task.id}:`, err); + logWarning("projection", `regenerateIfMissing SUMMARY failed for ${task.id}: ${(err as Error).message}`); } } } @@ -419,7 +469,7 @@ export function regenerateIfMissing( } return true; } catch (err) { - console.error(`[projections] regenerateIfMissing ${fileType} failed:`, err); + logWarning("projection", `regenerateIfMissing ${fileType} failed: ${(err as Error).message}`); return false; } } diff --git a/src/resources/extensions/gsd/workflow-reconcile.ts b/src/resources/extensions/gsd/workflow-reconcile.ts index 4704501b0..9f304cfbb 100644 --- a/src/resources/extensions/gsd/workflow-reconcile.ts +++ b/src/resources/extensions/gsd/workflow-reconcile.ts @@ -1,19 +1,61 @@ import { join } from "node:path"; import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs"; -import { readEvents, findForkPoint, appendEvent, getSessionId } from "./workflow-events.js"; +import { logWarning, logError } from "./workflow-logger.js"; +import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js"; import type { WorkflowEvent } from "./workflow-events.js"; import { transaction, updateTaskStatus, updateSliceStatus, + updateMilestoneStatus, + getSliceTasks, + insertMilestone, + _getAdapter, + getMilestoneSlices, insertVerificationEvidence, upsertDecision, openDatabase, + setTaskBlockerDiscovered, } from "./gsd-db.js"; +import { isClosedStatus } from "./status-guards.js"; +import { invalidateStateCache } from "./state.js"; +import { clearPathCache } from "./paths.js"; +import { clearParseCache } from "./files.js"; import { writeManifest } from "./workflow-manifest.js"; import { atomicWriteSync } from "./atomic-write.js"; import { acquireSyncLock, releaseSyncLock } from "./sync-lock.js"; +// ─── Replay Helpers ────────────────────────────────────────────────────────── + +/** + * Replay a complete_slice event with task validation. + * + * #2945 Bug 2: The original replay blindly called updateSliceStatus("done") + * without checking whether all tasks in the slice are actually complete. + * During API overload or partial execution, a complete_slice event could + * be logged even when tasks were skipped, causing the milestone completion + * guard to see the slice as "done" and allow premature milestone completion. + * + * This function validates that every task in the slice has a closed status + * before marking the slice as done. If any task is still pending, the slice + * status is left unchanged. + */ +export function replaySliceComplete(milestoneId: string, sliceId: string, ts: string): void { + const tasks = getSliceTasks(milestoneId, sliceId); + // If there are tasks and any are not closed, skip the status update + if (tasks.length > 0) { + const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status)); + if (incompleteTasks.length > 0) { + process.stderr.write( + `[gsd] reconcile: skipping complete_slice replay for ${sliceId} — ` + + `${incompleteTasks.length} task(s) still pending\n`, + ); + return; + } + } + updateSliceStatus(milestoneId, sliceId, "done", ts); +} + // ─── Public Types ───────────────────────────────────────────────────────────── export interface ConflictEntry { @@ -39,7 +81,15 @@ function replayEvents(events: WorkflowEvent[]): void { transaction(() => { for (const event of events) { const p = event.params; - switch (event.cmd) { + // Normalize cmd format: completion tools write hyphens ("complete-task"), + // legacy logs use underscores ("complete_task"). Accept both formats. + // Type guard: malformed event lines with non-string cmd are skipped. + if (typeof event.cmd !== "string") { + logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`); + continue; + } + const cmd = event.cmd.replace(/-/g, "_"); + switch (cmd) { case "complete_task": { const milestoneId = p["milestoneId"] as string; const sliceId = p["sliceId"] as string; @@ -55,13 +105,11 @@ function replayEvents(events: WorkflowEvent[]): void { break; } case "report_blocker": { - // report_blocker marks the task with blocker_discovered = 1 - // The DB helper updateTaskStatus doesn't handle blockers, - // so we just update status to "blocked" as a best-effort replay. const milestoneId = p["milestoneId"] as string; const sliceId = p["sliceId"] as string; const taskId = p["taskId"] as string; updateTaskStatus(milestoneId, sliceId, taskId, "blocked"); + setTaskBlockerDiscovered(milestoneId, sliceId, taskId, true); break; } case "record_verification": { @@ -82,12 +130,70 @@ function replayEvents(events: WorkflowEvent[]): void { case "complete_slice": { const milestoneId = p["milestoneId"] as string; const sliceId = p["sliceId"] as string; - updateSliceStatus(milestoneId, sliceId, "done", event.ts); + // #2945 Bug 2: validate tasks before marking slice done + replaySliceComplete(milestoneId, sliceId, event.ts); + break; + } + case "complete_milestone": { + const milestoneId = p["milestoneId"] as string; + if (!milestoneId) break; + // Invariant check: only mark complete if all slices are closed. + // Without this guard, a reordered/partial event stream could close + // a milestone while work is still incomplete. + const mSlices = getMilestoneSlices(milestoneId); + const allClosed = mSlices.length === 0 || mSlices.every(s => isClosedStatus(s.status)); + if (allClosed) { + updateMilestoneStatus(milestoneId, "complete", event.ts); + } else { + logWarning("reconcile", `Skipping complete_milestone replay for ${milestoneId}: not all slices are closed`); + } + break; + } + case "plan_milestone": { + // Replay milestone creation — uses INSERT OR IGNORE (gsd-db's insertMilestone is safe) + const mId = p["milestoneId"] as string; + if (mId) { + insertMilestone({ id: mId, title: (p["title"] as string) ?? mId }); + } break; } case "plan_slice": { - // plan_slice events are informational — slice should already exist. - // No DB mutation needed during replay (the slice was inserted at plan time). + // Replay slice creation — strict INSERT OR IGNORE to avoid overwriting + // progressed status. insertSlice() uses ON CONFLICT DO UPDATE which + // could downgrade a completed slice back to pending. + const milestoneId = p["milestoneId"] as string; + const sliceId = p["sliceId"] as string; + if (milestoneId && sliceId) { + const adapter = _getAdapter(); + if (adapter) { + adapter.prepare( + `INSERT OR IGNORE INTO slices (milestone_id, id, title, status, created_at) + VALUES (:mid, :sid, :title, 'pending', :ts)`, + ).run({ ":mid": milestoneId, ":sid": sliceId, ":title": (p["title"] as string) ?? sliceId, ":ts": event.ts }); + } + } + break; + } + case "plan_task": { + // Replay task creation — strict INSERT OR IGNORE to avoid overwriting + // progressed status. insertTask() uses ON CONFLICT DO UPDATE which + // could downgrade a done/in-progress task back to pending. + const milestoneId = p["milestoneId"] as string; + const sliceId = p["sliceId"] as string; + const taskId = p["taskId"] as string; + if (milestoneId && sliceId && taskId) { + const adapter = _getAdapter(); + if (adapter) { + adapter.prepare( + `INSERT OR IGNORE INTO tasks (milestone_id, slice_id, id, title, status, created_at) + VALUES (:mid, :sid, :tid, :title, 'pending', :ts)`, + ).run({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId, ":title": (p["title"] as string) ?? taskId, ":ts": event.ts }); + } + } + break; + } + case "replan_slice": { + // Informational — replan events don't mutate DB during replay break; } case "save_decision": { @@ -105,7 +211,7 @@ function replayEvents(events: WorkflowEvent[]): void { break; } default: - // Unknown commands are silently skipped during replay + logWarning("reconcile", `Unknown event cmd during replay: "${event.cmd}" — skipped`); break; } } @@ -123,17 +229,22 @@ export function extractEntityKey( event: WorkflowEvent, ): { type: string; id: string } | null { const p = event.params; + // Normalize cmd format: accept both hyphens and underscores + if (typeof event.cmd !== "string") return null; + const cmd = event.cmd.replace(/-/g, "_"); - switch (event.cmd) { + switch (cmd) { case "complete_task": case "start_task": case "report_blocker": case "record_verification": + case "plan_task": return typeof p["taskId"] === "string" ? { type: "task", id: p["taskId"] } : null; case "complete_slice": + case "replan_slice": return typeof p["sliceId"] === "string" ? { type: "slice", id: p["sliceId"] } : null; @@ -143,6 +254,12 @@ export function extractEntityKey( ? { type: "slice_plan", id: p["sliceId"] } : null; + case "complete_milestone": + case "plan_milestone": + return typeof p["milestoneId"] === "string" + ? { type: "milestone", id: p["milestoneId"] } + : null; + case "save_decision": if (typeof p["scope"] === "string" && typeof p["decision"] === "string") { return { type: "decision", id: `${p["scope"]}:${p["decision"]}` }; @@ -207,6 +324,41 @@ export function detectConflicts( return conflicts; } +function rewriteDivergedEventsForEntity( + divergedEvents: WorkflowEvent[], + entityType: string, + entityId: string, + replacementEvents: WorkflowEvent[], +): WorkflowEvent[] { + const rewritten: WorkflowEvent[] = []; + let inserted = false; + + for (const event of divergedEvents) { + const key = extractEntityKey(event); + if (key?.type === entityType && key.id === entityId) { + if (!inserted) { + rewritten.push(...replacementEvents); + inserted = true; + } + continue; + } + rewritten.push(event); + } + + if (!inserted) { + rewritten.push(...replacementEvents); + } + + return rewritten; +} + +function writeEventLog(basePath: string, events: WorkflowEvent[]): void { + const dir = join(basePath, ".gsd"); + mkdirSync(dir, { recursive: true }); + const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : ""); + atomicWriteSync(join(dir, "event-log.jsonl"), content); +} + // ─── writeConflictsFile ─────────────────────────────────────────────────────── /** @@ -274,9 +426,7 @@ export function reconcileWorktreeLogs( // Acquire advisory lock to prevent concurrent reconcile + append races const lock = acquireSyncLock(mainBasePath); if (!lock.acquired) { - process.stderr.write( - `[gsd] reconcile: could not acquire sync lock — another reconciliation may be in progress\n`, - ); + logWarning("reconcile", "could not acquire sync lock — another reconciliation may be in progress"); return { autoMerged: 0, conflicts: [] }; } @@ -315,9 +465,9 @@ function _reconcileWorktreeLogsInner( if (conflicts.length > 0) { // D-04: atomic all-or-nothing — block entire merge writeConflictsFile(mainBasePath, conflicts, worktreeBasePath); - process.stderr.write( - `[gsd] reconcile: ${conflicts.length} conflict(s) detected — see ${join(mainBasePath, ".gsd", "CONFLICTS.md")}\n`, - ); + const conflictSummary = conflicts.slice(0, 3).map(c => `${c.entityType}:${c.entityId}`).join(", "); + const truncated = conflicts.length > 3 ? `... and ${conflicts.length - 3} more` : ""; + logError("reconcile", `${conflicts.length} conflict(s) detected on ${conflictSummary}${truncated}. Details: .gsd/CONFLICTS.md`, { count: String(conflicts.length), path: join(mainBasePath, ".gsd", "CONFLICTS.md") }); return { autoMerged: 0, conflicts }; } @@ -327,6 +477,14 @@ function _reconcileWorktreeLogsInner( const merged = indexed.map(({ e }) => e); // Step 7: Write merged event log FIRST (so crash recovery can re-derive DB state) + // Guard: detect concurrent appendEvent calls between our read (step 1) and + // this rewrite. If the log grew, re-read and retry to avoid dropping events. + const preWriteEvents = readEvents(mainLogPath); + if (preWriteEvents.length > mainEvents.length) { + logWarning("reconcile", `Event log grew during reconcile (${mainEvents.length} → ${preWriteEvents.length}), retrying with fresh read`); + return _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath); + } + const baseEvents = mainEvents.slice(0, forkPoint + 1); const mergedLog = baseEvents.concat(merged); const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : ""); @@ -341,11 +499,15 @@ function _reconcileWorktreeLogsInner( try { writeManifest(mainBasePath); } catch (err) { - process.stderr.write( - `[gsd] reconcile: manifest write failed (non-fatal): ${(err as Error).message}\n`, - ); + logWarning("reconcile", "manifest write failed (non-fatal)", { error: (err as Error).message }); } + // Step 10: Invalidate caches so deriveState() sees post-reconcile DB state. + // Use targeted invalidation (not invalidateAllCaches) to avoid wiping artifacts table. + invalidateStateCache(); + clearPathCache(); + clearParseCache(); + return { autoMerged: merged.length, conflicts: [] }; } @@ -426,8 +588,8 @@ function parseEventBlock(block: string): WorkflowEvent[] { if (paramsMatch) { try { params = JSON.parse(paramsMatch[1]!) as Record; - } catch { - // Keep empty params on parse error + } catch (e) { + logWarning("reconcile", `tool call params parse failed: ${(e as Error).message}`); } i++; // consume params line } @@ -443,8 +605,8 @@ function parseEventBlock(block: string): WorkflowEvent[] { /** * Resolve a single conflict by picking one side's events. - * Replays the picked events through the DB helpers, appends them to the event log, - * and updates or removes CONFLICTS.md. + * Replays the picked events through the DB helpers, rewrites the chosen side's + * event log so the conflict is durable, and updates or removes CONFLICTS.md. * * When the last conflict is resolved, non-conflicting events from both sides * are also replayed (they were blocked by the all-or-nothing D-04 rule). @@ -466,14 +628,30 @@ export function resolveConflict( const conflict = conflicts[idx]!; const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents; + const mainLogPath = join(basePath, ".gsd", "event-log.jsonl"); + const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl"); + const mainEvents = readEvents(mainLogPath); + const wtEvents = readEvents(wtLogPath); + const forkPoint = findForkPoint(mainEvents, wtEvents); + const mainBaseEvents = mainEvents.slice(0, forkPoint + 1); + const wtBaseEvents = wtEvents.slice(0, forkPoint + 1); + const mainDiverged = mainEvents.slice(forkPoint + 1); + const wtDiverged = wtEvents.slice(forkPoint + 1); + + const rewrittenTargetEvents = pick === "main" + ? rewriteDivergedEventsForEntity(wtDiverged, entityType, entityId, eventsToReplay) + : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay); + + const targetBasePath = pick === "main" ? worktreeBasePath : basePath; + const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents; + writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents)); + // Replay resolved events through the DB (updates DB state) openDatabase(join(basePath, ".gsd", "gsd.db")); replayEvents(eventsToReplay); - - // Append resolved events to the event log - for (const event of eventsToReplay) { - appendEvent(basePath, { cmd: event.cmd, params: event.params, ts: event.ts, actor: event.actor }); - } + invalidateStateCache(); + clearPathCache(); + clearParseCache(); // Remove resolved conflict from list conflicts.splice(idx, 1); diff --git a/src/resources/extensions/gsd/workflow-templates.ts b/src/resources/extensions/gsd/workflow-templates.ts index 2c4b9daf1..b6070c32c 100644 --- a/src/resources/extensions/gsd/workflow-templates.ts +++ b/src/resources/extensions/gsd/workflow-templates.ts @@ -58,8 +58,17 @@ let cachedRegistry: TemplateRegistry | null = null; export function loadRegistry(): TemplateRegistry { if (cachedRegistry) return cachedRegistry; - const content = readFileSync(registryPath, "utf-8"); - cachedRegistry = JSON.parse(content) as TemplateRegistry; + if (!existsSync(registryPath)) { + cachedRegistry = { version: 1, templates: {} }; + return cachedRegistry; + } + + try { + const content = readFileSync(registryPath, "utf-8"); + cachedRegistry = JSON.parse(content) as TemplateRegistry; + } catch { + cachedRegistry = { version: 1, templates: {} }; + } return cachedRegistry; } diff --git a/src/resources/extensions/gsd/workspace-index.ts b/src/resources/extensions/gsd/workspace-index.ts index 8b270662b..28fa95df1 100644 --- a/src/resources/extensions/gsd/workspace-index.ts +++ b/src/resources/extensions/gsd/workspace-index.ts @@ -11,6 +11,7 @@ import { resolveTasksDir, } from "./paths.js"; import { deriveState } from "./state.js"; +import { extractVerdict } from "./verdict-parser.js"; import { milestoneIdSort, findMilestoneIds } from "./guided-flow.js"; import type { RiskLevel } from "./types.js"; import { getSliceBranchName, detectWorktreeName } from "./worktree.js"; @@ -42,6 +43,10 @@ export interface WorkspaceMilestoneTarget { id: string; title: string; roadmapPath?: string; + /** Authoritative milestone lifecycle status from the GSD state registry. */ + status?: "complete" | "active" | "pending" | "parked"; + /** Milestone validation verdict, when validation has been performed. */ + validationVerdict?: "pass" | "needs-attention" | "needs-remediation"; slices: WorkspaceSliceTarget[]; } @@ -192,6 +197,31 @@ export async function indexWorkspace(basePath: string, opts: IndexWorkspaceOptio phase: state.phase, }; + // Enrich milestones with authoritative status from state registry (#2807) + if (state.registry) { + const registryMap = new Map(state.registry.map(e => [e.id, e])); + for (const milestone of milestones) { + const entry = registryMap.get(milestone.id); + if (entry) { + milestone.status = entry.status; + } + } + } + + // Populate validationVerdict from VALIDATION files (#2807) + for (const milestone of milestones) { + const validationPath = resolveMilestoneFile(basePath, milestone.id, "VALIDATION"); + if (validationPath) { + const validationContent = await loadFile(validationPath); + if (validationContent) { + const verdict = extractVerdict(validationContent); + if (verdict === "pass" || verdict === "needs-attention" || verdict === "needs-remediation") { + milestone.validationVerdict = verdict; + } + } + } + } + const scopes: WorkspaceScopeTarget[] = [{ scope: "project", label: "project", kind: "project" }]; for (const milestone of milestones) { scopes.push({ scope: milestone.id, label: `${milestone.id}: ${milestone.title}`, kind: "milestone" }); diff --git a/src/resources/extensions/gsd/worktree-manager.ts b/src/resources/extensions/gsd/worktree-manager.ts index 5cf93e387..37490a30b 100644 --- a/src/resources/extensions/gsd/worktree-manager.ts +++ b/src/resources/extensions/gsd/worktree-manager.ts @@ -15,7 +15,7 @@ * 4. remove() — git worktree remove + branch cleanup */ -import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs"; +import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs"; import { execFileSync } from "node:child_process"; import { join, resolve, sep } from "node:path"; import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js"; @@ -89,16 +89,18 @@ function normalizePathForComparison(path: string): string { */ export function resolveGitDir(basePath: string): string { const gitPath = join(basePath, ".git"); - if (!existsSync(gitPath)) return join(basePath, ".git"); + if (!existsSync(gitPath)) return gitPath; + // In a normal repo .git is a directory — skip the file read (#3597) + if (lstatSync(gitPath).isDirectory()) return gitPath; try { const content = readFileSync(gitPath, "utf-8").trim(); if (content.startsWith("gitdir: ")) { return resolve(basePath, content.slice(8)); } - } catch { - // Not a file or unreadable — fall through to default + } catch (e) { + logWarning("worktree", `.git file read failed: ${(e as Error).message}`); } - return join(basePath, ".git"); + return gitPath; } export function worktreesDir(basePath: string): string { @@ -113,6 +115,23 @@ export function worktreeBranchName(name: string): string { return `worktree/${name}`; } +/** + * Validate that a path is inside the .gsd/worktrees/ directory. + * Resolves symlinks and normalizes ".." traversals before comparison + * so that a symlink-resolved or crafted path cannot escape containment. + * + * Used as a safety gate before any destructive operation (rmSync, + * nativeWorktreeRemove --force) to prevent #2365-style data loss. + */ +export function isInsideWorktreesDir(basePath: string, targetPath: string): boolean { + const wtDirPath = worktreesDir(basePath); + const wtDir = existsSync(wtDirPath) ? realpathSync(wtDirPath) : resolve(wtDirPath); + const resolved = existsSync(targetPath) ? realpathSync(targetPath) : resolve(targetPath); + // The resolved path must start with the worktrees dir followed by a separator, + // not merely be a prefix match (e.g. ".gsd/worktrees-extra" must not match). + return resolved === wtDir || resolved.startsWith(wtDir + sep); +} + // ─── Core Operations ─────────────────────────────────────────────────────── /** @@ -277,6 +296,80 @@ export function listWorktrees(basePath: string): WorktreeInfo[] { return worktrees; } +// ─── Nested .git Detection (#2616) ────────────────────────────────────── +// +// Scaffolding tools (create-next-app, cargo init, etc.) create nested .git +// directories inside worktrees. Git records these as gitlinks (mode 160000) +// without a .gitmodules entry — so worktree cleanup destroys the only copy +// of their object database, causing permanent silent data loss. + +/** Directories to skip when scanning for nested .git dirs. */ +const NESTED_GIT_SKIP_DIRS = new Set([ + ".git", ".gsd", "node_modules", ".next", ".nuxt", "dist", "build", + "__pycache__", ".tox", ".venv", "venv", "target", "vendor", +]); + +/** + * Recursively find nested .git directories inside a worktree root. + * Returns paths to directories that contain their own .git (directory, not file). + * Skips node_modules, .gsd, and other non-project directories for performance. + * + * A nested .git *directory* (not a .git file — which is a legitimate worktree + * pointer) indicates a scaffolded repo that will become an orphaned gitlink. + */ +export function findNestedGitDirs(rootPath: string): string[] { + const results: string[] = []; + + function walk(dir: string, depth: number): void { + // Cap recursion depth to avoid runaway scanning + if (depth > 10) return; + + let entries: string[]; + try { + entries = readdirSync(dir); + } catch (e) { + logWarning("worktree", `readdirSync failed: ${(e as Error).message}`); + return; + } + + for (const entry of entries) { + if (NESTED_GIT_SKIP_DIRS.has(entry)) continue; + + const fullPath = join(dir, entry); + + // Only follow real directories, not symlinks + let stat; + try { + stat = lstatSync(fullPath); + } catch (e) { + logWarning("worktree", `lstatSync failed for ${fullPath}: ${(e as Error).message}`); + continue; + } + if (!stat.isDirectory()) continue; + + // Check if this directory contains a .git *directory* (not a .git file). + // A .git file is a worktree pointer and is legitimate. + // A .git directory is a standalone repo created by scaffolding. + const innerGit = join(fullPath, ".git"); + try { + const innerStat = lstatSync(innerGit); + if (innerStat.isDirectory()) { + results.push(fullPath); + // Don't recurse into the nested repo — we found what we need + continue; + } + } catch (e) { + logWarning("worktree", `existsSync/.git check failed for ${fullPath}: ${(e as Error).message}`); + } + + walk(fullPath, depth + 1); + } + } + + walk(rootPath, 0); + return results; +} + /** * Remove a worktree and optionally delete its branch. * If the process is currently inside the worktree, chdir out first. @@ -296,16 +389,37 @@ export function removeWorktree( // time, so its registered path points to the resolved external location. // If syncStateToProjectRoot later creates a real .gsd/ directory that // shadows the symlink, the computed path diverges from git's record. + let gitReportedPath: string | null = null; try { const entries = nativeWorktreeList(basePath); const entry = entries.find(e => e.branch === branch); if (entry?.path) { - wtPath = entry.path; + gitReportedPath = entry.path; } - } catch { /* fall back to computed path */ } + } catch (e) { logWarning("worktree", `nativeWorktreeList parse failed: ${(e as Error).message}`); } + + // Safety gate (#2365): only use the git-reported path if it is actually + // inside .gsd/worktrees/. When .gsd/ was a symlink, git may have resolved + // it to an external directory (e.g. a project data folder). Using that + // path for removal would destroy user data. + if (gitReportedPath && isInsideWorktreesDir(basePath, gitReportedPath)) { + wtPath = gitReportedPath; + } else if (gitReportedPath) { + console.error( + `[GSD] WARNING: git worktree list reported path outside .gsd/worktrees/: ${gitReportedPath}\n` + + ` Refusing to use it for removal — falling back to computed path: ${wtPath}`, + ); + // Still tell git to unregister the worktree entry via its reported path, + // but do NOT use force and do NOT fall back to rmSync on this path. + try { nativeWorktreeRemove(basePath, gitReportedPath, false); } catch (e) { logWarning("worktree", `non-force worktree remove failed for ${gitReportedPath}: ${e instanceof Error ? e.message : String(e)}`); } + } const resolvedWtPath = existsSync(wtPath) ? realpathSync(wtPath) : wtPath; + // Double-check: the resolved path (after symlink resolution) must also be + // inside .gsd/worktrees/ — a symlink inside the directory could point out. + const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath); + // If we're inside the worktree, move out first — git can't remove an in-use directory const cwd = process.cwd(); const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd; @@ -316,7 +430,7 @@ export function removeWorktree( if (!existsSync(wtPath)) { nativeWorktreePrune(basePath); if (deleteBranch) { - try { nativeBranchDelete(basePath, branch, true); } catch { /* branch may not exist */ } + try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `nativeBranchDelete failed: ${(e as Error).message}`); } } return; } @@ -350,26 +464,87 @@ export function removeWorktree( logWarning("reconcile", `Submodule changes detected — stash failed, changes may be lost during force removal`, { worktree: name, path: resolvedWtPath }); } } - } catch { - // submodule status failed — proceed with normal removal + } catch (e) { + logWarning("worktree", `submodule status check failed: ${(e as Error).message}`); } } - // Remove worktree: try non-force first when submodules have changes, - // falling back to force only after submodule state has been preserved. - const useForce = hasSubmoduleChanges ? false : force; - try { nativeWorktreeRemove(basePath, resolvedWtPath, useForce); } catch { /* may fail */ } + // Nested .git safety (#2616): detect nested .git directories created by + // scaffolding tools (create-next-app, cargo init, etc.). These produce + // gitlink entries (mode 160000) without .gitmodules — cleanup would destroy + // the only copy of the nested object database, causing permanent data loss. + // Fix: remove the nested .git dirs so git tracks the files as regular content. + const nestedGitDirs = findNestedGitDirs(resolvedWtPath); + if (nestedGitDirs.length > 0) { + for (const nestedDir of nestedGitDirs) { + const nestedGitPath = join(nestedDir, ".git"); + try { + rmSync(nestedGitPath, { recursive: true, force: true }); + logWarning("reconcile", + `Removed nested .git directory from scaffolded project to prevent data loss (#2616)`, + { worktree: name, nestedRepo: nestedDir }, + ); + } catch { + logWarning("reconcile", + `Failed to remove nested .git directory — files may be lost as orphaned gitlink`, + { worktree: name, nestedRepo: nestedDir }, + ); + } + } + } - // If the directory is still there (e.g. locked), try harder with force - if (existsSync(resolvedWtPath)) { - try { nativeWorktreeRemove(basePath, resolvedWtPath, true); } catch { /* may fail */ } + // Remove worktree — only use force/rmSync when the path is safely contained + if (resolvedPathSafe) { + // Remove worktree: try non-force first when submodules have changes, + // falling back to force only after submodule state has been preserved. + const useForce = hasSubmoduleChanges ? false : force; + try { nativeWorktreeRemove(basePath, resolvedWtPath, useForce); } catch (e) { logWarning("worktree", `nativeWorktreeRemove failed: ${(e as Error).message}`); } + + // If the directory is still there (e.g. locked), try harder with force + if (existsSync(resolvedWtPath)) { + try { nativeWorktreeRemove(basePath, resolvedWtPath, true); } catch (e) { logWarning("worktree", `nativeWorktreeRemove (force) failed: ${(e as Error).message}`); } + } + + // (#2821) If the worktree directory STILL exists after both native removal + // attempts (e.g. untracked files like ASSESSMENT/UAT-RESULT prevent git + // worktree remove), force-remove the git internal worktree metadata first, + // then remove the filesystem directory. Without this, the .git/worktrees/ + // lock prevents rmSync from cleaning up, and the orphaned worktree directory + // causes every subsequent `/gsd auto` to re-enter the stale worktree. + if (existsSync(resolvedWtPath)) { + try { + const wtInternalDir = join(basePath, ".git", "worktrees", name); + if (existsSync(wtInternalDir)) { + rmSync(wtInternalDir, { recursive: true, force: true }); + } + rmSync(resolvedWtPath, { recursive: true, force: true }); + if (wtPath !== resolvedWtPath && existsSync(wtPath)) { + rmSync(wtPath, { recursive: true, force: true }); + } + } catch { + logWarning( + "reconcile", + `Worktree directory could not be removed after git internal cleanup: ${resolvedWtPath}. ` + + `Manual cleanup: rm -rf "${resolvedWtPath.replaceAll("\\", "/")}"`, + { worktree: name }, + ); + } + } + } else { + // Path is outside containment — only do a non-force git worktree remove + // (which refuses to delete dirty worktrees) and never fall back to rmSync. + console.error( + `[GSD] WARNING: Resolved worktree path is outside .gsd/worktrees/: ${resolvedWtPath}\n` + + ` Skipping forced removal to prevent data loss.`, + ); + try { nativeWorktreeRemove(basePath, resolvedWtPath, false); } catch (e) { logWarning("worktree", `non-force worktree remove failed for ${resolvedWtPath}: ${e instanceof Error ? e.message : String(e)}`); } } // Prune stale entries so git knows the worktree is gone nativeWorktreePrune(basePath); if (deleteBranch) { - try { nativeBranchDelete(basePath, branch, true); } catch { /* branch may not exist */ } + try { nativeBranchDelete(basePath, branch, true); } catch (e) { logWarning("worktree", `final branch delete failed: ${(e as Error).message}`); } } } diff --git a/src/resources/extensions/gsd/worktree-resolver.ts b/src/resources/extensions/gsd/worktree-resolver.ts index c84d44656..484c0a7f9 100644 --- a/src/resources/extensions/gsd/worktree-resolver.ts +++ b/src/resources/extensions/gsd/worktree-resolver.ts @@ -350,7 +350,13 @@ export class WorktreeResolver { data: { milestoneId, mode }, }); - if (mode === "none") { + // #2625: If we are physically inside an auto-worktree, we MUST merge + // regardless of the current isolation config. This prevents data loss when + // the default isolation mode changes between versions (e.g., "worktree" -> + // "none"): the worktree branch still holds real commits that need merging. + const inWorktree = this.deps.isInAutoWorktree(this.s.basePath) && this.s.originalBasePath; + + if (mode === "none" && !inWorktree) { debugLog("WorktreeResolver", { action: "mergeAndExit", milestoneId, @@ -361,8 +367,7 @@ export class WorktreeResolver { } if ( - mode === "worktree" || - (this.deps.isInAutoWorktree(this.s.basePath) && this.s.originalBasePath) + mode === "worktree" || inWorktree ) { this._mergeWorktreeMode(milestoneId, ctx); } else if (mode === "branch") { @@ -432,6 +437,20 @@ export class WorktreeResolver { milestoneId, roadmapContent, ); + + // #2945 Bug 3: mergeMilestoneToMain performs best-effort worktree + // cleanup internally (step 12), but it can silently fail on Windows + // or when the worktree directory is locked. Perform a secondary + // teardown here to ensure the worktree is properly cleaned up. + // This is idempotent — if the worktree was already removed, + // teardownAutoWorktree handles the no-op case gracefully. + try { + this.deps.teardownAutoWorktree(originalBase, milestoneId); + } catch { + // Best-effort — the primary cleanup in mergeMilestoneToMain may + // have already removed the worktree. + } + if (mergeResult.codeFilesChanged) { ctx.notify( `Milestone ${milestoneId} merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`, @@ -478,10 +497,11 @@ export class WorktreeResolver { }); // Surface a clear, actionable error. The worktree and milestone branch are // intentionally preserved — nothing has been deleted. The user can retry - // /gsd dispatch complete-milestone or merge manually once the underlying issue is fixed - // (e.g. checkout to wrong branch, unresolved conflicts). (#1668) + // /gsd dispatch complete-milestone or merge manually once the underlying + // issue is fixed (e.g. checkout to wrong branch, unresolved conflicts). + // (#1668, #1891) ctx.notify( - `Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry /gsd dispatch complete-milestone or merge manually.`, + `Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry with \`/gsd dispatch complete-milestone\` or merge manually.`, "warning", ); diff --git a/src/resources/extensions/gsd/worktree.ts b/src/resources/extensions/gsd/worktree.ts index 0f84166ae..c6bbf6af2 100644 --- a/src/resources/extensions/gsd/worktree.ts +++ b/src/resources/extensions/gsd/worktree.ts @@ -42,6 +42,16 @@ function getService(basePath: string): GitServiceImpl { return cachedService; } +/** + * Clear the cached GitServiceImpl. For testing only — forces the next + * getService() call to re-read preferences and create a fresh instance. + * @internal + */ +export function _resetServiceCache(): void { + cachedService = null; + cachedBasePath = null; +} + /** * Set the active milestone ID on the cached GitServiceImpl. * This enables integration branch resolution in getMainBranch(). diff --git a/src/resources/extensions/mcp-client/auth.ts b/src/resources/extensions/mcp-client/auth.ts new file mode 100644 index 000000000..52a3f86c8 --- /dev/null +++ b/src/resources/extensions/mcp-client/auth.ts @@ -0,0 +1,149 @@ +/** + * MCP Client OAuth / Auth helpers + * + * Builds transport options (headers, OAuthClientProvider) from MCP server + * config entries so that HTTP transports can authenticate with remote + * servers (Sentry, Linear, etc.). + * + * Fixes #2160 — MCP HTTP transport lacked an OAuth auth provider. + */ + +import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js"; +import type { StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; + +// ─── Types ──────────────────────────────────────────────────────────────────── + +export interface McpHttpAuthHeaders { + /** Static headers to attach to every request, e.g. `{ Authorization: "Bearer ${TOKEN}" }`. */ + headers?: Record; +} + +export interface McpHttpOAuthConfig { + /** OAuth configuration for servers that require the full OAuth flow. */ + oauth?: { + clientId: string; + clientSecret?: string; + scopes?: string[]; + redirectUrl?: string; + }; +} + +/** Union of all auth-related config fields for an HTTP MCP server. */ +export type McpHttpAuthConfig = McpHttpAuthHeaders & McpHttpOAuthConfig; + +// ─── Env resolution ─────────────────────────────────────────────────────────── + +/** Resolve `${VAR}` references in a string against `process.env`. */ +function resolveEnvValue(value: string): string { + return value.replace( + /\$\{([^}]+)\}/g, + (_match, varName) => process.env[varName] ?? "", + ); +} + +function resolveHeaders(raw: Record): Record { + const resolved: Record = {}; + for (const [key, value] of Object.entries(raw)) { + resolved[key] = typeof value === "string" ? resolveEnvValue(value) : value; + } + return resolved; +} + +// ─── OAuth provider (minimal CLI-friendly implementation) ───────────────────── + +/** + * Creates a minimal `OAuthClientProvider` suitable for CLI / headless use. + * + * This provider supports: + * - Pre-configured client credentials (client_id, optional client_secret) + * - Token storage in memory (per-session) + * - Scopes + * + * For full interactive OAuth flows (browser redirect), a richer provider would + * be needed, but for server-to-server and pre-authed scenarios this is + * sufficient. + */ +function createCliOAuthProvider(config: NonNullable): OAuthClientProvider { + let storedTokens: { access_token: string; token_type: string; refresh_token?: string } | undefined; + let storedCodeVerifier = ""; + + return { + get redirectUrl() { + return config.redirectUrl ?? "http://localhost:0/callback"; + }, + + get clientMetadata() { + return { + redirect_uris: [config.redirectUrl ?? "http://localhost:0/callback"], + client_name: "gsd", + ...(config.scopes ? { scope: config.scopes.join(" ") } : {}), + }; + }, + + clientInformation() { + return { + client_id: config.clientId, + ...(config.clientSecret ? { client_secret: config.clientSecret } : {}), + }; + }, + + tokens() { + return storedTokens; + }, + + saveTokens(tokens) { + storedTokens = tokens as typeof storedTokens; + }, + + redirectToAuthorization(authorizationUrl: URL) { + // In a CLI context we can't open a browser automatically. + // Log the URL so the user can manually visit it. + // eslint-disable-next-line no-console + console.error( + `[MCP OAuth] Authorization required. Visit:\n ${authorizationUrl.toString()}`, + ); + }, + + saveCodeVerifier(codeVerifier: string) { + storedCodeVerifier = codeVerifier; + }, + + codeVerifier() { + return storedCodeVerifier; + }, + }; +} + +// ─── Public API ─────────────────────────────────────────────────────────────── + +/** + * Build `StreamableHTTPClientTransportOptions` from an MCP server config's + * auth-related fields. + * + * Supports two auth strategies: + * 1. **`headers`** — static Authorization (or other) headers, with `${VAR}` env resolution. + * 2. **`oauth`** — full OAuthClientProvider for servers that implement MCP OAuth. + * + * When both are provided, `oauth` takes precedence (the SDK's built-in OAuth + * flow handles token refresh automatically). + */ +export function buildHttpTransportOpts( + authConfig: McpHttpAuthConfig, +): StreamableHTTPClientTransportOptions { + const opts: StreamableHTTPClientTransportOptions = {}; + + // OAuth takes precedence + if (authConfig.oauth) { + opts.authProvider = createCliOAuthProvider(authConfig.oauth); + return opts; + } + + // Static headers (with env var resolution) + if (authConfig.headers && Object.keys(authConfig.headers).length > 0) { + opts.requestInit = { + headers: resolveHeaders(authConfig.headers), + }; + } + + return opts; +} diff --git a/src/resources/extensions/mcp-client/index.ts b/src/resources/extensions/mcp-client/index.ts index 38d001aa1..3cfb5b51b 100644 --- a/src/resources/extensions/mcp-client/index.ts +++ b/src/resources/extensions/mcp-client/index.ts @@ -25,6 +25,8 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js" import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; import { readFileSync, existsSync } from "node:fs"; import { join } from "node:path"; +import { buildHttpTransportOpts } from "./auth.js"; +import type { McpHttpAuthConfig } from "./auth.js"; // ─── Types ──────────────────────────────────────────────────────────────────── @@ -36,6 +38,10 @@ interface McpServerConfig { env?: Record; url?: string; cwd?: string; + /** Static headers for HTTP transport (supports ${VAR} env resolution). */ + headers?: Record; + /** OAuth config for HTTP transport. */ + oauth?: McpHttpAuthConfig["oauth"]; } interface McpToolSchema { @@ -87,6 +93,9 @@ function readConfigs(): McpServerConfig[] { ? "http" : "unknown"; + const hasHeaders = hasUrl && config.headers && typeof config.headers === "object"; + const hasOAuth = hasUrl && config.oauth && typeof config.oauth === "object"; + servers.push({ name, transport, @@ -99,6 +108,8 @@ function readConfigs(): McpServerConfig[] { cwd: typeof config.cwd === "string" ? config.cwd : undefined, }), ...(hasUrl && { url: config.url as string }), + headers: hasHeaders ? config.headers as Record : undefined, + oauth: hasOAuth ? config.oauth as McpHttpAuthConfig["oauth"] : undefined, }); } } catch { @@ -111,7 +122,11 @@ function readConfigs(): McpServerConfig[] { } function getServerConfig(name: string): McpServerConfig | undefined { - return readConfigs().find((s) => s.name === name); + const trimmed = name.trim(); + return readConfigs().find((s) => + s.name === trimmed || + s.name.toLowerCase() === trimmed.toLowerCase(), + ); } /** Resolve ${VAR} references in env values against process.env. */ @@ -131,12 +146,14 @@ function resolveEnv(env: Record): Record { } async function getOrConnect(name: string, signal?: AbortSignal): Promise { - const existing = connections.get(name); - if (existing) return existing.client; - const config = getServerConfig(name); if (!config) throw new Error(`Unknown MCP server: "${name}". Use mcp_servers to list available servers.`); + // Always use config.name as the canonical cache key so that variant + // casing / whitespace still hits the same connection. + const existing = connections.get(config.name); + if (existing) return existing.client; + const client = new Client({ name: "gsd", version: "1.0.0" }); let transport: StdioClientTransport | StreamableHTTPClientTransport; @@ -151,15 +168,19 @@ async function getOrConnect(name: string, signal?: AbortSignal): Promise } else if (config.transport === "http" && config.url) { const resolvedUrl = config.url.replace( /\$\{([^}]+)\}/g, - (_, name) => process.env[name] ?? "", + (_, varName) => process.env[varName] ?? "", ); - transport = new StreamableHTTPClientTransport(new URL(resolvedUrl)); + const httpOpts = buildHttpTransportOpts({ + headers: config.headers, + oauth: config.oauth, + }); + transport = new StreamableHTTPClientTransport(new URL(resolvedUrl), httpOpts); } else { - throw new Error(`Server "${name}" has unsupported transport: ${config.transport}`); + throw new Error(`Server "${config.name}" has unsupported transport: ${config.transport}`); } await client.connect(transport, { signal, timeout: 30000 }); - connections.set(name, { client, transport }); + connections.set(config.name, { client, transport }); return client; } diff --git a/src/resources/extensions/mcp-client/tests/server-name-spaces.test.ts b/src/resources/extensions/mcp-client/tests/server-name-spaces.test.ts new file mode 100644 index 000000000..1cdb30f6e --- /dev/null +++ b/src/resources/extensions/mcp-client/tests/server-name-spaces.test.ts @@ -0,0 +1,55 @@ +/** + * Regression test for #3029 — mcp_discover fails for server names with spaces. + * + * The getServerConfig lookup must handle: + * 1. Exact match (already works) + * 2. Names with leading/trailing whitespace (trimming) + * 3. Case-insensitive matching (e.g. "Langgraph code" vs "langgraph Code") + * + * We test at the source level since getServerConfig is not exported. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, "..", "index.ts"), "utf-8"); + +test("#3029: getServerConfig trims whitespace from input name", () => { + assert.ok( + source.includes(".trim()"), + "getServerConfig should trim the input name before comparison", + ); +}); + +test("#3029: getServerConfig performs case-insensitive matching", () => { + assert.ok( + source.includes(".toLowerCase()"), + "getServerConfig should compare names case-insensitively", + ); +}); + +test("#3029: getOrConnect normalizes name for connection cache lookup", () => { + // The connections Map key must use the canonical (config) name, not the + // raw user input, so that subsequent lookups hit the cache even when the + // user's casing differs. + const getOrConnectMatch = source.match( + /async function getOrConnect\(name: string[\s\S]*?const existing = connections\.get\(/, + ); + assert.ok( + getOrConnectMatch, + "getOrConnect function should exist", + ); + // After the fix, getOrConnect should normalize the name via getServerConfig + // or use config.name as the canonical cache key. + assert.ok( + source.includes("connections.get(config.name") || + source.includes("connections.set(config.name"), + "getOrConnect should use config.name (canonical) as the connections cache key", + ); +}); diff --git a/src/resources/extensions/ollama/index.ts b/src/resources/extensions/ollama/index.ts new file mode 100644 index 000000000..7f87c6e77 --- /dev/null +++ b/src/resources/extensions/ollama/index.ts @@ -0,0 +1,131 @@ +// GSD2 — Ollama Extension: First-class local LLM support +/** + * Ollama Extension + * + * Auto-detects a running Ollama instance, discovers locally pulled models, + * and registers them as a first-class provider. No configuration required — + * if Ollama is running, models appear automatically. + * + * Features: + * - Auto-discovery of local models via /api/tags + * - Capability detection (vision, reasoning, context window) + * - /ollama slash commands for model management + * - ollama_manage tool for LLM-driven model operations + * - Zero-cost model registration (local inference) + * + * Respects OLLAMA_HOST env var for non-default endpoints. + */ + +import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent"; +import * as client from "./ollama-client.js"; +import { discoverModels } from "./ollama-discovery.js"; +import { registerOllamaCommands } from "./ollama-commands.js"; +import { streamOllamaChat } from "./ollama-chat-provider.js"; + +let toolsPromise: Promise | null = null; + +async function registerOllamaTools(pi: ExtensionAPI): Promise { + if (!toolsPromise) { + toolsPromise = (async () => { + const { registerOllamaTool } = await importExtensionModule< + typeof import("./ollama-tool.js") + >(import.meta.url, "./ollama-tool.js"); + registerOllamaTool(pi); + })().catch((error) => { + toolsPromise = null; + throw error; + }); + } + return toolsPromise; +} + +/** Track whether we've registered models so we can clean up on shutdown */ +let providerRegistered = false; + +/** + * Probe Ollama and register discovered models. + * Safe to call multiple times — re-discovers and re-registers. + */ +async function probeAndRegister(pi: ExtensionAPI): Promise { + const running = await client.isRunning(); + if (!running) { + if (providerRegistered) { + pi.unregisterProvider("ollama"); + providerRegistered = false; + } + return false; + } + + const models = await discoverModels(); + if (models.length === 0) return true; // Running but no models pulled + + const baseUrl = client.getOllamaHost(); + + // Use authMode "apiKey" with a dummy key (#3440). + // authMode "none" requires a custom streamSimple handler, but Ollama uses + // the standard OpenAI-compatible streaming endpoint. Ollama ignores the + // Authorization header so the dummy key is harmless. + pi.registerProvider("ollama", { + authMode: "apiKey", + apiKey: "ollama", + baseUrl, + api: "ollama-chat", + streamSimple: streamOllamaChat, + isReady: () => true, + models: models.map((m) => ({ + id: m.id, + name: m.name, + reasoning: m.reasoning, + input: m.input, + cost: m.cost, + contextWindow: m.contextWindow, + maxTokens: m.maxTokens, + providerOptions: (m.ollamaOptions ?? {}) as Record, + })), + }); + + providerRegistered = true; + return true; +} + +export default function ollama(pi: ExtensionAPI) { + // Register slash commands immediately (they check Ollama availability themselves) + registerOllamaCommands(pi); + + pi.on("session_start", async (_event, ctx) => { + // Register tool (deferred to avoid blocking startup) + if (ctx.hasUI) { + void registerOllamaTools(pi).catch((error) => { + ctx.ui.notify( + `Ollama tool failed to load: ${error instanceof Error ? error.message : String(error)}`, + "warning", + ); + }); + } else { + await registerOllamaTools(pi); + } + + // In headless/auto mode, await the probe so the fallback resolver can + // see Ollama before the first LLM call (#3531 race condition). + // In interactive mode, keep it async for fast startup. + if (!ctx.hasUI) { + try { + await probeAndRegister(pi); + } catch { /* non-fatal */ } + } else { + probeAndRegister(pi) + .then((found) => { + if (found) ctx.ui.setStatus("ollama", "Ollama"); + }) + .catch(() => {}); + } + }); + + pi.on("session_shutdown", async () => { + if (providerRegistered) { + pi.unregisterProvider("ollama"); + providerRegistered = false; + } + toolsPromise = null; + }); +} diff --git a/src/resources/extensions/ollama/model-capabilities.ts b/src/resources/extensions/ollama/model-capabilities.ts new file mode 100644 index 000000000..f44506fbf --- /dev/null +++ b/src/resources/extensions/ollama/model-capabilities.ts @@ -0,0 +1,152 @@ +// GSD2 — Known model capability table for Ollama models + +/** + * Maps well-known Ollama model families to their capabilities. + * Used to enrich auto-discovered models with accurate context windows, + * vision support, and reasoning detection. + * + * Fallback: estimate from parameter count if model isn't in the table. + */ + +import type { OllamaChatOptions } from "./types.js"; + +export interface ModelCapability { + contextWindow?: number; + maxTokens?: number; + input?: ("text" | "image")[]; + reasoning?: boolean; + /** Ollama-specific default inference options for this model family. */ + ollamaOptions?: OllamaChatOptions; +} + +/** + * Known model family capabilities. + * Keys are matched as prefixes against the model name (before the colon/tag). + * More specific entries should appear first. + */ +// Note: ollamaOptions.num_ctx is set for known model families where the context +// window is authoritative. For unknown/estimated models, num_ctx is NOT sent +// to avoid OOM risk — Ollama uses its own safe default instead. +const KNOWN_MODELS: Array<[pattern: string, caps: ModelCapability]> = [ + // ─── Reasoning models ─────────────────────────────────────────────── + ["deepseek-r1", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }], + ["qwq", { contextWindow: 131072, reasoning: true, ollamaOptions: { num_ctx: 131072 } }], + + // ─── Vision models ────────────────────────────────────────────────── + ["llava", { contextWindow: 4096, input: ["text", "image"], ollamaOptions: { num_ctx: 4096 } }], + ["bakllava", { contextWindow: 4096, input: ["text", "image"], ollamaOptions: { num_ctx: 4096 } }], + ["moondream", { contextWindow: 8192, input: ["text", "image"], ollamaOptions: { num_ctx: 8192 } }], + ["llama3.2-vision", { contextWindow: 131072, input: ["text", "image"], ollamaOptions: { num_ctx: 131072 } }], + ["minicpm-v", { contextWindow: 4096, input: ["text", "image"], ollamaOptions: { num_ctx: 4096 } }], + + // ─── Code models ──────────────────────────────────────────────────── + ["codestral", { contextWindow: 262144, maxTokens: 32768, ollamaOptions: { num_ctx: 262144 } }], + ["qwen2.5-coder", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }], + ["deepseek-coder-v2", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["starcoder2", { contextWindow: 16384, maxTokens: 8192, ollamaOptions: { num_ctx: 16384 } }], + ["codegemma", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }], + ["codellama", { contextWindow: 16384, maxTokens: 8192, ollamaOptions: { num_ctx: 16384 } }], + ["devstral", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }], + + // ─── Llama family ─────────────────────────────────────────────────── + ["llama3.3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["llama3.2", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["llama3.1", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["llama3", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }], + ["llama2", { contextWindow: 4096, maxTokens: 4096, ollamaOptions: { num_ctx: 4096 } }], + + // ─── Qwen family ──────────────────────────────────────────────────── + ["qwen3", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }], + ["qwen2.5", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }], + ["qwen2", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }], + + // ─── Gemma family ─────────────────────────────────────────────────── + ["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }], + + // ─── Mistral family ───────────────────────────────────────────────── + ["mistral-large", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["mistral-small", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["mistral-nemo", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["mistral", { contextWindow: 32768, maxTokens: 8192, ollamaOptions: { num_ctx: 32768 } }], + ["mixtral", { contextWindow: 32768, maxTokens: 8192, ollamaOptions: { num_ctx: 32768 } }], + + // ─── Phi family ───────────────────────────────────────────────────── + ["phi4", { contextWindow: 16384, maxTokens: 16384, ollamaOptions: { num_ctx: 16384 } }], + ["phi3.5", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["phi3", { contextWindow: 131072, maxTokens: 4096, ollamaOptions: { num_ctx: 131072 } }], + + // ─── Command R ────────────────────────────────────────────────────── + ["command-r-plus", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], + ["command-r", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }], +]; + +/** + * Look up capabilities for a model by name. + * Matches the longest prefix from the known models table. + */ +export function getModelCapabilities(modelName: string): ModelCapability { + // Strip tag (everything after the colon) for matching + const baseName = modelName.split(":")[0].toLowerCase(); + + for (const [pattern, caps] of KNOWN_MODELS) { + if (baseName === pattern || baseName.startsWith(pattern)) { + return caps; + } + } + + return {}; +} + +/** + * Estimate context window from parameter size string (e.g. "7B", "70B", "1.5B"). + * Used as fallback when model isn't in the known table. + */ +export function estimateContextFromParams(parameterSize: string): number { + const match = parameterSize.match(/([\d.]+)\s*([BbMm])/); + if (!match) return 8192; + + const size = parseFloat(match[1]); + const unit = match[2].toUpperCase(); + + // Convert to billions + const billions = unit === "M" ? size / 1000 : size; + + // Rough heuristics: larger models tend to support larger contexts + if (billions >= 70) return 131072; + if (billions >= 30) return 65536; + if (billions >= 13) return 32768; + if (billions >= 7) return 16384; + return 8192; +} + +/** + * Humanize a model name for display (e.g. "llama3.1:8b" → "Llama 3.1 8B"). + */ +export function humanizeModelName(modelName: string): string { + const [base, tag] = modelName.split(":"); + + // Capitalize first letter, add spaces around version numbers + let name = base + .replace(/([a-z])(\d)/g, "$1 $2") + .replace(/(\d)([a-z])/g, "$1 $2") + .replace(/^./, (c) => c.toUpperCase()); + + // Clean up common patterns + name = name.replace(/\s*-\s*/g, " "); + + if (tag && tag !== "latest") { + name += ` ${tag.toUpperCase()}`; + } + + return name; +} + +/** + * Format byte size for display (e.g. 4700000000 → "4.7 GB"). + */ +export function formatModelSize(bytes: number): string { + if (bytes >= 1e9) return `${(bytes / 1e9).toFixed(1)} GB`; + if (bytes >= 1e6) return `${(bytes / 1e6).toFixed(1)} MB`; + return `${(bytes / 1e3).toFixed(0)} KB`; +} diff --git a/src/resources/extensions/ollama/ndjson-stream.ts b/src/resources/extensions/ollama/ndjson-stream.ts new file mode 100644 index 000000000..32065aa4e --- /dev/null +++ b/src/resources/extensions/ollama/ndjson-stream.ts @@ -0,0 +1,63 @@ +// GSD2 — Ollama Extension: NDJSON streaming parser + +/** + * Parses a streaming NDJSON (newline-delimited JSON) response body into + * typed objects. Used for Ollama's /api/chat and /api/pull endpoints. + * + * @param strict When true, malformed JSON lines throw instead of being skipped. + * Use strict mode for inference streams where silent data loss is unacceptable. + * Use permissive mode (default) for progress endpoints like /api/pull. + */ + +export async function* parseNDJsonStream( + body: ReadableStream, + signal?: AbortSignal, + strict = false, +): AsyncGenerator { + const reader = body.getReader(); + const decoder = new TextDecoder(); + let buffer = ""; + + try { + while (true) { + if (signal?.aborted) break; + + const { done, value } = await reader.read(); + if (done) break; + + buffer += decoder.decode(value, { stream: true }); + const lines = buffer.split("\n"); + buffer = lines.pop() ?? ""; + + for (const line of lines) { + const trimmed = line.trim(); + if (!trimmed) continue; + try { + yield JSON.parse(trimmed) as T; + } catch (err) { + if (strict) { + throw new Error( + `Malformed NDJSON line from Ollama: ${trimmed.slice(0, 200)}`, + ); + } + // Permissive mode: skip malformed lines + } + } + } + + // Flush remaining buffer (skip if aborted) + if (buffer.trim() && !signal?.aborted) { + try { + yield JSON.parse(buffer.trim()) as T; + } catch (err) { + if (strict) { + throw new Error( + `Malformed NDJSON line from Ollama: ${buffer.trim().slice(0, 200)}`, + ); + } + } + } + } finally { + reader.releaseLock(); + } +} diff --git a/src/resources/extensions/ollama/ollama-auth-mode.test.ts b/src/resources/extensions/ollama/ollama-auth-mode.test.ts new file mode 100644 index 000000000..e74f2e76c --- /dev/null +++ b/src/resources/extensions/ollama/ollama-auth-mode.test.ts @@ -0,0 +1,20 @@ +/** + * Regression test for #3440: Ollama extension must register with + * authMode "apiKey" (not "none") to avoid streamSimple requirement. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +test("Ollama registers with authMode apiKey, not none (#3440)", () => { + const src = readFileSync(join(__dirname, "index.ts"), "utf-8"); + // Find the registerProvider call + const registerBlock = src.slice(src.indexOf("pi.registerProvider(\"ollama\"")); + const authLine = registerBlock.match(/authMode:\s*"(\w+)"/); + assert.ok(authLine, "registerProvider must specify authMode"); + assert.equal(authLine![1], "apiKey", "authMode must be apiKey, not none"); +}); diff --git a/src/resources/extensions/ollama/ollama-chat-provider.ts b/src/resources/extensions/ollama/ollama-chat-provider.ts new file mode 100644 index 000000000..81e1de6f4 --- /dev/null +++ b/src/resources/extensions/ollama/ollama-chat-provider.ts @@ -0,0 +1,459 @@ +// GSD2 — Ollama Extension: Native /api/chat stream provider + +/** + * Implements the "ollama-chat" API provider, streaming responses directly + * from Ollama's native /api/chat endpoint instead of the OpenAI compatibility + * shim. This exposes Ollama-specific options (num_ctx, keep_alive, num_gpu, + * sampling parameters) and surfaces inference performance metrics. + */ + +import { + type Api, + type AssistantMessage, + type AssistantMessageEvent, + type AssistantMessageEventStream, + type Context, + type ImageContent, + type InferenceMetrics, + type Message, + type Model, + type SimpleStreamOptions, + type StopReason, + type TextContent, + type ThinkingContent, + type Tool, + type ToolCall, + type Usage, + EventStream, +} from "@gsd/pi-ai"; +import { chat } from "./ollama-client.js"; +import type { + OllamaChatMessage, + OllamaChatOptions, + OllamaChatRequest, + OllamaChatResponse, + OllamaTool, + OllamaToolCall, +} from "./types.js"; +import { ThinkingTagParser, type ParsedChunk } from "./thinking-parser.js"; + +/** Create an AssistantMessageEventStream using the base EventStream class. */ +function createStream(): AssistantMessageEventStream { + return new EventStream( + (event) => event.type === "done" || event.type === "error", + (event) => { + if (event.type === "done") return event.message; + if (event.type === "error") return event.error; + throw new Error("Unexpected event type for final result"); + }, + ) as AssistantMessageEventStream; +} + +// ─── Stream handler ───────────────────────────────────────────────────────── + +export function streamOllamaChat( + model: Model, + context: Context, + options?: SimpleStreamOptions, +): AssistantMessageEventStream { + const stream = createStream(); + + (async () => { + const output = buildInitialOutput(model); + + try { + const request = buildRequest(model, context, options); + stream.push({ type: "start", partial: output }); + + const useThinkingParser = model.reasoning; + const thinkParser = useThinkingParser ? new ThinkingTagParser() : null; + + let contentIndex = -1; + let currentBlockType: "text" | "thinking" | null = null; + + function startBlock(type: "text" | "thinking") { + contentIndex++; + currentBlockType = type; + if (type === "text") { + output.content.push({ type: "text", text: "" }); + stream.push({ type: "text_start", contentIndex, partial: output }); + } else { + output.content.push({ type: "thinking", thinking: "" }); + stream.push({ type: "thinking_start", contentIndex, partial: output }); + } + } + + function endBlock() { + if (currentBlockType === null) return; + if (currentBlockType === "text") { + const block = output.content[contentIndex] as TextContent; + stream.push({ type: "text_end", contentIndex, content: block.text, partial: output }); + } else { + const block = output.content[contentIndex] as ThinkingContent; + stream.push({ type: "thinking_end", contentIndex, content: block.thinking, partial: output }); + } + currentBlockType = null; + } + + function emitDelta(type: "text" | "thinking", text: string) { + if (!text) return; + if (currentBlockType !== type) { + endBlock(); + startBlock(type); + } + if (type === "text") { + (output.content[contentIndex] as TextContent).text += text; + stream.push({ type: "text_delta", contentIndex, delta: text, partial: output }); + } else { + (output.content[contentIndex] as ThinkingContent).thinking += text; + stream.push({ type: "thinking_delta", contentIndex, delta: text, partial: output }); + } + } + + function processChunks(chunks: ParsedChunk[]) { + for (const chunk of chunks) { + emitDelta(chunk.type, chunk.text); + } + } + + function processToolCalls(toolCalls: OllamaToolCall[]) { + endBlock(); + for (const tc of toolCalls) { + contentIndex++; + const toolCall: ToolCall = { + type: "toolCall", + id: `ollama_tc_${contentIndex}`, + name: tc.function.name, + arguments: tc.function.arguments, + }; + output.content.push(toolCall); + stream.push({ type: "toolcall_start", contentIndex, partial: output }); + // Emit a delta with the serialized arguments (convention: start/delta/end) + stream.push({ + type: "toolcall_delta", + contentIndex, + delta: JSON.stringify(tc.function.arguments), + partial: output, + }); + stream.push({ + type: "toolcall_end", + contentIndex, + toolCall, + partial: output, + }); + } + output.stopReason = "toolUse"; + } + + for await (const chunk of chat(request, options?.signal)) { + // Handle text content — process independently of tool_calls + // (a chunk may contain both content and tool_calls) + const content = chunk.message?.content ?? ""; + if (content) { + if (thinkParser) { + processChunks(thinkParser.push(content)); + } else { + emitDelta("text", content); + } + } + + // Handle tool calls (Ollama sends them complete, may be on done:true chunk) + if (chunk.message?.tool_calls?.length) { + processToolCalls(chunk.message.tool_calls); + } + + if (chunk.done) { + // Final chunk — extract metrics and usage + if (thinkParser) processChunks(thinkParser.flush()); + endBlock(); + + output.usage = buildUsage(chunk); + output.inferenceMetrics = extractMetrics(chunk); + // Preserve "toolUse" if tool calls were processed + if (output.stopReason !== "toolUse") { + output.stopReason = mapStopReason(chunk.done_reason); + } + break; + } + } + + assertStreamSuccess(output, options?.signal); + finalizeStream(stream, output); + } catch (error) { + handleStreamError(stream, output, error, options?.signal); + } + })(); + + return stream; +} + +// ─── Request building ─────────────────────────────────────────────────────── + +function buildRequest( + model: Model, + context: Context, + options?: SimpleStreamOptions, +): OllamaChatRequest { + const ollamaOpts = (model.providerOptions ?? {}) as OllamaChatOptions; + + const request: OllamaChatRequest = { + model: model.id, + messages: convertMessages(context), + stream: true, + }; + + // Build options block with all Ollama-specific parameters + const reqOptions: NonNullable = {}; + + // Context window — only sent when explicitly configured via providerOptions. + // Sending inferred/estimated values risks OOM on constrained hosts. + // Users can set num_ctx per-model in models.json ollamaOptions or the + // capability table can provide it for known model families. + if (ollamaOpts.num_ctx !== undefined && ollamaOpts.num_ctx > 0) { + reqOptions.num_ctx = ollamaOpts.num_ctx; + } + + // Max output tokens + const maxTokens = options?.maxTokens ?? model.maxTokens; + if (maxTokens > 0) { + reqOptions.num_predict = maxTokens; + } + + // Temperature + if (options?.temperature !== undefined) { + reqOptions.temperature = options.temperature; + } + + // Per-model sampling options from providerOptions + if (ollamaOpts.top_p !== undefined) reqOptions.top_p = ollamaOpts.top_p; + if (ollamaOpts.top_k !== undefined) reqOptions.top_k = ollamaOpts.top_k; + if (ollamaOpts.repeat_penalty !== undefined) reqOptions.repeat_penalty = ollamaOpts.repeat_penalty; + if (ollamaOpts.seed !== undefined) reqOptions.seed = ollamaOpts.seed; + if (ollamaOpts.num_gpu !== undefined) reqOptions.num_gpu = ollamaOpts.num_gpu; + + if (Object.keys(reqOptions).length > 0) { + request.options = reqOptions; + } + + // Keep alive + if (ollamaOpts.keep_alive !== undefined) { + request.keep_alive = ollamaOpts.keep_alive; + } + + // Tools + if (context.tools?.length) { + request.tools = convertTools(context.tools); + } + + return request; +} + +// ─── Message conversion ───────────────────────────────────────────────────── + +function convertMessages(context: Context): OllamaChatMessage[] { + const messages: OllamaChatMessage[] = []; + + // System prompt + if (context.systemPrompt) { + messages.push({ role: "system", content: context.systemPrompt }); + } + + for (const msg of context.messages) { + switch (msg.role) { + case "user": + messages.push(convertUserMessage(msg)); + break; + case "assistant": + messages.push(convertAssistantMessage(msg)); + break; + case "toolResult": + messages.push({ + role: "tool", + content: msg.content + .filter((c): c is TextContent => c.type === "text") + .map((c) => c.text) + .join("\n"), + name: msg.toolName, + }); + break; + } + } + + return messages; +} + +function convertUserMessage(msg: Message & { role: "user" }): OllamaChatMessage { + if (typeof msg.content === "string") { + return { role: "user", content: msg.content }; + } + + const textParts: string[] = []; + const images: string[] = []; + + for (const part of msg.content) { + if (part.type === "text") { + textParts.push(part.text); + } else if (part.type === "image") { + // Strip data URI prefix if present + let data = (part as ImageContent).data; + const commaIdx = data.indexOf(","); + if (commaIdx !== -1 && data.startsWith("data:")) { + data = data.slice(commaIdx + 1); + } + images.push(data); + } + } + + const result: OllamaChatMessage = { + role: "user", + content: textParts.join("\n"), + }; + if (images.length > 0) { + result.images = images; + } + return result; +} + +function convertAssistantMessage(msg: Message & { role: "assistant" }): OllamaChatMessage { + let content = ""; + const toolCalls: OllamaChatMessage["tool_calls"] = []; + + for (const block of msg.content) { + if (block.type === "thinking") { + // Serialize thinking back inline for round-trip with Ollama + content += `${(block as ThinkingContent).thinking}`; + } else if (block.type === "text") { + content += (block as TextContent).text; + } else if (block.type === "toolCall") { + const tc = block as ToolCall; + toolCalls.push({ + function: { + name: tc.name, + arguments: tc.arguments, + }, + }); + } + } + + const result: OllamaChatMessage = { role: "assistant", content }; + if (toolCalls.length > 0) { + result.tool_calls = toolCalls; + } + return result; +} + +// ─── Tool conversion ──────────────────────────────────────────────────────── + +function convertTools(tools: Tool[]): OllamaTool[] { + return tools.map((tool) => { + const params = tool.parameters as Record; + return { + type: "function" as const, + function: { + name: tool.name, + description: tool.description, + parameters: { + type: "object" as const, + required: params.required as string[] | undefined, + properties: (params.properties as Record) ?? {}, + }, + }, + }; + }); +} + +// ─── Response mapping ─────────────────────────────────────────────────────── + +function mapStopReason(doneReason?: string): StopReason { + switch (doneReason) { + case "stop": + return "stop"; + case "length": + return "length"; + default: + return "stop"; + } +} + +function buildUsage(chunk: OllamaChatResponse): Usage { + const input = chunk.prompt_eval_count ?? 0; + const outputTokens = chunk.eval_count ?? 0; + return { + input, + output: outputTokens, + cacheRead: 0, + cacheWrite: 0, + totalTokens: input + outputTokens, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }; +} + +function extractMetrics(chunk: OllamaChatResponse): InferenceMetrics | undefined { + if (!chunk.eval_duration && !chunk.total_duration) return undefined; + + const evalCount = chunk.eval_count ?? 0; + const evalDurationNs = chunk.eval_duration ?? 0; + const evalDurationMs = evalDurationNs / 1e6; + const tokensPerSecond = evalDurationNs > 0 ? evalCount / (evalDurationNs / 1e9) : 0; + + return { + tokensPerSecond, + totalDurationMs: (chunk.total_duration ?? 0) / 1e6, + evalDurationMs, + promptEvalDurationMs: (chunk.prompt_eval_duration ?? 0) / 1e6, + }; +} + +// ─── Stream lifecycle helpers ─────────────────────────────────────────────── +// Replicated from openai-shared.ts (not exported from @gsd/pi-ai) + +function buildInitialOutput(model: Model): AssistantMessage { + return { + role: "assistant", + content: [], + api: model.api as Api, + provider: model.provider, + model: model.id, + usage: { + input: 0, + output: 0, + cacheRead: 0, + cacheWrite: 0, + totalTokens: 0, + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }, + }, + stopReason: "stop", + timestamp: Date.now(), + }; +} + +function assertStreamSuccess(output: AssistantMessage, signal?: AbortSignal): void { + if (signal?.aborted) { + throw new Error("Request was aborted"); + } + if (output.stopReason === "aborted" || output.stopReason === "error") { + throw new Error("An unknown error occurred"); + } +} + +function finalizeStream(stream: AssistantMessageEventStream, output: AssistantMessage): void { + stream.push({ + type: "done", + reason: output.stopReason as Extract, + message: output, + }); + stream.end(); +} + +function handleStreamError( + stream: AssistantMessageEventStream, + output: AssistantMessage, + error: unknown, + signal?: AbortSignal, +): void { + for (const block of output.content) delete (block as { index?: number }).index; + output.stopReason = signal?.aborted ? "aborted" : "error"; + output.errorMessage = error instanceof Error ? error.message : JSON.stringify(error); + stream.push({ type: "error", reason: output.stopReason, error: output }); + stream.end(); +} diff --git a/src/resources/extensions/ollama/ollama-client.ts b/src/resources/extensions/ollama/ollama-client.ts new file mode 100644 index 000000000..4738c09da --- /dev/null +++ b/src/resources/extensions/ollama/ollama-client.ts @@ -0,0 +1,196 @@ +// GSD2 — HTTP client for Ollama REST API + +/** + * Low-level HTTP client for the Ollama REST API. + * Respects the OLLAMA_HOST environment variable for non-default endpoints. + * + * Reference: https://github.com/ollama/ollama/blob/main/docs/api.md + */ + +import type { + OllamaChatRequest, + OllamaChatResponse, + OllamaPsResponse, + OllamaPullProgress, + OllamaShowResponse, + OllamaTagsResponse, + OllamaVersionResponse, +} from "./types.js"; +import { parseNDJsonStream } from "./ndjson-stream.js"; + +const DEFAULT_HOST = "http://localhost:11434"; +const PROBE_TIMEOUT_MS = 1500; +const REQUEST_TIMEOUT_MS = 10000; + +/** + * Get the Ollama host URL from OLLAMA_HOST or default. + */ +export function getOllamaHost(): string { + const host = process.env.OLLAMA_HOST; + if (!host) return DEFAULT_HOST; + + // OLLAMA_HOST can be just a host:port without scheme + if (host.startsWith("http://") || host.startsWith("https://")) return host; + return `http://${host}`; +} + +async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = REQUEST_TIMEOUT_MS): Promise { + const controller = new AbortController(); + const timeout = setTimeout(() => controller.abort(), timeoutMs); + try { + return await fetch(url, { ...options, signal: controller.signal }); + } finally { + clearTimeout(timeout); + } +} + +/** + * Check if Ollama is running and reachable. + */ +export async function isRunning(): Promise { + try { + const response = await fetchWithTimeout(`${getOllamaHost()}/`, {}, PROBE_TIMEOUT_MS); + return response.ok; + } catch { + return false; + } +} + +/** + * Get Ollama version. + */ +export async function getVersion(): Promise { + try { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/version`); + if (!response.ok) return null; + const data = (await response.json()) as OllamaVersionResponse; + return data.version; + } catch { + return null; + } +} + +/** + * List all locally available models. + */ +export async function listModels(): Promise { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/tags`); + if (!response.ok) { + throw new Error(`Ollama /api/tags returned ${response.status}: ${response.statusText}`); + } + return (await response.json()) as OllamaTagsResponse; +} + +/** + * Get detailed information about a specific model. + */ +export async function showModel(name: string): Promise { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/show`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name }), + }); + if (!response.ok) { + throw new Error(`Ollama /api/show returned ${response.status}: ${response.statusText}`); + } + return (await response.json()) as OllamaShowResponse; +} + +/** + * List currently loaded/running models. + */ +export async function getRunningModels(): Promise { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/ps`); + if (!response.ok) { + throw new Error(`Ollama /api/ps returned ${response.status}: ${response.statusText}`); + } + return (await response.json()) as OllamaPsResponse; +} + +/** + * Pull a model with streaming progress. + * Calls onProgress for each progress update. + * Returns when the pull is complete. + */ +export async function pullModel( + name: string, + onProgress?: (progress: OllamaPullProgress) => void, + signal?: AbortSignal, +): Promise { + const response = await fetch(`${getOllamaHost()}/api/pull`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name, stream: true }), + signal, + }); + + if (!response.ok) { + const text = await response.text(); + throw new Error(`Ollama /api/pull returned ${response.status}: ${text}`); + } + + if (!response.body) { + throw new Error("Ollama /api/pull returned no body"); + } + + for await (const progress of parseNDJsonStream(response.body, signal)) { + onProgress?.(progress); + } +} + +/** + * Stream a chat completion via /api/chat. + * Returns an async generator yielding each NDJSON response chunk. + */ +export async function* chat( + request: OllamaChatRequest, + signal?: AbortSignal, +): AsyncGenerator { + const response = await fetch(`${getOllamaHost()}/api/chat`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(request), + signal, + }); + + if (!response.ok) { + const text = await response.text(); + throw new Error(`Ollama /api/chat returned ${response.status}: ${text}`); + } + + if (!response.body) { + throw new Error("Ollama /api/chat returned no body"); + } + + yield* parseNDJsonStream(response.body, signal, true); +} + +/** + * Delete a local model. + */ +export async function deleteModel(name: string): Promise { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/delete`, { + method: "DELETE", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name }), + }); + if (!response.ok) { + const text = await response.text(); + throw new Error(`Ollama /api/delete returned ${response.status}: ${text}`); + } +} + +/** + * Copy a model to a new name. + */ +export async function copyModel(source: string, destination: string): Promise { + const response = await fetchWithTimeout(`${getOllamaHost()}/api/copy`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ source, destination }), + }); + if (!response.ok) { + const text = await response.text(); + throw new Error(`Ollama /api/copy returned ${response.status}: ${text}`); + } +} diff --git a/src/resources/extensions/ollama/ollama-commands.ts b/src/resources/extensions/ollama/ollama-commands.ts new file mode 100644 index 000000000..81322c784 --- /dev/null +++ b/src/resources/extensions/ollama/ollama-commands.ts @@ -0,0 +1,248 @@ +// GSD2 — Ollama slash commands + +/** + * Registers /ollama slash commands for managing local Ollama models. + * + * Commands: + * /ollama — Show status (running?, version, loaded models) + * /ollama list — List all available local models with sizes + * /ollama pull — Pull a model with progress + * /ollama remove — Delete a local model + * /ollama ps — Show running models and resource usage + */ + +import type { ExtensionAPI } from "@gsd/pi-coding-agent"; +import { Text } from "@gsd/pi-tui"; +import * as client from "./ollama-client.js"; +import { discoverModels, formatModelForDisplay } from "./ollama-discovery.js"; +import { formatModelSize } from "./model-capabilities.js"; + +export function registerOllamaCommands(pi: ExtensionAPI): void { + pi.registerCommand("ollama", { + description: "Manage local Ollama models — list | pull | remove | ps", + async handler(args, ctx) { + const parts = (args ?? "").trim().split(/\s+/); + const subcommand = parts[0] || "status"; + const modelArg = parts.slice(1).join(" "); + + switch (subcommand) { + case "status": + return await handleStatus(ctx); + case "list": + case "ls": + return await handleList(ctx); + case "pull": + return await handlePull(modelArg, ctx); + case "remove": + case "rm": + case "delete": + return await handleRemove(modelArg, ctx); + case "ps": + return await handlePs(ctx); + default: + ctx.ui.notify( + `Unknown subcommand: ${subcommand}. Use: status, list, pull, remove, ps`, + "warning", + ); + } + }, + }); +} + +async function handleStatus(ctx: any): Promise { + const running = await client.isRunning(); + if (!running) { + ctx.ui.notify( + "Ollama is not running. Install from https://ollama.com and run 'ollama serve'", + "warning", + ); + return; + } + + const version = await client.getVersion(); + const lines: string[] = []; + lines.push(`Ollama${version ? ` v${version}` : ""} — running (${client.getOllamaHost()})`); + + // Show loaded models + try { + const ps = await client.getRunningModels(); + if (ps.models && ps.models.length > 0) { + lines.push(""); + lines.push("Loaded:"); + for (const m of ps.models) { + const vram = m.size_vram > 0 ? formatModelSize(m.size_vram) + " VRAM" : "CPU"; + const expiresAt = new Date(m.expires_at); + const idleMs = expiresAt.getTime() - Date.now(); + const idleMin = Math.max(0, Math.floor(idleMs / 60000)); + lines.push(` ${m.name} ${vram} expires in ${idleMin}m`); + } + } + } catch { + // ps endpoint may not be available on older versions + } + + // Show available models + try { + const models = await discoverModels(); + if (models.length > 0) { + lines.push(""); + lines.push("Available:"); + for (const m of models) { + lines.push(` ${formatModelForDisplay(m)}`); + } + } else { + lines.push(""); + lines.push("No models pulled. Use /ollama pull to get started."); + } + } catch (err) { + lines.push(""); + lines.push(`Error listing models: ${err instanceof Error ? err.message : String(err)}`); + } + + await ctx.ui.custom( + (tui: any, theme: any, _kb: any, done: (r: undefined) => void) => { + const text = new Text(lines.map((l) => theme.fg("fg", l)).join("\n"), 0, 0); + setTimeout(() => done(undefined), 0); + return text; + }, + ); +} + +async function handleList(ctx: any): Promise { + const running = await client.isRunning(); + if (!running) { + ctx.ui.notify("Ollama is not running", "warning"); + return; + } + + const models = await discoverModels(); + if (models.length === 0) { + ctx.ui.notify("No models available. Use /ollama pull to download one.", "info"); + return; + } + + const lines = ["Local Ollama models:", ""]; + for (const m of models) { + lines.push(` ${formatModelForDisplay(m)}`); + } + + await ctx.ui.custom( + (tui: any, theme: any, _kb: any, done: (r: undefined) => void) => { + const text = new Text(lines.map((l) => theme.fg("fg", l)).join("\n"), 0, 0); + setTimeout(() => done(undefined), 0); + return text; + }, + ); +} + +async function handlePull(modelName: string, ctx: any): Promise { + if (!modelName) { + ctx.ui.notify("Usage: /ollama pull (e.g. /ollama pull llama3.1:8b)", "warning"); + return; + } + + const running = await client.isRunning(); + if (!running) { + ctx.ui.notify("Ollama is not running", "warning"); + return; + } + + ctx.ui.setWidget("ollama-pull", [`Pulling ${modelName}...`]); + + try { + let lastPercent = -1; + await client.pullModel(modelName, (progress) => { + if (progress.total && progress.completed) { + const percent = Math.floor((progress.completed / progress.total) * 100); + if (percent !== lastPercent) { + lastPercent = percent; + const completed = formatModelSize(progress.completed); + const total = formatModelSize(progress.total); + ctx.ui.setWidget("ollama-pull", [ + `Pulling ${modelName}... ${percent}% (${completed} / ${total})`, + ]); + } + } else if (progress.status) { + ctx.ui.setWidget("ollama-pull", [`${modelName}: ${progress.status}`]); + } + }); + + ctx.ui.setWidget("ollama-pull", undefined); + ctx.ui.notify(`${modelName} pulled successfully`, "success"); + } catch (err) { + ctx.ui.setWidget("ollama-pull", undefined); + ctx.ui.notify( + `Failed to pull ${modelName}: ${err instanceof Error ? err.message : String(err)}`, + "error", + ); + } +} + +async function handleRemove(modelName: string, ctx: any): Promise { + if (!modelName) { + ctx.ui.notify("Usage: /ollama remove ", "warning"); + return; + } + + const running = await client.isRunning(); + if (!running) { + ctx.ui.notify("Ollama is not running", "warning"); + return; + } + + const confirmed = await ctx.ui.confirm( + "Delete model", + `Are you sure you want to delete ${modelName}?`, + ); + + if (!confirmed) return; + + try { + await client.deleteModel(modelName); + ctx.ui.notify(`${modelName} deleted`, "success"); + } catch (err) { + ctx.ui.notify( + `Failed to delete ${modelName}: ${err instanceof Error ? err.message : String(err)}`, + "error", + ); + } +} + +async function handlePs(ctx: any): Promise { + const running = await client.isRunning(); + if (!running) { + ctx.ui.notify("Ollama is not running", "warning"); + return; + } + + try { + const ps = await client.getRunningModels(); + if (!ps.models || ps.models.length === 0) { + ctx.ui.notify("No models currently loaded in memory", "info"); + return; + } + + const lines = ["Running models:", ""]; + for (const m of ps.models) { + const vram = m.size_vram > 0 ? formatModelSize(m.size_vram) + " VRAM" : "CPU only"; + const totalSize = formatModelSize(m.size); + const expiresAt = new Date(m.expires_at); + const idleMs = expiresAt.getTime() - Date.now(); + const idleMin = Math.max(0, Math.floor(idleMs / 60000)); + lines.push(` ${m.name} ${totalSize} ${vram} expires in ${idleMin}m`); + } + + await ctx.ui.custom( + (tui: any, theme: any, _kb: any, done: (r: undefined) => void) => { + const text = new Text(lines.map((l) => theme.fg("fg", l)).join("\n"), 0, 0); + setTimeout(() => done(undefined), 0); + return text; + }, + ); + } catch (err) { + ctx.ui.notify( + `Failed to get running models: ${err instanceof Error ? err.message : String(err)}`, + "error", + ); + } +} diff --git a/src/resources/extensions/ollama/ollama-discovery.ts b/src/resources/extensions/ollama/ollama-discovery.ts new file mode 100644 index 000000000..29fb1bc77 --- /dev/null +++ b/src/resources/extensions/ollama/ollama-discovery.ts @@ -0,0 +1,103 @@ +// GSD2 — Ollama model discovery and capability detection + +/** + * Discovers locally available Ollama models and enriches them with + * capability metadata (context window, vision, reasoning) from the + * known model table and /api/show responses. + * + * Returns models in the format expected by pi.registerProvider(). + */ + +import { listModels } from "./ollama-client.js"; +import { + estimateContextFromParams, + formatModelSize, + getModelCapabilities, + humanizeModelName, +} from "./model-capabilities.js"; +import type { OllamaChatOptions, OllamaModelInfo } from "./types.js"; + +export interface DiscoveredOllamaModel { + id: string; + name: string; + reasoning: boolean; + input: ("text" | "image")[]; + cost: { input: number; output: number; cacheRead: number; cacheWrite: number }; + contextWindow: number; + maxTokens: number; + /** Raw size in bytes for display purposes */ + sizeBytes: number; + /** Parameter size string from Ollama (e.g. "7B") */ + parameterSize: string; + /** Ollama-specific inference options for this model */ + ollamaOptions?: OllamaChatOptions; +} + +const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }; + +function enrichModel(info: OllamaModelInfo): DiscoveredOllamaModel { + const caps = getModelCapabilities(info.name); + const parameterSize = info.details?.parameter_size ?? ""; + + // Determine context window: known table > estimate from param size > default + const contextWindow = + caps.contextWindow ?? + (parameterSize ? estimateContextFromParams(parameterSize) : 8192); + + // Determine max tokens: known table > fraction of context > default + const maxTokens = + caps.maxTokens ?? Math.min(Math.floor(contextWindow / 4), 16384); + + // Detect vision from families or known table + const hasVision = + caps.input?.includes("image") ?? + (info.details?.families?.some((f) => f === "clip" || f === "mllama") ?? false); + + // Detect reasoning from known table + const reasoning = caps.reasoning ?? false; + + return { + id: info.name, + name: humanizeModelName(info.name), + reasoning, + input: hasVision ? ["text", "image"] : ["text"], + cost: ZERO_COST, + contextWindow, + maxTokens, + sizeBytes: info.size, + parameterSize, + ollamaOptions: caps.ollamaOptions, + }; +} + +/** + * Discover all locally available Ollama models with enriched capabilities. + */ +export async function discoverModels(): Promise { + const tags = await listModels(); + if (!tags.models || tags.models.length === 0) return []; + + return tags.models.map(enrichModel); +} + +/** + * Format a discovered model for display in model list. + */ +export function formatModelForDisplay(model: DiscoveredOllamaModel): string { + const parts = [model.id]; + + if (model.sizeBytes > 0) { + parts.push(`(${formatModelSize(model.sizeBytes)})`); + } + + const flags: string[] = []; + if (model.reasoning) flags.push("reasoning"); + if (model.input.includes("image")) flags.push("vision"); + + if (flags.length > 0) { + parts.push(`[${flags.join(", ")}]`); + } + + return parts.join(" "); +} + diff --git a/src/resources/extensions/ollama/ollama-tool.ts b/src/resources/extensions/ollama/ollama-tool.ts new file mode 100644 index 000000000..e3a5d7535 --- /dev/null +++ b/src/resources/extensions/ollama/ollama-tool.ts @@ -0,0 +1,287 @@ +// GSD2 — LLM-callable Ollama management tool +/** + * Registers an ollama_manage tool that the LLM can call to interact + * with the local Ollama instance — list models, pull new ones, check status. + */ + +import type { ExtensionAPI } from "@gsd/pi-coding-agent"; +import { Text } from "@gsd/pi-tui"; +import { Type } from "@sinclair/typebox"; +import * as client from "./ollama-client.js"; +import { discoverModels, formatModelForDisplay } from "./ollama-discovery.js"; +import { formatModelSize } from "./model-capabilities.js"; + +interface OllamaToolDetails { + action: string; + model?: string; + modelCount?: number; + durationMs: number; + error?: string; +} + +export function registerOllamaTool(pi: ExtensionAPI): void { + pi.registerTool({ + name: "ollama_manage", + label: "Ollama", + description: + "Manage local Ollama models. List available models, pull new ones, " + + "check Ollama status, or see running models and resource usage. " + + "Use this when you need a specific local model that isn't available yet.", + promptSnippet: "Manage local Ollama models (list, pull, status, ps)", + promptGuidelines: [ + "Use 'list' to see what models are available locally before trying to use one.", + "Use 'pull' to download a model that isn't available yet.", + "Use 'remove' to delete a local model that is no longer needed.", + "Use 'show' to get detailed info about a model (parameters, quantization, families).", + "Use 'status' to check if Ollama is running.", + "Use 'ps' to see which models are loaded in memory and VRAM usage.", + "Common models: llama3.1:8b, qwen2.5-coder:7b, deepseek-r1:8b, codestral:22b", + ], + parameters: Type.Object({ + action: Type.Union( + [ + Type.Literal("list"), + Type.Literal("pull"), + Type.Literal("remove"), + Type.Literal("show"), + Type.Literal("status"), + Type.Literal("ps"), + ], + { description: "Action to perform" }, + ), + model: Type.Optional( + Type.String({ description: "Model name (required for pull)" }), + ), + }), + + async execute(_toolCallId, params, signal, onUpdate, _ctx) { + const startTime = Date.now(); + const { action, model } = params; + + try { + switch (action) { + case "status": { + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running. It needs to be started with 'ollama serve'." }], + details: { action, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + const version = await client.getVersion(); + return { + content: [{ type: "text", text: `Ollama${version ? ` v${version}` : ""} is running at ${client.getOllamaHost()}` }], + details: { action, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + case "list": { + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running." }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "not_running" } as OllamaToolDetails, + }; + } + + const models = await discoverModels(); + if (models.length === 0) { + return { + content: [{ type: "text", text: "No models available. Pull one with action='pull'." }], + details: { action, modelCount: 0, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + const lines = models.map((m) => formatModelForDisplay(m)); + return { + content: [{ type: "text", text: `Available models:\n${lines.join("\n")}` }], + details: { action, modelCount: models.length, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + case "pull": { + if (!model) { + return { + content: [{ type: "text", text: "Error: 'model' parameter is required for pull action." }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "missing_model" } as OllamaToolDetails, + }; + } + + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running." }], + isError: true, + details: { action, model, durationMs: Date.now() - startTime, error: "not_running" } as OllamaToolDetails, + }; + } + + let lastStatus = ""; + await client.pullModel(model, (progress) => { + if (progress.total && progress.completed) { + const pct = Math.floor((progress.completed / progress.total) * 100); + const status = `Pulling ${model}... ${pct}%`; + if (status !== lastStatus) { + lastStatus = status; + onUpdate?.({ content: [{ type: "text", text: status }], details: { action, model, durationMs: Date.now() - startTime } as OllamaToolDetails }); + } + } else if (progress.status && progress.status !== lastStatus) { + lastStatus = progress.status; + onUpdate?.({ content: [{ type: "text", text: `${model}: ${progress.status}` }], details: { action, model, durationMs: Date.now() - startTime } as OllamaToolDetails }); + } + }, signal); + + return { + content: [{ type: "text", text: `Successfully pulled ${model}` }], + details: { action, model, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + case "ps": { + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running." }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "not_running" } as OllamaToolDetails, + }; + } + + const ps = await client.getRunningModels(); + if (!ps.models || ps.models.length === 0) { + return { + content: [{ type: "text", text: "No models currently loaded in memory." }], + details: { action, modelCount: 0, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + const lines = ps.models.map((m) => { + const vram = m.size_vram > 0 ? `${formatModelSize(m.size_vram)} VRAM` : "CPU"; + return `${m.name} — ${formatModelSize(m.size)} total, ${vram}`; + }); + + return { + content: [{ type: "text", text: `Loaded models:\n${lines.join("\n")}` }], + details: { action, modelCount: ps.models.length, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + case "remove": { + if (!model) { + return { + content: [{ type: "text", text: "Error: 'model' parameter is required for remove action." }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "missing_model" } as OllamaToolDetails, + }; + } + + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running." }], + isError: true, + details: { action, model, durationMs: Date.now() - startTime, error: "not_running" } as OllamaToolDetails, + }; + } + + await client.deleteModel(model); + return { + content: [{ type: "text", text: `Successfully removed ${model}` }], + details: { action, model, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + case "show": { + if (!model) { + return { + content: [{ type: "text", text: "Error: 'model' parameter is required for show action." }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "missing_model" } as OllamaToolDetails, + }; + } + + const running = await client.isRunning(); + if (!running) { + return { + content: [{ type: "text", text: "Ollama is not running." }], + isError: true, + details: { action, model, durationMs: Date.now() - startTime, error: "not_running" } as OllamaToolDetails, + }; + } + + const info = await client.showModel(model); + const details = info.details; + const infoLines = [ + `Model: ${model}`, + `Family: ${details.family}`, + `Parameters: ${details.parameter_size}`, + `Quantization: ${details.quantization_level}`, + `Format: ${details.format}`, + ]; + if (details.families?.length) { + infoLines.push(`Families: ${details.families.join(", ")}`); + } + if (info.parameters) { + infoLines.push(`\nModelfile parameters:\n${info.parameters}`); + } + + return { + content: [{ type: "text", text: infoLines.join("\n") }], + details: { action, model, durationMs: Date.now() - startTime } as OllamaToolDetails, + }; + } + + default: + return { + content: [{ type: "text", text: `Unknown action: ${action}` }], + isError: true, + details: { action, durationMs: Date.now() - startTime, error: "unknown_action" } as OllamaToolDetails, + }; + } + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + return { + content: [{ type: "text", text: `Ollama error: ${msg}` }], + isError: true, + details: { action, model, durationMs: Date.now() - startTime, error: msg } as OllamaToolDetails, + }; + } + }, + + renderCall(args, theme) { + let text = theme.fg("toolTitle", theme.bold("ollama ")); + text += theme.fg("accent", args.action); + if (args.model) { + text += theme.fg("dim", ` ${args.model}`); + } + return new Text(text, 0, 0); + }, + + renderResult(result, { isPartial, expanded }, theme) { + const d = result.details as OllamaToolDetails | undefined; + + if (isPartial) return new Text(theme.fg("warning", "Working..."), 0, 0); + if ((result as any).isError || d?.error) { + return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0); + } + + let text = theme.fg("success", d?.action ?? "done"); + if (d?.modelCount !== undefined) { + text += theme.fg("dim", ` (${d.modelCount} models)`); + } + text += theme.fg("dim", ` ${d?.durationMs ?? 0}ms`); + + if (expanded) { + const content = result.content[0]; + if (content?.type === "text") { + const preview = content.text.split("\n").slice(0, 10).join("\n"); + text += "\n\n" + theme.fg("dim", preview); + } + } + + return new Text(text, 0, 0); + }, + }); +} diff --git a/src/resources/extensions/ollama/tests/model-capabilities.test.ts b/src/resources/extensions/ollama/tests/model-capabilities.test.ts new file mode 100644 index 000000000..61af68e9b --- /dev/null +++ b/src/resources/extensions/ollama/tests/model-capabilities.test.ts @@ -0,0 +1,162 @@ +// GSD2 — Tests for Ollama model capability detection +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { + getModelCapabilities, + estimateContextFromParams, + humanizeModelName, + formatModelSize, +} from "../model-capabilities.js"; + +// ─── getModelCapabilities ──────────────────────────────────────────────────── + +describe("getModelCapabilities", () => { + it("returns reasoning for deepseek-r1 models", () => { + const caps = getModelCapabilities("deepseek-r1:8b"); + assert.equal(caps.reasoning, true); + assert.equal(caps.contextWindow, 131072); + }); + + it("returns reasoning for qwq models", () => { + const caps = getModelCapabilities("qwq:32b"); + assert.equal(caps.reasoning, true); + }); + + it("returns vision for llava models", () => { + const caps = getModelCapabilities("llava:7b"); + assert.deepEqual(caps.input, ["text", "image"]); + }); + + it("returns vision for llama3.2-vision models", () => { + const caps = getModelCapabilities("llama3.2-vision:11b"); + assert.deepEqual(caps.input, ["text", "image"]); + }); + + it("returns correct context for llama3.1", () => { + const caps = getModelCapabilities("llama3.1:8b"); + assert.equal(caps.contextWindow, 131072); + }); + + it("returns correct context for llama3 (no .1)", () => { + const caps = getModelCapabilities("llama3:8b"); + assert.equal(caps.contextWindow, 8192); + }); + + it("returns correct context for llama2", () => { + const caps = getModelCapabilities("llama2:7b"); + assert.equal(caps.contextWindow, 4096); + }); + + it("returns correct context for qwen2.5-coder", () => { + const caps = getModelCapabilities("qwen2.5-coder:7b"); + assert.equal(caps.contextWindow, 131072); + assert.equal(caps.maxTokens, 32768); + }); + + it("returns correct context for codestral", () => { + const caps = getModelCapabilities("codestral:22b"); + assert.equal(caps.contextWindow, 262144); + }); + + it("returns correct context for mistral-nemo", () => { + const caps = getModelCapabilities("mistral-nemo:12b"); + assert.equal(caps.contextWindow, 131072); + }); + + it("returns correct context for gemma3", () => { + const caps = getModelCapabilities("gemma3:9b"); + assert.equal(caps.contextWindow, 131072); + }); + + it("returns empty object for unknown models", () => { + const caps = getModelCapabilities("totally-unknown-model:3b"); + assert.deepEqual(caps, {}); + }); + + it("strips tag before matching", () => { + const caps = getModelCapabilities("llama3.1:70b-instruct-q4_0"); + assert.equal(caps.contextWindow, 131072); + }); + + it("matches case-insensitively", () => { + const caps = getModelCapabilities("Llama3.1:8B"); + assert.equal(caps.contextWindow, 131072); + }); +}); + +// ─── estimateContextFromParams ─────────────────────────────────────────────── + +describe("estimateContextFromParams", () => { + it("estimates 8192 for small models", () => { + assert.equal(estimateContextFromParams("1.5B"), 8192); + }); + + it("estimates 16384 for 7B models", () => { + assert.equal(estimateContextFromParams("7B"), 16384); + }); + + it("estimates 32768 for 13B models", () => { + assert.equal(estimateContextFromParams("13B"), 32768); + }); + + it("estimates 65536 for 34B models", () => { + assert.equal(estimateContextFromParams("34B"), 65536); + }); + + it("estimates 131072 for 70B+ models", () => { + assert.equal(estimateContextFromParams("70B"), 131072); + }); + + it("handles decimal sizes", () => { + assert.equal(estimateContextFromParams("7.5B"), 16384); + }); + + it("handles M (millions)", () => { + assert.equal(estimateContextFromParams("500M"), 8192); + }); + + it("returns 8192 for unparseable input", () => { + assert.equal(estimateContextFromParams("unknown"), 8192); + }); + + it("returns 8192 for empty string", () => { + assert.equal(estimateContextFromParams(""), 8192); + }); +}); + +// ─── humanizeModelName ─────────────────────────────────────────────────────── + +describe("humanizeModelName", () => { + it("capitalizes and adds tag", () => { + assert.equal(humanizeModelName("llama3.1:8b"), "Llama 3.1 8B"); + }); + + it("handles latest tag", () => { + assert.equal(humanizeModelName("llama3.1:latest"), "Llama 3.1"); + }); + + it("handles no tag", () => { + assert.equal(humanizeModelName("llama3.1"), "Llama 3.1"); + }); + + it("handles hyphenated names", () => { + const result = humanizeModelName("deepseek-r1:8b"); + assert.ok(result.includes("8B")); + }); +}); + +// ─── formatModelSize ───────────────────────────────────────────────────────── + +describe("formatModelSize", () => { + it("formats GB", () => { + assert.equal(formatModelSize(4_700_000_000), "4.7 GB"); + }); + + it("formats MB", () => { + assert.equal(formatModelSize(500_000_000), "500.0 MB"); + }); + + it("formats KB", () => { + assert.equal(formatModelSize(500_000), "500 KB"); + }); +}); diff --git a/src/resources/extensions/ollama/tests/ollama-chat-provider-stream.test.ts b/src/resources/extensions/ollama/tests/ollama-chat-provider-stream.test.ts new file mode 100644 index 000000000..bc3982c6e --- /dev/null +++ b/src/resources/extensions/ollama/tests/ollama-chat-provider-stream.test.ts @@ -0,0 +1,82 @@ +// GSD2 — Regression test: Ollama streaming must not drop content on done:true chunks (#3576) +// Copyright (c) 2026 Jeremy McSpadden + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +/** + * This test validates the streaming logic pattern used in ollama-chat-provider.ts. + * The bug: content on the terminal done:true chunk was silently dropped because + * the stream loop only emitted content when `!chunk.done`. + * + * The fix: process chunk.message.content regardless of chunk.done, then handle + * done metadata. This test exercises that logic path with a simulated chunk stream. + */ + +interface OllamaChunk { + done: boolean; + done_reason?: string; + message?: { content?: string; tool_calls?: unknown[] }; + prompt_eval_count?: number; + eval_count?: number; +} + +function simulateStreamLoop(chunks: OllamaChunk[]): string { + let output = ""; + + for (const chunk of chunks) { + // This mirrors the fixed logic in ollama-chat-provider.ts + const content = chunk.message?.content ?? ""; + if (content) { + output += content; + } + + if (chunk.done) { + break; + } + } + + return output; +} + +describe("Ollama stream terminal chunk handling", () => { + it("captures content from done:true chunk", () => { + const chunks: OllamaChunk[] = [ + { done: false, message: { content: "Hello " } }, + { done: false, message: { content: "world" } }, + { done: true, done_reason: "stop", message: { content: "!" } }, + ]; + + const result = simulateStreamLoop(chunks); + assert.equal(result, "Hello world!", "trailing content on done chunk must not be dropped"); + }); + + it("works when done chunk has no content", () => { + const chunks: OllamaChunk[] = [ + { done: false, message: { content: "Hello" } }, + { done: true, done_reason: "stop", message: {} }, + ]; + + const result = simulateStreamLoop(chunks); + assert.equal(result, "Hello"); + }); + + it("works when done chunk has empty string content", () => { + const chunks: OllamaChunk[] = [ + { done: false, message: { content: "data" } }, + { done: true, done_reason: "stop", message: { content: "" } }, + ]; + + const result = simulateStreamLoop(chunks); + assert.equal(result, "data"); + }); + + it("handles single done chunk with content", () => { + const chunks: OllamaChunk[] = [ + { done: true, done_reason: "stop", message: { content: "one-shot" } }, + ]; + + const result = simulateStreamLoop(chunks); + assert.equal(result, "one-shot", "single done chunk with content should work"); + }); +}); diff --git a/src/resources/extensions/ollama/tests/ollama-client.test.ts b/src/resources/extensions/ollama/tests/ollama-client.test.ts new file mode 100644 index 000000000..0deae397a --- /dev/null +++ b/src/resources/extensions/ollama/tests/ollama-client.test.ts @@ -0,0 +1,38 @@ +// GSD2 — Tests for Ollama HTTP client +import { describe, it, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { getOllamaHost } from "../ollama-client.js"; + +// ─── getOllamaHost ────────────────────────────────────────────────────────── + +describe("getOllamaHost", () => { + const originalHost = process.env.OLLAMA_HOST; + + afterEach(() => { + if (originalHost === undefined) { + delete process.env.OLLAMA_HOST; + } else { + process.env.OLLAMA_HOST = originalHost; + } + }); + + it("returns default when OLLAMA_HOST is not set", () => { + delete process.env.OLLAMA_HOST; + assert.equal(getOllamaHost(), "http://localhost:11434"); + }); + + it("returns OLLAMA_HOST when set with scheme", () => { + process.env.OLLAMA_HOST = "http://myhost:12345"; + assert.equal(getOllamaHost(), "http://myhost:12345"); + }); + + it("adds http:// when OLLAMA_HOST has no scheme", () => { + process.env.OLLAMA_HOST = "myhost:12345"; + assert.equal(getOllamaHost(), "http://myhost:12345"); + }); + + it("preserves https:// scheme", () => { + process.env.OLLAMA_HOST = "https://secure-ollama.example.com"; + assert.equal(getOllamaHost(), "https://secure-ollama.example.com"); + }); +}); diff --git a/src/resources/extensions/ollama/tests/ollama-discovery.test.ts b/src/resources/extensions/ollama/tests/ollama-discovery.test.ts new file mode 100644 index 000000000..a228bf663 --- /dev/null +++ b/src/resources/extensions/ollama/tests/ollama-discovery.test.ts @@ -0,0 +1 @@ +// GSD2 — Tests for Ollama model discovery and enrichment diff --git a/src/resources/extensions/ollama/thinking-parser.ts b/src/resources/extensions/ollama/thinking-parser.ts new file mode 100644 index 000000000..9c060761c --- /dev/null +++ b/src/resources/extensions/ollama/thinking-parser.ts @@ -0,0 +1,116 @@ +// GSD2 — Ollama Extension: Stateful tag stream parser + +/** + * Extracts ... thinking blocks from a streaming text response. + * Handles the case where tag boundaries span multiple chunks by buffering + * up to 8 characters (length of "") at chunk boundaries. + * + * Used for reasoning models like deepseek-r1 and qwq that embed thinking + * inline in their text output. + */ + +export type ParsedChunk = + | { type: "thinking"; text: string } + | { type: "text"; text: string }; + +const OPEN_TAG = ""; +const CLOSE_TAG = ""; +const MAX_TAG_LEN = Math.max(OPEN_TAG.length, CLOSE_TAG.length); + +export class ThinkingTagParser { + private buffer = ""; + private inThinking = false; + + /** + * Feed a chunk of text and get back parsed segments. + * May return zero or more segments depending on tag boundaries. + */ + push(chunk: string): ParsedChunk[] { + const results: ParsedChunk[] = []; + let input = this.buffer + chunk; + this.buffer = ""; + + while (input.length > 0) { + if (this.inThinking) { + const closeIdx = input.indexOf(CLOSE_TAG); + if (closeIdx !== -1) { + // Found close tag — emit thinking content before it + const thinking = input.slice(0, closeIdx); + if (thinking) results.push({ type: "thinking", text: thinking }); + this.inThinking = false; + input = input.slice(closeIdx + CLOSE_TAG.length); + } else if (this.couldBePartialTag(input, CLOSE_TAG)) { + // Possible partial close tag at end — buffer only the matching tail + const tailLen = this.getPartialTagTailLength(input, CLOSE_TAG); + const safe = input.slice(0, input.length - tailLen); + if (safe) results.push({ type: "thinking", text: safe }); + this.buffer = input.slice(-tailLen); + break; + } else { + // No close tag — emit all as thinking + results.push({ type: "thinking", text: input }); + break; + } + } else { + const openIdx = input.indexOf(OPEN_TAG); + if (openIdx !== -1) { + // Found open tag — emit text before it + const text = input.slice(0, openIdx); + if (text) results.push({ type: "text", text }); + this.inThinking = true; + input = input.slice(openIdx + OPEN_TAG.length); + } else if (this.couldBePartialTag(input, OPEN_TAG)) { + // Possible partial open tag at end — buffer only the matching tail + const tailLen = this.getPartialTagTailLength(input, OPEN_TAG); + const safe = input.slice(0, input.length - tailLen); + if (safe) results.push({ type: "text", text: safe }); + this.buffer = input.slice(-tailLen); + break; + } else { + // No open tag — emit all as text + results.push({ type: "text", text: input }); + break; + } + } + } + + return results; + } + + /** + * Flush any remaining buffered content. Call at end of stream. + */ + flush(): ParsedChunk[] { + if (!this.buffer) return []; + + const result: ParsedChunk = { + type: this.inThinking ? "thinking" : "text", + text: this.buffer, + }; + this.buffer = ""; + return [result]; + } + + /** + * Check if the end of input could be the start of a partial tag. + * Only buffers when the tail of input matches a prefix of the tag. + */ + private couldBePartialTag(input: string, tag: string): boolean { + return this.getPartialTagTailLength(input, tag) > 0; + } + + /** + * Get the length of the tail of input that matches a prefix of the tag. + * Returns 0 if no partial match. + */ + private getPartialTagTailLength(input: string, tag: string): number { + const maxCheck = Math.min(input.length, tag.length - 1); + for (let len = maxCheck; len >= 1; len--) { + const tail = input.slice(-len); + if (tag.startsWith(tail)) { + return len; + } + } + return 0; + } +} diff --git a/src/resources/extensions/ollama/types.ts b/src/resources/extensions/ollama/types.ts new file mode 100644 index 000000000..51e9beb01 --- /dev/null +++ b/src/resources/extensions/ollama/types.ts @@ -0,0 +1,153 @@ +// GSD2 — Ollama API response types + +/** + * Type definitions for the Ollama REST API. + * Reference: https://github.com/ollama/ollama/blob/main/docs/api.md + */ + +// ─── /api/tags ────────────────────────────────────────────────────────────── + +export interface OllamaModelDetails { + parent_model: string; + format: string; + family: string; + families: string[] | null; + parameter_size: string; + quantization_level: string; +} + +export interface OllamaModelInfo { + name: string; + model: string; + modified_at: string; + size: number; + digest: string; + details: OllamaModelDetails; +} + +export interface OllamaTagsResponse { + models: OllamaModelInfo[]; +} + +// ─── /api/show ────────────────────────────────────────────────────────────── + +export interface OllamaShowResponse { + modelfile: string; + parameters: string; + template: string; + details: OllamaModelDetails; + model_info: Record; +} + +// ─── /api/ps ──────────────────────────────────────────────────────────────── + +export interface OllamaRunningModel { + name: string; + model: string; + size: number; + digest: string; + details: OllamaModelDetails; + expires_at: string; + size_vram: number; +} + +export interface OllamaPsResponse { + models: OllamaRunningModel[]; +} + +// ─── /api/pull ────────────────────────────────────────────────────────────── + +export interface OllamaPullProgress { + status: string; + digest?: string; + total?: number; + completed?: number; +} + +// ─── /api/version ─────────────────────────────────────────────────────────── + +export interface OllamaVersionResponse { + version: string; +} + +// ─── /api/chat ────────────────────────────────────────────────────────────── + +/** Per-model Ollama inference options carried via Model.providerOptions. */ +export interface OllamaChatOptions { + /** How long to keep the model loaded after the last request. e.g. "5m", "0" to unload. */ + keep_alive?: string; + /** Number of GPU layers to offload. -1 = all. */ + num_gpu?: number; + /** Override the context window for Ollama requests. Only sent when explicitly set. */ + num_ctx?: number; + /** Sampling: top-k most likely tokens. Default: 40 */ + top_k?: number; + /** Sampling: nucleus sampling threshold. */ + top_p?: number; + /** Sampling: penalize repeating tokens. Default: 1.1 */ + repeat_penalty?: number; + /** Sampling: fixed seed for reproducibility. */ + seed?: number; +} + +export interface OllamaChatMessage { + role: "system" | "user" | "assistant" | "tool"; + content: string; + images?: string[]; + tool_calls?: OllamaToolCall[]; + /** Tool name — required for role: "tool" messages to correlate results with calls. */ + name?: string; +} + +export interface OllamaToolCall { + function: { + name: string; + arguments: Record; + }; +} + +export interface OllamaTool { + type: "function"; + function: { + name: string; + description: string; + parameters: { + type: "object"; + required?: string[]; + properties: Record; + }; + }; +} + +export interface OllamaChatRequest { + model: string; + messages: OllamaChatMessage[]; + stream?: boolean; + tools?: OllamaTool[]; + options?: { + num_ctx?: number; + num_predict?: number; + temperature?: number; + top_p?: number; + top_k?: number; + repeat_penalty?: number; + seed?: number; + stop?: string[]; + num_gpu?: number; + }; + keep_alive?: string; +} + +export interface OllamaChatResponse { + model: string; + created_at: string; + message: OllamaChatMessage; + done: boolean; + done_reason?: string; + total_duration?: number; + load_duration?: number; + prompt_eval_count?: number; + prompt_eval_duration?: number; + eval_count?: number; + eval_duration?: number; +} diff --git a/src/resources/extensions/remote-questions/manager.ts b/src/resources/extensions/remote-questions/manager.ts index a1e1d10f7..338e354f1 100644 --- a/src/resources/extensions/remote-questions/manager.ts +++ b/src/resources/extensions/remote-questions/manager.ts @@ -24,6 +24,15 @@ interface QuestionInput { allowMultiple?: boolean; } +/** + * Check whether a remote channel is configured without triggering any + * side effects (no HTTP requests, no prompt records). Used by the race + * logic to decide routing before committing to a remote dispatch. + */ +export function isRemoteConfigured(): boolean { + return resolveRemoteConfig() !== null; +} + export async function tryRemoteQuestions( questions: QuestionInput[], signal?: AbortSignal, diff --git a/src/resources/extensions/search-the-web/extension-manifest.json b/src/resources/extensions/search-the-web/extension-manifest.json index 582c341d8..b17107d76 100644 --- a/src/resources/extensions/search-the-web/extension-manifest.json +++ b/src/resources/extensions/search-the-web/extension-manifest.json @@ -8,6 +8,6 @@ "provides": { "tools": ["search-the-web", "fetch_page", "search_and_read", "web_search"], "commands": ["search-provider"], - "hooks": ["model_select", "before_provider_request"] + "hooks": ["session_start", "model_select", "before_provider_request"] } } diff --git a/src/resources/extensions/search-the-web/url-utils.ts b/src/resources/extensions/search-the-web/url-utils.ts index 24b3caedd..fca98e173 100644 --- a/src/resources/extensions/search-the-web/url-utils.ts +++ b/src/resources/extensions/search-the-web/url-utils.ts @@ -21,11 +21,30 @@ const PRIVATE_IP_PATTERNS = [ /^fe80:/i, ]; +/** + * Hostnames exempted from SSRF blocking. Set via setFetchAllowedUrls() + * from global settings.json or GSD_FETCH_ALLOWED_URLS env var. + */ +let fetchAllowedHostnames: Set = new Set(); + +/** + * Replace the fetch URL allowlist (hostnames exempted from SSRF checks). + */ +export function setFetchAllowedUrls(hostnames: string[]): void { + fetchAllowedHostnames = new Set(hostnames.map((h) => h.toLowerCase())); +} + +/** Get the currently active fetch URL allowlist. */ +export function getFetchAllowedUrls(): readonly string[] { + return [...fetchAllowedHostnames]; +} + export function isBlockedUrl(url: string): boolean { try { const parsed = new URL(url); if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return true; const hostname = parsed.hostname.toLowerCase(); + if (fetchAllowedHostnames.has(hostname)) return false; if (BLOCKED_HOSTNAMES.has(hostname)) return true; for (const pattern of PRIVATE_IP_PATTERNS) { if (pattern.test(hostname)) return true; diff --git a/src/resources/extensions/shared/interview-ui.ts b/src/resources/extensions/shared/interview-ui.ts index 823568330..66771bc84 100644 --- a/src/resources/extensions/shared/interview-ui.ts +++ b/src/resources/extensions/shared/interview-ui.ts @@ -80,6 +80,12 @@ export interface InterviewRoundOptions { * Label for the Esc-confirm overlay header. Defaults to "End interview?". */ exitHeadline?: string; + /** + * Optional AbortSignal to cancel the interview externally (e.g. when racing + * against a remote question channel). When aborted, the TUI closes and the + * promise resolves with an empty answers object. + */ + signal?: AbortSignal; /** * Text for the "exit" hint shown in the review screen footer and exit confirm overlay. * Defaults to "end interview". @@ -105,7 +111,7 @@ export interface WrapUpOptions { // ─── Constants ──────────────────────────────────────────────────────────────── const OTHER_OPTION_LABEL = "None of the above"; -const OTHER_OPTION_DESCRIPTION = "Press TAB to add optional notes."; +const OTHER_OPTION_DESCRIPTION = "Select to type your own answer."; // ─── Wrap-up screen ─────────────────────────────────────────────────────────── @@ -207,6 +213,13 @@ export async function showInterviewRound( let exitCursor = 0; // 0 = keep going (default), 1 = end interview let cachedLines: string[] | undefined; + // External cancellation (e.g. remote channel won the race) + if (opts.signal) { + const onAbort = () => done({ endInterview: false, answers: {} }); + if (opts.signal.aborted) { onAbort(); } + else { opts.signal.addEventListener("abort", onAbort, { once: true }); } + } + // Editor is created once; editorTheme comes from the design system const editorRef = { current: null as Editor | null }; @@ -295,6 +308,19 @@ export async function showInterviewRound( states[currentIdx].committedIndex = states[currentIdx].cursorIndex; } + // Auto-open the notes field when "None of the above" is selected + // so the user can immediately provide a free-text explanation + // instead of being trapped in a re-asking loop (bug #2715). + // Only auto-open if the user hasn't already provided notes — + // otherwise Enter from notes mode loops back here endlessly. + if (!isMultiSelect(currentIdx) && states[currentIdx].cursorIndex === noneOrDoneIdx(currentIdx) && !states[currentIdx].notes && !states[currentIdx].notesVisible) { + states[currentIdx].notesVisible = true; + focusNotes = true; + loadStateToEditor(); + refresh(); + return; + } + if (isMultiQuestion && currentIdx < questions.length - 1) { let next = currentIdx + 1; for (let i = 0; i < questions.length; i++) { diff --git a/src/resources/extensions/shared/tests/ask-user-freetext.test.ts b/src/resources/extensions/shared/tests/ask-user-freetext.test.ts new file mode 100644 index 000000000..41e4d8292 --- /dev/null +++ b/src/resources/extensions/shared/tests/ask-user-freetext.test.ts @@ -0,0 +1,161 @@ +/** + * Tests for ask-user-questions free-text input behavior. + * + * Bug #2715: The ask-user-questions UI lacks free-text input and can trap + * users in a loop when the agent needs an explanation rather than a fixed + * choice. + * + * These tests exercise the RPC fallback path (ctx.ui.select) in + * ask-user-questions.ts to ensure that selecting "None of the above" + * triggers a follow-up free-text input prompt via ctx.ui.input(). + */ + +import { describe, it, beforeEach } from "node:test"; +import assert from "node:assert/strict"; + +// The ask-user-questions extension registers a tool via pi.registerTool(). +// We capture that registration and call execute() directly with a mock context. +import AskUserQuestions from "../../ask-user-questions.js"; +import { resetAskUserQuestionsCache } from "../../ask-user-questions.js"; + +interface CapturedTool { + name: string; + execute: (...args: any[]) => Promise; +} + +function captureTool(): CapturedTool { + let captured: CapturedTool | null = null; + const fakePi = { + registerTool(tool: any) { + captured = { name: tool.name, execute: tool.execute }; + }, + }; + AskUserQuestions(fakePi as any); + if (!captured) throw new Error("No tool registered"); + return captured; +} + +function makeQuestion(id: string, options: string[]) { + return { + id, + header: id, + question: `Pick for ${id}`, + options: options.map((label) => ({ label, description: `Desc for ${label}` })), + }; +} + +function makeMockCtx(opts: { + selectReturns: (string | string[] | undefined)[]; + inputReturns?: (string | undefined)[]; +}) { + let selectCallIdx = 0; + let inputCallIdx = 0; + const selectCalls: { title: string; options: string[] }[] = []; + const inputCalls: { title: string; placeholder?: string }[] = []; + + return { + ctx: { + hasUI: true, + ui: { + custom: () => undefined, // force RPC fallback + select: async (title: string, options: string[], selectOpts?: any) => { + selectCalls.push({ title, options }); + return opts.selectReturns[selectCallIdx++]; + }, + input: async (title: string, placeholder?: string) => { + inputCalls.push({ title, placeholder }); + return (opts.inputReturns ?? [])[inputCallIdx++]; + }, + }, + }, + selectCalls, + inputCalls, + }; +} + +describe("ask-user-questions RPC fallback free-text", () => { + beforeEach(() => { + resetAskUserQuestionsCache(); + }); + + it("prompts for free-text input when user selects 'None of the above'", async () => { + const tool = captureTool(); + const { ctx, selectCalls, inputCalls } = makeMockCtx({ + selectReturns: ["None of the above"], + inputReturns: ["I need to explain my reasoning"], + }); + + const params = { + questions: [makeQuestion("q1", ["Option A", "Option B"])], + }; + + const result = await tool.execute("call-1", params, undefined, undefined, ctx); + + // The select should have been called with "None of the above" appended + assert.equal(selectCalls.length, 1); + assert.ok( + selectCalls[0].options.includes("None of the above"), + "select options should include 'None of the above'", + ); + + // A follow-up input() call should have been made to collect free text + assert.equal(inputCalls.length, 1, "should call ctx.ui.input() for free-text after 'None of the above'"); + + // The result should include the user's free-text note + const text = result.content[0]?.text; + assert.ok(text, "result should have text content"); + const parsed = JSON.parse(text); + assert.ok( + parsed.answers.q1, + "answer for q1 should exist", + ); + const q1Answers = parsed.answers.q1.answers; + assert.ok( + q1Answers.some((a: string) => a.includes("I need to explain my reasoning")), + "answer should include the free-text explanation", + ); + }); + + it("does NOT prompt for free-text when user selects a normal option", async () => { + const tool = captureTool(); + const { ctx, inputCalls } = makeMockCtx({ + selectReturns: ["Option A"], + }); + + const params = { + questions: [makeQuestion("q1", ["Option A", "Option B"])], + }; + + const result = await tool.execute("call-2", params, undefined, undefined, ctx); + + // No input() call should have been made + assert.equal(inputCalls.length, 0, "should NOT call ctx.ui.input() for a normal option"); + + const text = result.content[0]?.text; + const parsed = JSON.parse(text); + assert.deepStrictEqual(parsed.answers.q1.answers, ["Option A"]); + }); + + it("handles cancelled free-text input gracefully", async () => { + const tool = captureTool(); + const { ctx, inputCalls } = makeMockCtx({ + selectReturns: ["None of the above"], + inputReturns: [undefined], // user cancelled the input + }); + + const params = { + questions: [makeQuestion("q1", ["Option A", "Option B"])], + }; + + const result = await tool.execute("call-3", params, undefined, undefined, ctx); + + // Input should still have been called + assert.equal(inputCalls.length, 1, "should call ctx.ui.input() even if user cancels"); + + // Result should still contain "None of the above" without a note + const text = result.content[0]?.text; + assert.ok(text, "result should have text content"); + const parsed = JSON.parse(text); + assert.deepStrictEqual(parsed.answers.q1.answers, ["None of the above"]); + }); +}); diff --git a/src/resources/extensions/shared/tests/interview-notes-loop.test.ts b/src/resources/extensions/shared/tests/interview-notes-loop.test.ts new file mode 100644 index 000000000..5e0a5704b --- /dev/null +++ b/src/resources/extensions/shared/tests/interview-notes-loop.test.ts @@ -0,0 +1,142 @@ +// GSD2 — Regression test for interview-ui "None of the above" notes loop +// Copyright (c) 2026 Jeremy McSpadden + +/** + * Regression test for bug #3502: + * + * Selecting "None of the above" opens the notes field, but pressing Enter + * after typing a note called goNextOrSubmit() which saw the cursor still + * on the "None of the above" slot and re-opened notes — trapping the user + * in an infinite loop. + * + * The fix adds a `!states[currentIdx].notes` guard so auto-open only fires + * when notes are still empty. + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { showInterviewRound, type Question, type RoundResult } from "../interview-ui.js"; + +// Raw terminal sequences that matchesKey() recognises +const ENTER = "\r"; +const DOWN = "\x1b[B"; +const TAB = "\t"; + +/** + * Drive showInterviewRound with a scripted sequence of key inputs. + * We mock ctx.ui.custom() to capture the widget, feed it inputs, and + * resolve when done() is called. + */ +function runWithInputs( + questions: Question[], + inputs: string[], +): Promise { + return new Promise((resolve, reject) => { + const timeout = setTimeout(() => reject(new Error("Timed out — likely stuck in infinite loop")), 3000); + + const mockCtx = { + ui: { + custom: (factory: any) => { + const mockTui = { + requestRender: () => {}, + }; + const mockTheme = { + // Minimal theme stubs — render output is not asserted + fg: (_c: string, t: string) => t, + bold: (t: string) => t, + dim: (t: string) => t, + italic: (t: string) => t, + strikethrough: (t: string) => t, + accent: (t: string) => t, + success: (t: string) => t, + warning: (t: string) => t, + error: (t: string) => t, + info: (t: string) => t, + muted: (t: string) => t, + dimmed: (t: string) => t, + }; + const mockKb = {}; + + const widget = factory(mockTui, mockTheme, mockKb, (result: RoundResult) => { + clearTimeout(timeout); + resolve(result); + }); + + // Feed each input sequentially + for (const input of inputs) { + widget.handleInput(input); + } + }, + }, + }; + + showInterviewRound(questions, {}, mockCtx as any).catch(reject); + }); +} + +describe("interview-ui notes loop regression (#3502)", () => { + const questions: Question[] = [ + { + id: "q1", + header: "Project Type", + question: "What type of project?", + options: [ + { label: "Web App", description: "Frontend or full-stack" }, + { label: "CLI Tool", description: "Command-line utility" }, + ], + }, + ]; + + it("does not loop when Enter is pressed after typing a note on 'None of the above'", async () => { + // With 2 options, "None of the above" is index 2 (0-based) + // Cursor starts at 0, so press Down twice to reach it + const result = await runWithInputs(questions, [ + DOWN, // cursor → index 1 (CLI Tool) + DOWN, // cursor → index 2 (None of the above) + ENTER, // commit → auto-opens notes field + "u", "n", "s", "u", "r", "e", // type "unsure" + ENTER, // should advance to review, NOT reopen notes + ENTER, // submit from review screen + ]); + + // If we get here, the loop did not occur (timeout would have fired) + assert.ok(result, "should return a result"); + assert.equal(result.endInterview, false); + + const answer = result.answers.q1; + assert.ok(answer, "answer for q1 should exist"); + assert.equal(answer.notes, "unsure", "notes should contain typed text"); + assert.equal(answer.selected, "None of the above"); + }); + + it("Enter on empty notes advances instead of re-opening (notesVisible guard)", async () => { + // Press Down twice to "None of the above", Enter to select + // Then immediately Enter again (empty notes) — notesVisible is already + // true from auto-open, so the guard prevents re-opening and Enter + // advances to review. The notes remain empty. + const result = await runWithInputs(questions, [ + DOWN, // cursor → 1 + DOWN, // cursor → 2 (None of the above) + ENTER, // commit → auto-opens notes (notesVisible = true) + ENTER, // empty notes → notesVisible prevents re-open → advances to review + ENTER, // submit from review screen + ]); + + assert.ok(result, "should return a result"); + const answer = result.answers.q1; + assert.ok(answer, "answer for q1 should exist"); + assert.equal(answer.notes, ""); + }); + + it("normal option selection is unaffected", async () => { + const result = await runWithInputs(questions, [ + ENTER, // select first option (Web App) and advance to review + ENTER, // submit from review screen + ]); + + assert.ok(result, "should return a result"); + const answer = result.answers.q1; + assert.ok(answer, "answer for q1 should exist"); + assert.equal(answer.selected, "Web App"); + }); +}); diff --git a/src/resources/extensions/slash-commands/audit.ts b/src/resources/extensions/slash-commands/audit.ts index b5f3bf85c..fe7d3f046 100644 --- a/src/resources/extensions/slash-commands/audit.ts +++ b/src/resources/extensions/slash-commands/audit.ts @@ -1,4 +1,5 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent"; +import { mkdirSync } from "node:fs"; export default function auditCommand(pi: ExtensionAPI) { pi.registerCommand("audit", { @@ -39,7 +40,7 @@ export default function auditCommand(pi: ExtensionAPI) { // ── Step 3: Ensure the output directory exists ─────────────────────── - await pi.exec("mkdir", ["-p", ".gsd/audits"]); + mkdirSync(".gsd/audits", { recursive: true }); // ── Step 4: Send the audit prompt to the agent ─────────────────────── diff --git a/src/resources/extensions/subagent/agents.ts b/src/resources/extensions/subagent/agents.ts index 43e124fa3..6f14c3bcf 100644 --- a/src/resources/extensions/subagent/agents.ts +++ b/src/resources/extensions/subagent/agents.ts @@ -25,6 +25,33 @@ export interface AgentDiscoveryResult { projectAgentsDir: string | null; } +interface AgentFrontmatter extends Record { + name?: string; + description?: string; + tools?: string | string[]; + model?: string; +} + +function parseAgentTools(value: string | string[] | undefined): string[] | undefined { + if (typeof value === "string") { + const tools = value + .split(",") + .map((tool) => tool.trim()) + .filter(Boolean); + return tools.length > 0 ? tools : undefined; + } + + if (Array.isArray(value)) { + const tools = value + .flatMap((tool) => typeof tool === "string" ? tool.split(",") : []) + .map((tool) => tool.trim()) + .filter(Boolean); + return tools.length > 0 ? tools : undefined; + } + + return undefined; +} + function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] { const agents: AgentConfig[] = []; @@ -51,16 +78,13 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig continue; } - const { frontmatter, body } = parseFrontmatter>(content); + const { frontmatter, body } = parseFrontmatter(content); - if (!frontmatter.name || !frontmatter.description) { + if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") { continue; } - const tools = frontmatter.tools - ?.split(",") - .map((t: string) => t.trim()) - .filter(Boolean); + const tools = parseAgentTools(frontmatter.tools); agents.push({ name: frontmatter.name, diff --git a/src/resources/extensions/subagent/isolation.ts b/src/resources/extensions/subagent/isolation.ts index a326f55d3..e862e65ff 100644 --- a/src/resources/extensions/subagent/isolation.ts +++ b/src/resources/extensions/subagent/isolation.ts @@ -53,8 +53,10 @@ interface Baseline { // Directory helpers // ============================================================================ -function encodeCwd(cwd: string): string { - return cwd.replace(/\//g, "--"); +export function encodeCwd(cwd: string): string { + // Encode the entire cwd so Windows drive letters, separators, and UNC + // prefixes cannot leak into the isolation path. + return Buffer.from(cwd, "utf8").toString("base64url"); } const gsdHome = process.env.GSD_HOME || path.join(os.homedir(), ".gsd"); @@ -500,4 +502,3 @@ export function readIsolationMode(): IsolationMode { return "none"; } } - diff --git a/src/resources/skills/btw/SKILL.md b/src/resources/skills/btw/SKILL.md new file mode 100644 index 000000000..c3a103f8f --- /dev/null +++ b/src/resources/skills/btw/SKILL.md @@ -0,0 +1,42 @@ +--- +name: btw +description: Ask a quick side question about your current work without derailing the main task. Answers from existing conversation context only — no tool calls, no file reads, single concise response. Use when you need a fast answer from what is already in this session. +--- + + +Answer a quick side question using only what is already present in the current conversation context. Do not read files, run commands, search, or use any tools. Give a single, concise response and return focus to the main work. + + + +**This is a side question, not a task.** + +- Answer only from information already in the conversation (files read, decisions made, code seen, context established) +- Do NOT use any tools — no Read, no Bash, no Grep, no Search +- If the answer requires reading something new, say so briefly and suggest the user ask as a normal prompt instead +- Keep the response short and direct — one to a few sentences unless the question genuinely needs more +- Do not summarize the main work, ask follow-up questions, or offer to do anything else +- After answering, stop — do not prompt for next steps + + + +Parse the argument after `/btw` as the question. Answer it directly from context. + +If no argument is provided, ask: "What did you want to know?" + +If the question cannot be answered from current context (requires reading a file, running a command, or information not yet in the session), respond with: +"I'd need to [read X / run Y / look up Z] to answer that — ask it as a normal prompt when you're ready." + + + +**Good uses of /btw:** +- `/btw what was the name of that config file again?` → answers from files already read in session +- `/btw which branch are we on?` → answers from git context already established +- `/btw did we already handle the null case in that function?` → answers from code already reviewed +- `/btw what model does this use?` → answers from code or config already in context + +**Not a good fit for /btw (suggest normal prompt):** +- Questions requiring reading a file not yet seen +- Questions requiring running a command +- Questions needing a multi-step answer or follow-up +- Starting a new task or changing direction + diff --git a/src/resources/skills/create-gsd-extension/SKILL.md b/src/resources/skills/create-gsd-extension/SKILL.md index e233c0229..28c51efca 100644 --- a/src/resources/skills/create-gsd-extension/SKILL.md +++ b/src/resources/skills/create-gsd-extension/SKILL.md @@ -7,9 +7,11 @@ description: Create, debug, and iterate on GSD extensions (TypeScript modules th **Extensions are TypeScript modules** that hook into GSD's runtime (built on pi). They export a default function receiving `ExtensionAPI` and use it to subscribe to events, register tools/commands/shortcuts, and interact with the session. -**GSD extension paths:** -- Global extensions: `~/.gsd/agent/extensions/*.ts` or `~/.gsd/agent/extensions/*/index.ts` -- Project-local extensions: `.gsd/extensions/*.ts` or `.gsd/extensions/*/index.ts` +**GSD extension paths (community/user-installed extensions):** +- Global: `~/.pi/agent/extensions/*.ts` or `~/.pi/agent/extensions/*/index.ts` +- Project-local: `.gsd/extensions/*.ts` or `.gsd/extensions/*/index.ts` + +Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package. Community extensions placed there are silently ignored by the loader. **The three primitives:** 1. **Events** — Listen and react (`pi.on("event", handler)`). Can block tool calls, modify messages, inject context. diff --git a/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md b/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md index 75f73f2c8..11b300677 100644 --- a/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md +++ b/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md @@ -26,11 +26,12 @@ Non-negotiable rules and common gotchas when building GSD extensions. -**GSD extension paths:** -- Global: `~/.gsd/agent/extensions/*.ts` -- Global (subdir): `~/.gsd/agent/extensions/*/index.ts` +**GSD extension paths (community/user-installed extensions):** +- Global: `~/.pi/agent/extensions/*.ts` +- Global (subdir): `~/.pi/agent/extensions/*/index.ts` - Project-local: `.gsd/extensions/*.ts` - Project-local (subdir): `.gsd/extensions/*/index.ts` -The upstream pi docs reference `~/.pi` paths — GSD uses `~/.gsd` everywhere instead. +Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package. +Community extensions placed there are silently ignored by the loader. diff --git a/src/resources/skills/create-gsd-extension/workflows/add-capability.md b/src/resources/skills/create-gsd-extension/workflows/add-capability.md index a069e4570..eac2e4ea1 100644 --- a/src/resources/skills/create-gsd-extension/workflows/add-capability.md +++ b/src/resources/skills/create-gsd-extension/workflows/add-capability.md @@ -14,7 +14,7 @@ Read the reference file for the specific capability being added: ## Step 1: Identify the Extension Locate the existing extension file. Check: -- `~/.gsd/agent/extensions/` (global) +- `~/.pi/agent/extensions/` (global community extensions) - `.gsd/extensions/` (project-local) Read the current extension code to understand its structure. @@ -28,7 +28,7 @@ If the extension needs new imports, add them at the top of the file. ## Step 3: Handle Structural Changes **Single file → Directory**: If the extension is outgrowing a single file: -1. Create `~/.gsd/agent/extensions/my-extension/` +1. Create `~/.pi/agent/extensions/my-extension/` 2. Move the file to `index.ts` 3. Extract helpers to separate files diff --git a/src/resources/skills/create-gsd-extension/workflows/create-extension.md b/src/resources/skills/create-gsd-extension/workflows/create-extension.md index 817efa13b..a91a39ae6 100644 --- a/src/resources/skills/create-gsd-extension/workflows/create-extension.md +++ b/src/resources/skills/create-gsd-extension/workflows/create-extension.md @@ -12,7 +12,7 @@ ## Step 1: Determine Scope and Placement Ask the user: -- **Global** (`~/.gsd/agent/extensions/`) — Available in all GSD sessions +- **Global** (`~/.pi/agent/extensions/`) — Available in all GSD sessions - **Project-local** (`.gsd/extensions/`) — Available only in this project ## Step 2: Determine Extension Capabilities @@ -36,12 +36,12 @@ Identify what the extension needs from the user's description: **Single file** — for small extensions (1-2 tools/commands, simple hooks): ``` -~/.gsd/agent/extensions/my-extension.ts +~/.pi/agent/extensions/my-extension.ts ``` **Directory with index.ts** — for multi-file extensions: ``` -~/.gsd/agent/extensions/my-extension/ +~/.pi/agent/extensions/my-extension/ ├── index.ts ├── tools.ts └── utils.ts @@ -49,7 +49,7 @@ Identify what the extension needs from the user's description: **Package with dependencies** — when npm packages are needed: ``` -~/.gsd/agent/extensions/my-extension/ +~/.pi/agent/extensions/my-extension/ ├── package.json ├── src/index.ts └── node_modules/ diff --git a/src/resources/skills/create-gsd-extension/workflows/debug-extension.md b/src/resources/skills/create-gsd-extension/workflows/debug-extension.md index 58b1e982e..5a8ac2295 100644 --- a/src/resources/skills/create-gsd-extension/workflows/debug-extension.md +++ b/src/resources/skills/create-gsd-extension/workflows/debug-extension.md @@ -32,12 +32,14 @@ gsd -e ./path/to/extension.ts ## Step 3: Verify File Location -Extensions must be in auto-discovery paths: -- `~/.gsd/agent/extensions/*.ts` -- `~/.gsd/agent/extensions/*/index.ts` +Community extensions must be in auto-discovery paths: +- `~/.pi/agent/extensions/*.ts` +- `~/.pi/agent/extensions/*/index.ts` - `.gsd/extensions/*.ts` - `.gsd/extensions/*/index.ts` +Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package. + The file must `export default function(pi: ExtensionAPI) { ... }`. ## Step 4: Check for Common Mistakes diff --git a/src/security-overrides.ts b/src/security-overrides.ts new file mode 100644 index 000000000..9a0609d6c --- /dev/null +++ b/src/security-overrides.ts @@ -0,0 +1,42 @@ +/** + * Apply user-configured security overrides from global settings.json and env vars. + * + * Both overrides are global-only (not project-level) because the threat model is + * malicious project-level config in cloned repos. Global settings and env vars + * represent the user's own authority on their machine. + * + * Precedence: env var > settings.json > built-in defaults + */ + +import { type SettingsManager, setAllowedCommandPrefixes } from '@gsd/pi-coding-agent' +import { setFetchAllowedUrls } from './resources/extensions/search-the-web/url-utils.js' + +export function applySecurityOverrides(settingsManager: SettingsManager): void { + // --- Command prefix allowlist --- + const envPrefixes = process.env.GSD_ALLOWED_COMMAND_PREFIXES + if (envPrefixes) { + const prefixes = envPrefixes.split(',').map(s => s.trim()).filter(Boolean) + if (prefixes.length > 0) { + setAllowedCommandPrefixes(prefixes) + } + } else { + const settingsPrefixes = settingsManager.getAllowedCommandPrefixes() + if (settingsPrefixes && settingsPrefixes.length > 0) { + setAllowedCommandPrefixes(settingsPrefixes) + } + } + + // --- Fetch URL allowlist (SSRF exemptions) --- + const envUrls = process.env.GSD_FETCH_ALLOWED_URLS + if (envUrls) { + const urls = envUrls.split(',').map(s => s.trim()).filter(Boolean) + if (urls.length > 0) { + setFetchAllowedUrls(urls) + } + } else { + const settingsUrls = settingsManager.getFetchAllowedUrls() + if (settingsUrls && settingsUrls.length > 0) { + setFetchAllowedUrls(settingsUrls) + } + } +} diff --git a/src/startup-model-validation.ts b/src/startup-model-validation.ts new file mode 100644 index 000000000..1a4141f00 --- /dev/null +++ b/src/startup-model-validation.ts @@ -0,0 +1,78 @@ +/** + * Startup model validation — extracted from cli.ts so it can be called + * AFTER extensions register their models in the ModelRegistry. + * + * Before this extraction (bug #2626), the validation ran before + * createAgentSession(), meaning extension-provided models (e.g. + * claude-code/claude-sonnet-4-6) were not yet in the registry. + * configuredExists was always false for extension models, causing the + * user's valid choice to be silently overwritten with a built-in fallback. + */ + +import { getPiDefaultModelAndProvider } from './pi-migration.js' + +interface MinimalModel { + provider: string + id: string +} + +interface MinimalModelRegistry { + getAll(): MinimalModel[] + getAvailable(): MinimalModel[] +} + +type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' + +interface MinimalSettingsManager { + getDefaultProvider(): string | undefined + getDefaultModel(): string | undefined + getDefaultThinkingLevel(): ThinkingLevel | undefined + setDefaultModelAndProvider(provider: string, modelId: string): void + setDefaultThinkingLevel(level: ThinkingLevel): void +} + +/** + * Validate the configured default model against the registry. + * + * If the configured model exists in the registry, this is a no-op — the + * user's choice is preserved. If it does not exist (stale settings from a + * prior install, or genuinely removed model), a fallback is selected and + * written to settings. + * + * IMPORTANT: Call this AFTER createAgentSession() so that extension- + * provided models have been registered in the ModelRegistry. + */ +export function validateConfiguredModel( + modelRegistry: MinimalModelRegistry, + settingsManager: MinimalSettingsManager, +): void { + const configuredProvider = settingsManager.getDefaultProvider() + const configuredModel = settingsManager.getDefaultModel() + const allModels = modelRegistry.getAll() + const availableModels = modelRegistry.getAvailable() + const configuredExists = configuredProvider && configuredModel && + allModels.some((m) => m.provider === configuredProvider && m.id === configuredModel) + + if (!configuredModel || !configuredExists) { + // Model not configured at all, or removed from registry — pick a fallback. + // Only fires when the model is genuinely unknown (not just temporarily unavailable). + const piDefault = getPiDefaultModelAndProvider() + const preferred = + (piDefault + ? availableModels.find((m) => m.provider === piDefault.provider && m.id === piDefault.model) + : undefined) || + availableModels.find((m) => m.provider === 'openai' && m.id === 'gpt-5.4') || + availableModels.find((m) => m.provider === 'openai') || + availableModels.find((m) => m.provider === 'anthropic' && m.id === 'claude-opus-4-6') || + availableModels.find((m) => m.provider === 'anthropic' && m.id.includes('opus')) || + availableModels.find((m) => m.provider === 'anthropic') || + availableModels[0] + if (preferred) { + settingsManager.setDefaultModelAndProvider(preferred.provider, preferred.id) + } + } + + if (settingsManager.getDefaultThinkingLevel() !== 'off' && !configuredExists) { + settingsManager.setDefaultThinkingLevel('off') + } +} diff --git a/src/tests/auto-mode-piped.test.ts b/src/tests/auto-mode-piped.test.ts new file mode 100644 index 000000000..005dddadd --- /dev/null +++ b/src/tests/auto-mode-piped.test.ts @@ -0,0 +1,106 @@ +/** + * Tests for `gsd auto` routing — verifies that `auto` is recognized as a + * subcommand alias for `headless auto` so it doesn't fall through to the + * interactive TUI, which hangs when stdin/stdout are piped. + * + * Regression test for #2732. + */ + +import test from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' + +const projectRoot = join(fileURLToPath(import.meta.url), '..', '..', '..') + +// --------------------------------------------------------------------------- +// Source-level verification: cli.ts must handle 'auto' before TUI +// --------------------------------------------------------------------------- + +/** + * Read cli.ts and verify the 'auto' subcommand is routed before the + * interactive TUI code path. This is the definitive test — if cli.ts doesn't + * handle 'auto', piped invocations will hang (#2732). + */ +function cliSourceHandlesAutoBeforeTUI(): boolean { + const cliSource = readFileSync(join(projectRoot, 'src', 'cli.ts'), 'utf-8') + + // Find the position of the 'auto' subcommand handler + // It should appear as: messages[0] === 'auto' + const autoHandlerMatch = cliSource.match( + /messages\[0\]\s*===\s*['"]auto['"]/, + ) + if (!autoHandlerMatch) return false + + // Find the position of the InteractiveMode TUI entry + const tuiMatch = cliSource.match(/new\s+InteractiveMode\s*\(/) + if (!tuiMatch) return false + + // The auto handler must appear BEFORE the TUI in the source + const autoPos = cliSource.indexOf(autoHandlerMatch[0]) + const tuiPos = cliSource.indexOf(tuiMatch[0]) + + return autoPos < tuiPos +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Core regression test: `gsd auto` must be handled before TUI (#2732) +// ═══════════════════════════════════════════════════════════════════════════ + +test('cli.ts handles `auto` subcommand before interactive TUI (#2732)', () => { + assert.ok( + cliSourceHandlesAutoBeforeTUI(), + 'cli.ts must route messages[0] === "auto" to a handler BEFORE ' + + 'reaching `new InteractiveMode()`. Without this, `gsd auto` with ' + + 'piped stdin/stdout falls through to the TUI and hangs.', + ) +}) + +// ═══════════════════════════════════════════════════════════════════════════ +// Verify the auto handler routes to headless (not a stub/no-op) +// ═══════════════════════════════════════════════════════════════════════════ + +test('cli.ts routes `auto` to headless runner', () => { + const cliSource = readFileSync(join(projectRoot, 'src', 'cli.ts'), 'utf-8') + + // The auto handler block should import or reference headless + // Look for the auto block and check it contains runHeadless or headless + const autoBlockRegex = /messages\[0\]\s*===\s*['"]auto['"][\s\S]*?runHeadless/ + assert.ok( + autoBlockRegex.test(cliSource), + '`auto` subcommand handler must invoke runHeadless to delegate to headless mode', + ) +}) + +// ═══════════════════════════════════════════════════════════════════════════ +// Verify piped-mode hint in error message when auto mode is not available +// ═══════════════════════════════════════════════════════════════════════════ + +test('TTY error message mentions `gsd auto` as a non-interactive alternative', () => { + const cliSource = readFileSync(join(projectRoot, 'src', 'cli.ts'), 'utf-8') + + // The TTY error message should mention auto as an alternative + assert.ok( + cliSource.includes('gsd auto') || cliSource.includes('gsd headless'), + 'TTY error hints should mention headless/auto mode as alternatives', + ) +}) + +// ═══════════════════════════════════════════════════════════════════════════ +// `gsd headless` still works (no regression) +// ═══════════════════════════════════════════════════════════════════════════ + +test('cli.ts handles `headless` subcommand before interactive TUI', () => { + const cliSource = readFileSync(join(projectRoot, 'src', 'cli.ts'), 'utf-8') + + const headlessMatch = cliSource.match(/messages\[0\]\s*===\s*['"]headless['"]/) + const tuiMatch = cliSource.match(/new\s+InteractiveMode\s*\(/) + + assert.ok(headlessMatch, 'headless subcommand handler exists') + assert.ok(tuiMatch, 'InteractiveMode TUI exists') + + const headlessPos = cliSource.indexOf(headlessMatch![0]) + const tuiPos = cliSource.indexOf(tuiMatch![0]) + assert.ok(headlessPos < tuiPos, 'headless handler is before TUI') +}) diff --git a/src/tests/auto-piped-io.test.ts b/src/tests/auto-piped-io.test.ts new file mode 100644 index 000000000..84bb5fbc1 --- /dev/null +++ b/src/tests/auto-piped-io.test.ts @@ -0,0 +1,172 @@ +/** + * Tests for auto-mode piped I/O detection (#2732). + * + * When `gsd auto` is run with piped stdout (e.g. `gsd auto | cat`), + * the CLI should detect the non-TTY stdout and redirect to headless + * mode instead of hanging in interactive mode trying to set up a TUI + * on a non-terminal output stream. + * + * Also verifies the stdout TTY gate at the interactive mode entry point: + * when stdout is piped, interactive mode must not be entered regardless + * of the subcommand. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; + +// ─── Extracted detection logic (mirrors cli.ts) ─────────────────────────── + +/** + * Subcommands that are explicitly handled before the interactive mode + * section in cli.ts and therefore never fall through to the TUI. + */ +const EXPLICIT_SUBCOMMANDS = new Set([ + "headless", + "update", + "config", + "worktree", + "wt", + "sessions", + "web", +]); + +/** + * Detect whether the current subcommand should be auto-redirected + * to headless mode when stdout is not a TTY. + * + * Returns true when: the subcommand is "auto" AND stdout is piped. + */ +function shouldRedirectAutoToHeadless( + subcommand: string | undefined, + stdoutIsTTY: boolean, +): boolean { + if (stdoutIsTTY) return false; + return subcommand === "auto"; +} + +/** + * Check whether interactive mode can be entered. + * Both stdin AND stdout must be TTY for the TUI to work. + */ +function canEnterInteractiveMode( + stdinIsTTY: boolean, + stdoutIsTTY: boolean, +): boolean { + return stdinIsTTY && stdoutIsTTY; +} + +/** + * Returns true if the subcommand is handled by an explicit branch + * in cli.ts and will never reach the interactive mode section. + */ +function isExplicitSubcommand(subcommand: string | undefined): boolean { + return subcommand !== undefined && EXPLICIT_SUBCOMMANDS.has(subcommand); +} + +// ─── shouldRedirectAutoToHeadless ───────────────────────────────────────── + +test("redirects 'auto' to headless when stdout is piped", () => { + assert.ok(shouldRedirectAutoToHeadless("auto", false)); +}); + +test("does NOT redirect 'auto' when stdout is a TTY", () => { + assert.ok(!shouldRedirectAutoToHeadless("auto", true)); +}); + +test("does NOT redirect non-auto subcommands when stdout is piped", () => { + assert.ok(!shouldRedirectAutoToHeadless("headless", false)); + assert.ok(!shouldRedirectAutoToHeadless("config", false)); + assert.ok(!shouldRedirectAutoToHeadless("update", false)); + assert.ok(!shouldRedirectAutoToHeadless(undefined, false)); +}); + +// ─── canEnterInteractiveMode ────────────────────────────────────────────── + +test("allows interactive mode when both stdin and stdout are TTY", () => { + assert.ok(canEnterInteractiveMode(true, true)); +}); + +test("blocks interactive mode when stdin is piped", () => { + assert.ok(!canEnterInteractiveMode(false, true)); +}); + +test("blocks interactive mode when stdout is piped", () => { + assert.ok(!canEnterInteractiveMode(true, false)); +}); + +test("blocks interactive mode when both stdin and stdout are piped", () => { + assert.ok(!canEnterInteractiveMode(false, false)); +}); + +// ─── isExplicitSubcommand ───────────────────────────────────────────────── + +test("identifies explicitly handled subcommands", () => { + assert.ok(isExplicitSubcommand("headless")); + assert.ok(isExplicitSubcommand("update")); + assert.ok(isExplicitSubcommand("config")); + assert.ok(isExplicitSubcommand("worktree")); + assert.ok(isExplicitSubcommand("wt")); + assert.ok(isExplicitSubcommand("sessions")); + assert.ok(isExplicitSubcommand("web")); +}); + +test("does NOT identify 'auto' as explicit subcommand", () => { + assert.ok(!isExplicitSubcommand("auto")); +}); + +test("does NOT identify undefined as explicit subcommand", () => { + assert.ok(!isExplicitSubcommand(undefined)); +}); + +// ─── End-to-end scenario: gsd auto | cat ────────────────────────────────── + +test("scenario: 'gsd auto 2>&1 | cat' — should redirect to headless", () => { + // Simulates: subcommand = "auto", stdin is TTY, stdout is piped + const subcommand = "auto"; + const stdinIsTTY = true; + const stdoutIsTTY = false; + + // Interactive mode should be blocked + assert.ok(!canEnterInteractiveMode(stdinIsTTY, stdoutIsTTY)); + + // Auto should be redirected to headless + assert.ok(shouldRedirectAutoToHeadless(subcommand, stdoutIsTTY)); +}); + +test("scenario: 'gsd auto > /tmp/output.txt' — should redirect to headless", () => { + const subcommand = "auto"; + const stdinIsTTY = true; + const stdoutIsTTY = false; + + assert.ok(!canEnterInteractiveMode(stdinIsTTY, stdoutIsTTY)); + assert.ok(shouldRedirectAutoToHeadless(subcommand, stdoutIsTTY)); +}); + +test("scenario: 'gsd auto' in terminal — normal interactive mode", () => { + const subcommand = "auto"; + const stdinIsTTY = true; + const stdoutIsTTY = true; + + assert.ok(canEnterInteractiveMode(stdinIsTTY, stdoutIsTTY)); + assert.ok(!shouldRedirectAutoToHeadless(subcommand, stdoutIsTTY)); +}); + +test("scenario: 'echo msg | gsd auto' — stdin piped, should redirect", () => { + const subcommand = "auto"; + const stdinIsTTY = false; + const stdoutIsTTY = true; // stdout is TTY even though stdin is piped + + // stdout is TTY, so auto redirect doesn't trigger... + assert.ok(!shouldRedirectAutoToHeadless(subcommand, stdoutIsTTY)); + // ...but interactive mode is blocked because stdin is piped + assert.ok(!canEnterInteractiveMode(stdinIsTTY, stdoutIsTTY)); +}); + +test("scenario: 'echo msg | gsd auto | cat' — both piped", () => { + const subcommand = "auto"; + const stdinIsTTY = false; + const stdoutIsTTY = false; + + assert.ok(!canEnterInteractiveMode(stdinIsTTY, stdoutIsTTY)); + assert.ok(shouldRedirectAutoToHeadless(subcommand, stdoutIsTTY)); +}); diff --git a/src/tests/auto-resume-resource-loader.test.ts b/src/tests/auto-resume-resource-loader.test.ts new file mode 100644 index 000000000..9926e87c2 --- /dev/null +++ b/src/tests/auto-resume-resource-loader.test.ts @@ -0,0 +1,56 @@ +// GSD2 — Regression test: auto-mode resume resolves resource-loader.js from deployed path (#3949) +// Copyright (c) 2026 Jeremy McSpadden +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const autoTsPath = join(__dirname, "..", "resources", "extensions", "gsd", "auto.ts"); +const loaderTsPath = join(__dirname, "..", "loader.ts"); + +test("loader.ts sets GSD_PKG_ROOT env var", () => { + const loaderSrc = readFileSync(loaderTsPath, "utf-8"); + assert.ok( + loaderSrc.includes("process.env.GSD_PKG_ROOT"), + "loader.ts must set GSD_PKG_ROOT so deployed extensions can locate package-root modules", + ); +}); + +test("auto.ts resume uses GSD_PKG_ROOT for resource-loader import, not bare relative path", () => { + const autoSrc = readFileSync(autoTsPath, "utf-8"); + + // Must reference GSD_PKG_ROOT to build an absolute path + assert.ok( + autoSrc.includes("process.env.GSD_PKG_ROOT"), + "auto.ts must use GSD_PKG_ROOT to resolve resource-loader.js from deployed extension path", + ); + + // The import must use the computed variable (resourceLoaderPath), not a hardcoded relative path. + assert.ok( + autoSrc.includes("await import(resourceLoaderPath)"), + "auto.ts resource-loader import must use the computed resourceLoaderPath variable, not a hardcoded relative path", + ); + + // The resourceLoaderPath must be constructed from GSD_PKG_ROOT via pathToFileURL + // (raw filesystem paths break on Windows with ERR_UNSUPPORTED_ESM_URL_SCHEME) + assert.ok( + autoSrc.includes("pathToFileURL(join(pkgRoot,"), + "auto.ts must convert the constructed path to a file URL for cross-platform import()", + ); +}); + +test("GSD_PKG_ROOT resolves resource-loader.js correctly from package root", () => { + // Simulate what auto.ts does: given GSD_PKG_ROOT, construct the path + const pkgRoot = resolve(__dirname, "..", ".."); + const resourceLoaderPath = join(pkgRoot, "dist", "resource-loader.js"); + + // After build, dist/resource-loader.js should exist + // (this test runs post-build in CI; in dev it validates the path construction) + const expectedDir = dirname(resourceLoaderPath); + assert.ok( + expectedDir.endsWith(join("dist")), + `resource-loader path should be under dist/, got: ${expectedDir}`, + ); +}); diff --git a/src/tests/bridge-package-root.test.ts b/src/tests/bridge-package-root.test.ts new file mode 100644 index 000000000..8e46101ff --- /dev/null +++ b/src/tests/bridge-package-root.test.ts @@ -0,0 +1,71 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { join } from 'node:path' + +/** + * Regression test for #1881: Windows web mode — hardcoded Linux CI path in + * standalone build. + * + * The Next.js standalone build bakes import.meta.url into compiled chunks as + * the CI runner's absolute Linux path (file:///home/runner/work/gsd-2/gsd-2/…). + * On Windows, fileURLToPath() rejects this with "File URL path must be + * absolute". The fix wraps the derivation in safePackageRootFromImportUrl() + * so the module-level constant never throws, and resolveBridgeRuntimeConfig + * falls through to the GSD_WEB_PACKAGE_ROOT env var. + */ + +import { safePackageRootFromImportUrl } from '../web/safe-import-meta-resolve.ts' + +test('safePackageRootFromImportUrl returns a path for a valid native file URL', () => { + const result = safePackageRootFromImportUrl(import.meta.url) + assert.ok(result !== null, 'should return a path for a valid native file URL') + assert.ok(typeof result === 'string') + assert.ok(result.length > 0) +}) + +test('safePackageRootFromImportUrl returns null for a non-file URL', () => { + const result = safePackageRootFromImportUrl('https://example.com/foo/bar.ts') + assert.equal(result, null) +}) + +test('safePackageRootFromImportUrl returns null for empty input', () => { + const result = safePackageRootFromImportUrl('') + assert.equal(result, null) +}) + +test('safePackageRootFromImportUrl returns null for malformed URL', () => { + const result = safePackageRootFromImportUrl('not-a-url') + assert.equal(result, null) +}) + +test('safePackageRootFromImportUrl respects ancestorLevels', () => { + // With 0 levels, should return the directory of the module itself + const level0 = safePackageRootFromImportUrl(import.meta.url, 0) + const level2 = safePackageRootFromImportUrl(import.meta.url, 2) + assert.ok(level0 !== null) + assert.ok(level2 !== null) + // level0 is deeper than level2 + assert.ok(level0.length > level2.length) +}) + +test('bridge-service.ts uses safePackageRootFromImportUrl for DEFAULT_PACKAGE_ROOT', () => { + const source = readFileSync(join(process.cwd(), 'src', 'web', 'bridge-service.ts'), 'utf-8') + assert.ok( + source.includes('safePackageRootFromImportUrl(import.meta.url)'), + 'bridge-service.ts must derive DEFAULT_PACKAGE_ROOT via the safe helper', + ) + const rawPattern = 'const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url' + assert.ok( + !source.includes(rawPattern), + 'bridge-service.ts must not use raw fileURLToPath for DEFAULT_PACKAGE_ROOT', + ) +}) + +test('bridge-service resolveBridgeRuntimeConfig falls back to lazy default', () => { + const source = readFileSync(join(process.cwd(), 'src', 'web', 'bridge-service.ts'), 'utf-8') + assert.ok( + source.includes('env.GSD_WEB_PACKAGE_ROOT || getDefaultPackageRoot()'), + 'resolveBridgeRuntimeConfig must fall back to lazy default package root', + ) +}) diff --git a/src/tests/cli-onboarding-custom-provider.test.ts b/src/tests/cli-onboarding-custom-provider.test.ts new file mode 100644 index 000000000..3f7644d53 --- /dev/null +++ b/src/tests/cli-onboarding-custom-provider.test.ts @@ -0,0 +1,37 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { SettingsManager } from "../../packages/pi-coding-agent/src/core/settings-manager.ts"; + +test("SettingsManager reads defaultProvider/defaultModel from the explicit agentDir used by CLI (#3860)", () => { + const root = mkdtempSync(join(tmpdir(), "gsd-cli-settings-")); + const cwd = join(root, "project"); + const agentDir = join(root, ".gsd", "agent"); + + try { + mkdirSync(cwd, { recursive: true }); + mkdirSync(agentDir, { recursive: true }); + writeFileSync( + join(agentDir, "settings.json"), + JSON.stringify({ + defaultProvider: "example-provider", + defaultModel: "gpt-5.4", + }), + "utf-8", + ); + + const settingsManager = SettingsManager.create(cwd, agentDir); + assert.equal(settingsManager.getDefaultProvider(), "example-provider"); + assert.equal(settingsManager.getDefaultModel(), "gpt-5.4"); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("cli.ts wires SettingsManager.create with both cwd and agentDir (#3860)", () => { + const cliSource = readFileSync(join(import.meta.dirname, "..", "cli.ts"), "utf-8"); + assert.match(cliSource, /SettingsManager\.create\(process\.cwd\(\),\s*agentDir\)/); +}); diff --git a/src/tests/create-gsd-extension-paths.test.ts b/src/tests/create-gsd-extension-paths.test.ts new file mode 100644 index 000000000..7aff613b3 --- /dev/null +++ b/src/tests/create-gsd-extension-paths.test.ts @@ -0,0 +1,76 @@ +/** + * Validates that the create-gsd-extension skill documentation uses the correct + * community extension install path (~/.pi/agent/extensions/) instead of the + * bundled-only path (~/.gsd/agent/extensions/). + * + * Bug: https://github.com/gsd-build/gsd-2/issues/3131 + * + * ~/.gsd/agent/extensions/ is reserved for bundled extensions synced from + * the gsd-pi package. Community/user extensions must use ~/.pi/agent/extensions/. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const skillDir = join(__dirname, "..", "resources", "skills", "create-gsd-extension"); + +function readSkillFile(relativePath: string): string { + return readFileSync(join(skillDir, relativePath), "utf-8"); +} + +// All documentation files that reference community extension paths +const docsToCheck: { file: string; label: string }[] = [ + { file: "SKILL.md", label: "SKILL.md" }, + { file: "references/key-rules-gotchas.md", label: "key-rules-gotchas.md" }, + { file: "workflows/add-capability.md", label: "add-capability.md" }, + { file: "workflows/create-extension.md", label: "create-extension.md" }, + { file: "workflows/debug-extension.md", label: "debug-extension.md" }, +]; + +test("create-gsd-extension docs use ~/.pi/agent/extensions/ for community extensions", async (t) => { + for (const { file, label } of docsToCheck) { + await t.test(`${label} references ~/.pi/agent/extensions/ for global extensions`, () => { + const content = readSkillFile(file); + + // The doc should reference ~/.pi/agent/extensions/ (community path) + assert.ok( + content.includes("~/.pi/agent/extensions/"), + `${label} should reference ~/.pi/agent/extensions/ for community extensions`, + ); + }); + } +}); + +test("create-gsd-extension docs do NOT direct users to install in ~/.gsd/agent/extensions/", async (t) => { + for (const { file, label } of docsToCheck) { + await t.test(`${label} does not tell users to place extensions in ~/.gsd/agent/extensions/`, () => { + const content = readSkillFile(file); + + // ~/.gsd/agent/extensions/ should only appear in context that clearly marks + // it as reserved/bundled, never as an install target for community extensions. + // We check that it does NOT appear as a "Global extensions:" or "Global:" path directive. + const lines = content.split("\n"); + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (line.includes("~/.gsd/agent/extensions/")) { + // If the line references ~/.gsd/agent/extensions/, it must be in a + // context explaining it is reserved/bundled — not as an install instruction. + const context = lines.slice(Math.max(0, i - 2), i + 3).join("\n"); + const isBundledContext = + context.toLowerCase().includes("bundled") || + context.toLowerCase().includes("reserved") || + context.toLowerCase().includes("synced"); + assert.ok( + isBundledContext, + `${label} line ${i + 1} references ~/.gsd/agent/extensions/ without ` + + `marking it as bundled/reserved. Context:\n${context}`, + ); + } + } + }); + } +}); diff --git a/src/tests/ensure-workspace-builds.test.ts b/src/tests/ensure-workspace-builds.test.ts index f256c7afe..965d2348e 100644 --- a/src/tests/ensure-workspace-builds.test.ts +++ b/src/tests/ensure-workspace-builds.test.ts @@ -1,12 +1,12 @@ import { describe, it, beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; -import { mkdtempSync, writeFileSync, mkdirSync, rmSync, utimesSync } from "node:fs"; +import { mkdtempSync, writeFileSync, mkdirSync, rmSync, utimesSync, statSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { createRequire } from "node:module"; const require = createRequire(import.meta.url); -const { newestSrcMtime } = require("../../scripts/ensure-workspace-builds.cjs"); +const { newestSrcMtime, detectStalePackages } = require("../../scripts/ensure-workspace-builds.cjs"); describe("newestSrcMtime", () => { let tmp: string; @@ -62,3 +62,95 @@ describe("newestSrcMtime", () => { assert.equal(newestSrcMtime(tmp), 0); }); }); + +describe("detectStalePackages", () => { + let tmp: string; + + beforeEach(() => { tmp = mkdtempSync(join(tmpdir(), "gsd-stale-test-")); }); + afterEach(() => { rmSync(tmp, { recursive: true, force: true }); }); + + /** + * Helper to create a fake workspace package with src/ and dist/ directories. + * Sets timestamps to simulate npm tarball extraction where src/ files can be + * 1 second newer than dist/ files. + */ + function createFakePackage( + packagesDir: string, + pkgName: string, + opts: { srcNewerThanDist?: boolean; missingDist?: boolean } = {}, + ): void { + const pkgDir = join(packagesDir, pkgName); + const srcDir = join(pkgDir, "src"); + const distDir = join(pkgDir, "dist"); + mkdirSync(srcDir, { recursive: true }); + writeFileSync(join(srcDir, "index.ts"), "export const x = 1;"); + + if (!opts.missingDist) { + mkdirSync(distDir, { recursive: true }); + writeFileSync(join(distDir, "index.js"), "export const x = 1;"); + } + + if (opts.srcNewerThanDist && !opts.missingDist) { + // Simulate npm tarball extraction: src/ is 1 second newer than dist/ + const distTime = new Date("2024-06-01T00:00:00Z"); + const srcTime = new Date("2024-06-01T00:00:01Z"); + utimesSync(join(distDir, "index.js"), distTime, distTime); + utimesSync(join(srcDir, "index.ts"), srcTime, srcTime); + } + } + + it("detects missing dist/ as stale regardless of .git presence", () => { + const packagesDir = join(tmp, "packages"); + mkdirSync(packagesDir, { recursive: true }); + createFakePackage(packagesDir, "test-pkg", { missingDist: true }); + + const result = detectStalePackages(tmp, ["test-pkg"]); + assert.deepEqual(result, ["test-pkg"]); + }); + + it("detects stale src > dist timestamps in a git repo (dev clone)", () => { + // Simulate a git repo by creating .git directory + mkdirSync(join(tmp, ".git"), { recursive: true }); + const packagesDir = join(tmp, "packages"); + mkdirSync(packagesDir, { recursive: true }); + createFakePackage(packagesDir, "test-pkg", { srcNewerThanDist: true }); + + const result = detectStalePackages(tmp, ["test-pkg"]); + assert.deepEqual(result, ["test-pkg"]); + }); + + it("skips staleness check when not in a git repo (npm tarball install)", () => { + // No .git directory — simulates npm install from tarball + const packagesDir = join(tmp, "packages"); + mkdirSync(packagesDir, { recursive: true }); + createFakePackage(packagesDir, "test-pkg", { srcNewerThanDist: true }); + + // Even though src/ is newer than dist/, the script should NOT detect it + // as stale because we're in an npm tarball (no .git directory). + // The timestamp difference is an artifact of npm tarball extraction. + const result = detectStalePackages(tmp, ["test-pkg"]); + assert.deepEqual(result, [], "should not detect staleness in npm tarball installs (no .git)"); + }); + + it("still detects missing dist/ in npm tarball installs", () => { + // No .git directory — simulates npm install from tarball + const packagesDir = join(tmp, "packages"); + mkdirSync(packagesDir, { recursive: true }); + createFakePackage(packagesDir, "test-pkg", { missingDist: true }); + + // Missing dist/ should always be detected, even in npm installs + const result = detectStalePackages(tmp, ["test-pkg"]); + assert.deepEqual(result, ["test-pkg"]); + }); + + it("returns empty array when dist/ is up to date", () => { + mkdirSync(join(tmp, ".git"), { recursive: true }); + const packagesDir = join(tmp, "packages"); + mkdirSync(packagesDir, { recursive: true }); + createFakePackage(packagesDir, "test-pkg"); + // Default: timestamps are equal (both set by writeFileSync at ~same time) + + const result = detectStalePackages(tmp, ["test-pkg"]); + assert.deepEqual(result, []); + }); +}); diff --git a/src/tests/extension-load-perf.test.ts b/src/tests/extension-load-perf.test.ts new file mode 100644 index 000000000..0142ff5e2 --- /dev/null +++ b/src/tests/extension-load-perf.test.ts @@ -0,0 +1,87 @@ +/** + * Extension loading performance test + * + * Regression test for https://github.com/gsd-build/gsd-2/issues/2108 + * + * Verifies that loading multiple extensions sharing common dependencies + * does NOT re-compile those dependencies for each extension. The jiti + * module cache must be shared across extension loads so that shared + * modules are compiled once. + * + * Uses the built dist/ (not raw TS source) because pi-coding-agent uses + * TypeScript features unsupported by --experimental-strip-types. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +// Import loadExtensions from the compiled dist (it IS re-exported from the +// core/extensions barrel but not from the top-level index). +// Use process.cwd() rather than import.meta.url-relative navigation — the +// compiled test lands in dist-test/src/tests/, so relative paths differ between +// source and compiled contexts. process.cwd() is always the repo root in CI. +const loaderPath = join( + process.cwd(), + "packages", "pi-coding-agent", "dist", "core", "extensions", "loader.js", +); + +test("loadExtensions shares module cache across extensions (perf regression #2108)", async () => { + const { loadExtensions } = await import(loaderPath); + + // Create a temp directory with two extensions that import a shared helper + const tmp = mkdtempSync(join(tmpdir(), "gsd-perf-test-")); + + try { + // Shared helper module + const sharedDir = join(tmp, "shared"); + mkdirSync(sharedDir, { recursive: true }); + writeFileSync( + join(sharedDir, "helper.ts"), + `export const SHARED_VALUE = "shared-${Date.now()}";\n`, + ); + + // Extension A — imports the shared helper + const extADir = join(tmp, "ext-a"); + mkdirSync(extADir, { recursive: true }); + writeFileSync( + join(extADir, "index.ts"), + `import { SHARED_VALUE } from "${join(sharedDir, "helper.ts").replace(/\\/g, "/")}";\n` + + `export default function(api: any) {\n` + + ` api.registerCommand("ext-a-cmd", { description: "test A " + SHARED_VALUE, handler: async () => {} });\n` + + `}\n`, + ); + + // Extension B — imports the same shared helper + const extBDir = join(tmp, "ext-b"); + mkdirSync(extBDir, { recursive: true }); + writeFileSync( + join(extBDir, "index.ts"), + `import { SHARED_VALUE } from "${join(sharedDir, "helper.ts").replace(/\\/g, "/")}";\n` + + `export default function(api: any) {\n` + + ` api.registerCommand("ext-b-cmd", { description: "test B " + SHARED_VALUE, handler: async () => {} });\n` + + `}\n`, + ); + + const paths = [join(extADir, "index.ts"), join(extBDir, "index.ts")]; + const start = Date.now(); + const result = await loadExtensions(paths, tmp); + const elapsed = Date.now() - start; + + // Both extensions should load without errors + assert.strictEqual(result.errors.length, 0, `Extension errors: ${JSON.stringify(result.errors)}`); + assert.strictEqual(result.extensions.length, 2, "Expected 2 extensions to load"); + + // With shared jiti cache, loading 2 trivial extensions that share a + // dependency should complete in well under 5 seconds. + assert.ok( + elapsed < 5000, + `Extension loading took ${elapsed}ms — expected < 5000ms. ` + + `This suggests jiti module caching is not shared across extensions.`, + ); + } finally { + try { rmSync(tmp, { recursive: true, force: true, maxRetries: 3 }); } catch { /* cleanup */ } + } +}); diff --git a/src/tests/extension-model-validation.test.ts b/src/tests/extension-model-validation.test.ts new file mode 100644 index 000000000..22ae05c1a --- /dev/null +++ b/src/tests/extension-model-validation.test.ts @@ -0,0 +1,169 @@ +/** + * Regression test for #2626: Extension-provided models silently overwritten on startup. + * + * The startup model-validation logic must run AFTER extensions register their + * models in the ModelRegistry. When validation runs before extensions load, + * extension-provided models (e.g. claude-code/claude-sonnet-4-6) are not yet + * in the registry, so configuredExists is always false and the user's choice + * is silently replaced with a built-in fallback. + * + * This test exercises `validateConfiguredModel()` directly (once extracted) to + * verify that: + * (a) extension models present in the registry are preserved, + * (b) genuinely missing models still trigger fallback selection. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +const { validateConfiguredModel } = await import("../startup-model-validation.js"); + +/** + * Minimal stub of ModelRegistry with just getAll() / getAvailable(). + */ +function fakeModelRegistry(models: Array<{ provider: string; id: string }>) { + const available = models.map((m) => ({ + ...m, + name: m.id, + contextWindow: 128_000, + maxTokens: 4096, + reasoning: false, + })); + return { + getAll: () => available, + getAvailable: () => available, + }; +} + +/** + * Minimal stub of SettingsManager backed by plain objects. + */ +function fakeSettingsManager(initial: { provider?: string; model?: string }) { + let provider = initial.provider; + let model = initial.model; + let thinkingLevel = "off" as string; + return { + getDefaultProvider: () => provider, + getDefaultModel: () => model, + getDefaultThinkingLevel: () => thinkingLevel, + setDefaultModelAndProvider(p: string, m: string) { + provider = p; + model = m; + }, + setDefaultThinkingLevel(level: string) { + thinkingLevel = level; + }, + // Expose for assertions + get currentProvider() { return provider; }, + get currentModel() { return model; }, + }; +} + +// ────────────────────────────────────────────────────────────────────── +// Test: extension-provided model in registry must NOT be overwritten +// ────────────────────────────────────────────────────────────────────── +test("validateConfiguredModel preserves extension-provided model when present in registry", () => { + const settings = fakeSettingsManager({ + provider: "claude-code", + model: "claude-sonnet-4-6", + }); + + // Registry includes the extension model (simulating post-extension-load state) + const registry = fakeModelRegistry([ + { provider: "openai", id: "gpt-5.4" }, + { provider: "claude-code", id: "claude-sonnet-4-6" }, + ]); + + validateConfiguredModel(registry as any, settings as any); + + assert.equal(settings.currentProvider, "claude-code", + "provider must remain the user-configured extension provider"); + assert.equal(settings.currentModel, "claude-sonnet-4-6", + "model must remain the user-configured extension model"); +}); + +// ────────────────────────────────────────────────────────────────────── +// Test: genuinely removed model still triggers fallback +// ────────────────────────────────────────────────────────────────────── +test("validateConfiguredModel falls back when model is not in registry", () => { + const settings = fakeSettingsManager({ + provider: "openai", + model: "grok-2", // hypothetical removed model + }); + + const registry = fakeModelRegistry([ + { provider: "openai", id: "gpt-5.4" }, + { provider: "anthropic", id: "claude-opus-4-6" }, + ]); + + validateConfiguredModel(registry as any, settings as any); + + // Should have been overwritten to one of the available models + assert.notEqual(settings.currentModel, "grok-2", + "stale model must be replaced by a fallback"); + assert.ok(settings.currentProvider, "a fallback provider must be set"); + assert.ok(settings.currentModel, "a fallback model must be set"); +}); + +// ────────────────────────────────────────────────────────────────────── +// Test: no configured model at all triggers fallback +// ────────────────────────────────────────────────────────────────────── +test("validateConfiguredModel picks a fallback when nothing is configured", () => { + const settings = fakeSettingsManager({ + provider: undefined, + model: undefined, + }); + + const registry = fakeModelRegistry([ + { provider: "openai", id: "gpt-5.4" }, + ]); + + validateConfiguredModel(registry as any, settings as any); + + assert.equal(settings.currentProvider, "openai"); + assert.equal(settings.currentModel, "gpt-5.4"); +}); + +// ────────────────────────────────────────────────────────────────────── +// Test: thinking level reset when model doesn't exist +// ────────────────────────────────────────────────────────────────────── +test("validateConfiguredModel resets thinking level when model was replaced", () => { + const settings = fakeSettingsManager({ + provider: "openai", + model: "grok-2", + }); + // Simulate non-off thinking level + settings.setDefaultThinkingLevel("high"); + + const registry = fakeModelRegistry([ + { provider: "openai", id: "gpt-5.4" }, + ]); + + validateConfiguredModel(registry as any, settings as any); + + assert.equal(settings.getDefaultThinkingLevel(), "off", + "thinking level must be reset to off when model was not found"); +}); + +// ────────────────────────────────────────────────────────────────────── +// Test: thinking level NOT reset when model exists +// ────────────────────────────────────────────────────────────────────── +test("validateConfiguredModel preserves thinking level when model exists", () => { + const settings = fakeSettingsManager({ + provider: "openai", + model: "gpt-5.4", + }); + settings.setDefaultThinkingLevel("high"); + + const registry = fakeModelRegistry([ + { provider: "openai", id: "gpt-5.4" }, + ]); + + validateConfiguredModel(registry as any, settings as any); + + assert.equal(settings.getDefaultThinkingLevel(), "high", + "thinking level must be preserved when configured model exists"); +}); diff --git a/src/tests/google-search-auth.repro.test.ts b/src/tests/google-search-auth.repro.test.ts index 309bbb72b..5dac025fb 100644 --- a/src/tests/google-search-auth.repro.test.ts +++ b/src/tests/google-search-auth.repro.test.ts @@ -1,6 +1,6 @@ import test from "node:test"; import assert from "node:assert/strict"; -import googleSearchExtension from "../resources/extensions/google-search/index.ts"; +import googleSearchExtension from "../resources/extensions/google-search/index.js"; function createMockPI() { const handlers: any[] = []; diff --git a/src/tests/google-search-oauth-shape.test.ts b/src/tests/google-search-oauth-shape.test.ts new file mode 100644 index 000000000..66aa072e5 --- /dev/null +++ b/src/tests/google-search-oauth-shape.test.ts @@ -0,0 +1,215 @@ +/** + * google-search-oauth-shape.test.ts — Regression test for #2963. + * + * The OAuth fallback in google_search manually POSTs to the Cloud Code Assist + * endpoint. The original implementation sent a request body that did not match + * the endpoint's expected contract, causing a 400 INVALID_ARGUMENT response. + * + * This test captures the fetch call and asserts that the URL and body conform + * to the Cloud Code Assist wire format used by the working provider in + * packages/pi-ai/src/providers/google-gemini-cli.ts. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import googleSearchExtension from "../resources/extensions/google-search/index.js"; + +// ── Helpers ───────────────────────────────────────────────────────────────── + +function createMockPI() { + const handlers: Array<{ event: string; handler: any }> = []; + let registeredTool: any = null; + + return { + handlers, + get registeredTool() { return registeredTool; }, + on(event: string, handler: any) { + handlers.push({ event, handler }); + }, + registerTool(tool: any) { + registeredTool = tool; + }, + async fire(event: string, eventData: any, ctx: any) { + for (const h of handlers) { + if (h.event === event) { + await h.handler(eventData, ctx); + } + } + }, + }; +} + +function mockModelRegistry(oauthJson?: string) { + return { + authStorage: { + hasAuth: async (_id: string) => !!oauthJson, + }, + getApiKeyForProvider: async (_provider: string) => oauthJson, + }; +} + +/** A valid SSE response body matching the Cloud Code Assist wire format. */ +function makeOkSSEBody() { + const payload = { + response: { + candidates: [{ + content: { + parts: [{ text: "Sunny, 85 °F in Austin today." }], + }, + groundingMetadata: { + groundingChunks: [ + { web: { title: "weather.com", uri: "https://weather.com/austin", domain: "weather.com" } }, + ], + webSearchQueries: ["weather today in Austin Texas"], + }, + }], + }, + }; + return `data: ${JSON.stringify(payload)}\n\n`; +} + +// ── Tests ──────────────────────────────────────────────────────────────────── + +test("#2963: OAuth fallback URL must include ?alt=sse query parameter", async (t) => { + const originalKey = process.env.GEMINI_API_KEY; + delete process.env.GEMINI_API_KEY; + const originalFetch = global.fetch; + + let capturedUrl = ""; + + (global as any).fetch = async (url: string, _options: any) => { + capturedUrl = url; + return { ok: true, text: async () => makeOkSSEBody() }; + }; + + t.after(() => { + global.fetch = originalFetch; + if (originalKey !== undefined) process.env.GEMINI_API_KEY = originalKey; + else delete process.env.GEMINI_API_KEY; + }); + + const pi = createMockPI(); + googleSearchExtension(pi as any); + + const oauthJson = JSON.stringify({ token: "tok", projectId: "proj" }); + const ctx = { ui: { notify() {} }, modelRegistry: mockModelRegistry(oauthJson) }; + + await pi.fire("session_start", {}, ctx); + await pi.registeredTool.execute("c1", { query: "weather" }, new AbortController().signal, () => {}, ctx); + + assert.ok( + capturedUrl.includes("?alt=sse"), + `URL must contain ?alt=sse for SSE parsing to work. Got: ${capturedUrl}`, + ); +}); + +test("#2963: OAuth fallback body must include userAgent field", async (t) => { + const originalKey = process.env.GEMINI_API_KEY; + delete process.env.GEMINI_API_KEY; + const originalFetch = global.fetch; + + let capturedBody: any = null; + + (global as any).fetch = async (_url: string, options: any) => { + capturedBody = JSON.parse(options.body); + return { ok: true, text: async () => makeOkSSEBody() }; + }; + + t.after(() => { + global.fetch = originalFetch; + if (originalKey !== undefined) process.env.GEMINI_API_KEY = originalKey; + else delete process.env.GEMINI_API_KEY; + }); + + const pi = createMockPI(); + googleSearchExtension(pi as any); + + const oauthJson = JSON.stringify({ token: "tok", projectId: "proj" }); + const ctx = { ui: { notify() {} }, modelRegistry: mockModelRegistry(oauthJson) }; + + await pi.fire("session_start", {}, ctx); + await pi.registeredTool.execute("c2", { query: "weather userAgent test" }, new AbortController().signal, () => {}, ctx); + + assert.ok(capturedBody, "fetch must have been called"); + assert.equal( + typeof capturedBody.userAgent, + "string", + "Body must include a userAgent field (Cloud Code Assist contract)", + ); +}); + +test("#2963: OAuth fallback body must contain google_search tool in correct format", async (t) => { + const originalKey = process.env.GEMINI_API_KEY; + delete process.env.GEMINI_API_KEY; + const originalFetch = global.fetch; + + let capturedBody: any = null; + + (global as any).fetch = async (_url: string, options: any) => { + capturedBody = JSON.parse(options.body); + return { ok: true, text: async () => makeOkSSEBody() }; + }; + + t.after(() => { + global.fetch = originalFetch; + if (originalKey !== undefined) process.env.GEMINI_API_KEY = originalKey; + else delete process.env.GEMINI_API_KEY; + }); + + const pi = createMockPI(); + googleSearchExtension(pi as any); + + const oauthJson = JSON.stringify({ token: "tok", projectId: "proj" }); + const ctx = { ui: { notify() {} }, modelRegistry: mockModelRegistry(oauthJson) }; + + await pi.fire("session_start", {}, ctx); + await pi.registeredTool.execute("c3", { query: "weather tools test" }, new AbortController().signal, () => {}, ctx); + + assert.ok(capturedBody, "fetch must have been called"); + const tools = capturedBody.request?.tools; + assert.ok(Array.isArray(tools), "request.tools must be an array"); + assert.ok( + tools.some((t: any) => t.googleSearch !== undefined), + `tools must contain a googleSearch entry. Got: ${JSON.stringify(tools)}`, + ); +}); + +test("#2963: OAuth fallback body has correct top-level structure", async (t) => { + const originalKey = process.env.GEMINI_API_KEY; + delete process.env.GEMINI_API_KEY; + const originalFetch = global.fetch; + + let capturedBody: any = null; + + (global as any).fetch = async (_url: string, options: any) => { + capturedBody = JSON.parse(options.body); + return { ok: true, text: async () => makeOkSSEBody() }; + }; + + t.after(() => { + global.fetch = originalFetch; + if (originalKey !== undefined) process.env.GEMINI_API_KEY = originalKey; + else delete process.env.GEMINI_API_KEY; + }); + + const pi = createMockPI(); + googleSearchExtension(pi as any); + + const oauthJson = JSON.stringify({ token: "tok", projectId: "proj" }); + const ctx = { ui: { notify() {} }, modelRegistry: mockModelRegistry(oauthJson) }; + + await pi.fire("session_start", {}, ctx); + await pi.registeredTool.execute("c4", { query: "weather structure test" }, new AbortController().signal, () => {}, ctx); + + assert.ok(capturedBody, "fetch must have been called"); + + // Top-level fields required by CloudCodeAssistRequest + assert.equal(capturedBody.project, "proj", "project must match the OAuth projectId"); + assert.ok(typeof capturedBody.model === "string" && capturedBody.model.length > 0, "model must be a non-empty string"); + assert.ok(capturedBody.request && typeof capturedBody.request === "object", "request must be an object"); + assert.ok(typeof capturedBody.userAgent === "string", "userAgent must be present"); + + // Nested request fields + assert.ok(Array.isArray(capturedBody.request.contents), "request.contents must be an array"); + assert.ok(Array.isArray(capturedBody.request.tools), "request.tools must be an array"); +}); diff --git a/src/tests/headless-multi-turn.test.ts b/src/tests/headless-multi-turn.test.ts new file mode 100644 index 000000000..19cb1b9bb --- /dev/null +++ b/src/tests/headless-multi-turn.test.ts @@ -0,0 +1,19 @@ +/** + * Regression test for #3547: discuss and plan must be classified as + * multi-turn commands in headless mode. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +test("headless.ts classifies discuss as multi-turn (#3547)", () => { + const src = readFileSync(join(__dirname, "..", "headless.ts"), "utf-8"); + const multiTurnLine = src.match(/isMultiTurnCommand\s*=\s*[^;]+/); + assert.ok(multiTurnLine, "isMultiTurnCommand must be defined"); + assert.ok(multiTurnLine![0].includes("discuss"), "discuss must be in multi-turn list"); + assert.ok(multiTurnLine![0].includes("plan"), "plan must be in multi-turn list"); +}); diff --git a/src/tests/headless-query-extension-path.test.ts b/src/tests/headless-query-extension-path.test.ts new file mode 100644 index 000000000..499509187 --- /dev/null +++ b/src/tests/headless-query-extension-path.test.ts @@ -0,0 +1,28 @@ +/** + * Regression test for #3471: headless-query must load extensions from + * the synced agent directory, not directly from src/resources/. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +test("headless-query resolves from agent extensions dir (#3471)", () => { + const src = readFileSync(join(__dirname, "..", "headless-query.ts"), "utf-8"); + assert.ok( + src.includes("agentExtensionsDir") || src.includes(".gsd/agent"), + "headless-query must resolve from synced agent directory", + ); +}); + +test("cli.ts calls initResources before headless (#3471)", () => { + const src = readFileSync(join(__dirname, "..", "cli.ts"), "utf-8"); + const headlessBlock = src.slice(src.indexOf("gsd headless")); + const initIdx = headlessBlock.indexOf("initResources"); + const runIdx = headlessBlock.indexOf("runHeadless"); + assert.ok(initIdx !== -1, "initResources must be called before headless"); + assert.ok(initIdx < runIdx, "initResources must come before runHeadless"); +}); diff --git a/src/tests/integration/web-auto-dashboard-lock-reconciliation.test.ts b/src/tests/integration/web-auto-dashboard-lock-reconciliation.test.ts new file mode 100644 index 000000000..dafdcffe1 --- /dev/null +++ b/src/tests/integration/web-auto-dashboard-lock-reconciliation.test.ts @@ -0,0 +1,199 @@ +/** + * Regression test for #2705: Web UI shows "Start auto" even while auto mode is + * already running. + * + * Root cause: collectAuthoritativeAutoDashboardData spawns a subprocess that + * imports auto.ts fresh. The module-level AutoSession state (s.active) is + * always false in a new process, so the subprocess always reports + * { active: false } even when auto IS running in the parent process. + * + * Fix: after obtaining the subprocess result, reconcile active/paused state + * with on-disk session lock and paused-session metadata. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { + collectAuthoritativeAutoDashboardData, +} from "../../web/auto-dashboard-service.ts"; + +// ─── Helpers ────────────────────────────────────────────────────────── + +const repoRoot = join(import.meta.dirname, "..", "..", ".."); + +function makeTempFixture(): { projectCwd: string; cleanup: () => void } { + const root = mkdtempSync(join(tmpdir(), "gsd-auto-lock-test-")); + const projectCwd = join(root, "project"); + mkdirSync(projectCwd, { recursive: true }); + return { + projectCwd, + cleanup: () => { + try { rmSync(root, { recursive: true, force: true }); } catch { /* best-effort */ } + }, + }; +} + +function writeAutoModule(dir: string, payload: Record): string { + const modulePath = join(dir, "fake-auto-dashboard.mjs"); + writeFileSync( + modulePath, + `export function getAutoDashboardData() { return ${JSON.stringify(payload)}; }\n`, + ); + return modulePath; +} + +function writeSessionLock(projectCwd: string, data: Record): void { + const gsdDir = join(projectCwd, ".gsd"); + mkdirSync(gsdDir, { recursive: true }); + writeFileSync(join(gsdDir, "auto.lock"), JSON.stringify(data)); +} + +function writePausedSession(projectCwd: string, data: Record): void { + const runtimeDir = join(projectCwd, ".gsd", "runtime"); + mkdirSync(runtimeDir, { recursive: true }); + writeFileSync(join(runtimeDir, "paused-session.json"), JSON.stringify(data)); +} + +const INACTIVE_PAYLOAD = { + active: false, + paused: false, + stepMode: false, + startTime: 0, + elapsed: 0, + currentUnit: null, + completedUnits: [], + basePath: "", + totalCost: 0, + totalTokens: 0, +}; + +// ─── Tests ────────────────────────────────────────────────────────── + +test("#2705 regression: subprocess reports active=false but session lock exists with live PID → reconcile to active=true", async (t) => { + const fixture = makeTempFixture(); + t.after(() => fixture.cleanup()); + + const modulePath = writeAutoModule(fixture.projectCwd, INACTIVE_PAYLOAD); + + // On disk: session lock exists with current PID (simulates auto running in parent process). + writeSessionLock(fixture.projectCwd, { + pid: process.pid, + startedAt: new Date().toISOString(), + unitType: "execute-task", + unitId: "M001/S01/T01", + unitStartedAt: new Date().toISOString(), + }); + + const result = await collectAuthoritativeAutoDashboardData(repoRoot, { + env: { + ...process.env, + GSD_WEB_TEST_AUTO_DASHBOARD_MODULE: modulePath, + GSD_WEB_PROJECT_CWD: fixture.projectCwd, + }, + }); + + // After reconciliation, active MUST be true because the lock PID is alive. + assert.equal(result.active, true, "active must be reconciled to true when session lock PID is alive"); + assert.equal(result.paused, false, "paused must remain false when no paused-session exists"); +}); + +test("#2705: subprocess reports active=false and no session lock → remains inactive", async (t) => { + const fixture = makeTempFixture(); + t.after(() => fixture.cleanup()); + + const modulePath = writeAutoModule(fixture.projectCwd, INACTIVE_PAYLOAD); + + const result = await collectAuthoritativeAutoDashboardData(repoRoot, { + env: { + ...process.env, + GSD_WEB_TEST_AUTO_DASHBOARD_MODULE: modulePath, + GSD_WEB_PROJECT_CWD: fixture.projectCwd, + }, + }); + + assert.equal(result.active, false, "active must remain false when no session lock exists"); + assert.equal(result.paused, false); +}); + +test("#2705: subprocess reports active=false but paused-session.json exists → reconcile to paused=true", async (t) => { + const fixture = makeTempFixture(); + t.after(() => fixture.cleanup()); + + const modulePath = writeAutoModule(fixture.projectCwd, INACTIVE_PAYLOAD); + + writePausedSession(fixture.projectCwd, { + milestoneId: "M001", + pausedAt: new Date().toISOString(), + stepMode: false, + }); + + const result = await collectAuthoritativeAutoDashboardData(repoRoot, { + env: { + ...process.env, + GSD_WEB_TEST_AUTO_DASHBOARD_MODULE: modulePath, + GSD_WEB_PROJECT_CWD: fixture.projectCwd, + }, + }); + + assert.equal(result.paused, true, "paused must be reconciled to true when paused-session.json exists"); + assert.equal(result.active, false, "active must remain false when paused (paused overrides active)"); +}); + +test("#2705: subprocess reports active=true → no reconciliation needed", async (t) => { + const fixture = makeTempFixture(); + t.after(() => fixture.cleanup()); + + const activePayload = { + active: true, + paused: false, + stepMode: true, + startTime: 1000, + elapsed: 500, + currentUnit: { type: "execute-task", id: "M001/S01/T01", startedAt: 1000 }, + completedUnits: [], + basePath: fixture.projectCwd, + totalCost: 1.5, + totalTokens: 1000, + }; + const modulePath = writeAutoModule(fixture.projectCwd, activePayload); + + const result = await collectAuthoritativeAutoDashboardData(repoRoot, { + env: { + ...process.env, + GSD_WEB_TEST_AUTO_DASHBOARD_MODULE: modulePath, + GSD_WEB_PROJECT_CWD: fixture.projectCwd, + }, + }); + + assert.equal(result.active, true, "active should remain true when subprocess already reports it"); +}); + +test("#2705: session lock exists but PID is dead → remains inactive (stale lock)", async (t) => { + const fixture = makeTempFixture(); + t.after(() => fixture.cleanup()); + + const modulePath = writeAutoModule(fixture.projectCwd, INACTIVE_PAYLOAD); + + // Use a PID that is almost certainly dead. + writeSessionLock(fixture.projectCwd, { + pid: 999999999, + startedAt: new Date().toISOString(), + unitType: "execute-task", + unitId: "M001/S01/T01", + unitStartedAt: new Date().toISOString(), + }); + + const result = await collectAuthoritativeAutoDashboardData(repoRoot, { + env: { + ...process.env, + GSD_WEB_TEST_AUTO_DASHBOARD_MODULE: modulePath, + GSD_WEB_PROJECT_CWD: fixture.projectCwd, + }, + }); + + assert.equal(result.active, false, "active must remain false when session lock PID is dead (stale lock)"); +}); diff --git a/src/tests/integration/web-live-interaction-contract.test.ts b/src/tests/integration/web-live-interaction-contract.test.ts index 5e288b69f..ce473ff40 100644 --- a/src/tests/integration/web-live-interaction-contract.test.ts +++ b/src/tests/integration/web-live-interaction-contract.test.ts @@ -358,6 +358,7 @@ function routeEvent(state: MinimalLiveState, event: any): MinimalLiveState { } case "tool_execution_start": { s.activeToolExecution = { id: event.toolCallId, name: event.toolName }; + s.streamingAssistantText = ""; break; } case "tool_execution_end": { @@ -802,6 +803,7 @@ test("(g-2) tool_execution_start/end update activeToolExecution", async () => { assert.ok(state.activeToolExecution); assert.equal(state.activeToolExecution.id, "tc-1"); assert.equal(state.activeToolExecution.name, "bash"); + assert.equal(state.streamingAssistantText, ""); state = routeEvent(state, { type: "tool_execution_end", @@ -813,6 +815,46 @@ test("(g-2) tool_execution_start/end update activeToolExecution", async () => { assert.equal(state.activeToolExecution, null); }); +test("(g-3) tool_execution_start clears provisional streaming text so only post-tool final text survives", async () => { + let state = createMinimalLiveState(); + + state = routeEvent(state, { + type: "message_update", + assistantMessageEvent: { + type: "text_delta", + delta: "It seems the questions were presented to the user. Let me wait for them to answer.", + }, + }); + assert.equal(state.streamingAssistantText, "It seems the questions were presented to the user. Let me wait for them to answer."); + + state = routeEvent(state, { + type: "tool_execution_start", + toolCallId: "tc-ask-1", + toolName: "ask_user_questions", + }); + assert.equal(state.streamingAssistantText, ""); + + state = routeEvent(state, { + type: "tool_execution_end", + toolCallId: "tc-ask-1", + toolName: "ask_user_questions", + result: {}, + isError: false, + }); + state = routeEvent(state, { + type: "message_update", + assistantMessageEvent: { + type: "text_delta", + delta: "What are you working on? Once you answer I'll tailor my approach accordingly.", + }, + }); + state = routeEvent(state, { type: "turn_end" }); + + assert.deepEqual(state.liveTranscript, [ + "What are you working on? Once you answer I'll tailor my approach accordingly.", + ]); +}); + test("(h) steer and abort commands post the correct RPC command type", async (t) => { const fixture = makeWorkspaceFixture(); const sessionPath = createSessionFile(fixture.projectCwd, fixture.sessionsDir, "sess-steer", "Steer Session"); diff --git a/src/tests/integration/web-live-state-contract.test.ts b/src/tests/integration/web-live-state-contract.test.ts index 2af24bcc6..bed3b44c2 100644 --- a/src/tests/integration/web-live-state-contract.test.ts +++ b/src/tests/integration/web-live-state-contract.test.ts @@ -397,10 +397,11 @@ test("/api/session/events exposes explicit live_state_invalidation events for ag harness.emit({ type: "auto_retry_end", success: false, attempt: 1, finalError: "still failing" }); harness.emit({ type: "auto_compaction_start", reason: "threshold" }); harness.emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false }); + harness.emit({ type: "turn_end" }); const events = await readSseEventsUntil( response, - (seen) => seen.filter((event) => event.type === "live_state_invalidation").length >= 5, + (seen) => seen.filter((event) => event.type === "live_state_invalidation").length >= 6, ); const invalidations = events.filter((event) => event.type === "live_state_invalidation"); @@ -416,6 +417,7 @@ test("/api/session/events exposes explicit live_state_invalidation events for ag { reason: "auto_retry_end", source: "bridge_event", workspaceIndexCacheInvalidated: false }, { reason: "auto_compaction_start", source: "bridge_event", workspaceIndexCacheInvalidated: false }, { reason: "auto_compaction_end", source: "bridge_event", workspaceIndexCacheInvalidated: false }, + { reason: "turn_end", source: "bridge_event", workspaceIndexCacheInvalidated: true }, ], "live_state_invalidation reasons/sources should stay inspectable on /api/session/events", ); @@ -424,6 +426,7 @@ test("/api/session/events exposes explicit live_state_invalidation events for ag assert.deepEqual(invalidations[2].domains, ["auto", "recovery"]); assert.deepEqual(invalidations[3].domains, ["auto", "recovery"]); assert.deepEqual(invalidations[4].domains, ["auto", "recovery"]); + assert.deepEqual(invalidations[5].domains, ["workspace"]); controller.abort(); await waitForMicrotasks(); @@ -585,3 +588,79 @@ test("workspace cache only busts on real boundaries and session mutations emit t unsubscribe(); }); + +test("turn_end events invalidate workspace so milestones list reflects current state (issue #2706)", async (t) => { + const fixture = makeWorkspaceFixture(); + const sessionPath = createSessionFile( + fixture.projectCwd, + fixture.sessionsDir, + "sess-turn", + "Turn Session", + "2026-03-15T03:32:00.000Z", + ); + let workspaceIndexCalls = 0; + + const harness = createHarness((command, current) => { + if (command.type === "get_state") { + current.emit({ + id: command.id, + type: "response", + command: "get_state", + success: true, + data: fakeSessionState("sess-turn", sessionPath), + }); + return; + } + + assert.fail(`unexpected command: ${command.type}`); + }); + + setupBridge(harness, fixture, { + indexWorkspace: async () => { + workspaceIndexCalls += 1; + return fakeWorkspaceIndex(); + }, + }); + + t.after(async () => { + await bridge.resetBridgeServiceForTests(); + onboarding.resetOnboardingServiceForTests(); + fixture.cleanup(); + }); + + const service = bridge.getProjectBridgeService(); + await service.ensureStarted(); + const seenEvents: any[] = []; + const unsubscribe = service.subscribe((event) => { + seenEvents.push(event); + }); + + // Load workspace once to prime cache + await bridge.collectBootPayload(); + assert.equal(workspaceIndexCalls, 1, "initial boot should call indexWorkspace once"); + + // Emit turn_end — this should invalidate the workspace cache so the + // milestones list picks up state changes that occurred during the turn. + harness.emit({ type: "turn_end" }); + await waitForMicrotasks(); + + // Verify a live_state_invalidation was emitted for turn_end + const invalidations = seenEvents.filter((event) => event.type === "live_state_invalidation"); + const turnEndInvalidation = invalidations.find((event) => event.reason === "turn_end"); + assert.ok(turnEndInvalidation, "turn_end should emit a live_state_invalidation event"); + assert.ok( + turnEndInvalidation.domains.includes("workspace"), + "turn_end invalidation should include the workspace domain", + ); + assert.equal( + turnEndInvalidation.workspaceIndexCacheInvalidated, + true, + "turn_end should invalidate the workspace index cache", + ); + + // Verify workspace cache was actually busted + await bridge.collectBootPayload(); + assert.equal(workspaceIndexCalls, 2, "turn_end should bust the workspace index cache so the next fetch re-indexes"); + + unsubscribe(); +}); diff --git a/src/tests/integration/web-mode-assembled.test.ts b/src/tests/integration/web-mode-assembled.test.ts index d476c7c89..6bc3cafa5 100644 --- a/src/tests/integration/web-mode-assembled.test.ts +++ b/src/tests/integration/web-mode-assembled.test.ts @@ -350,6 +350,7 @@ test("assembled lifecycle: boot → onboard → prompt → streaming text → to onboarding.configureOnboardingServiceForTests({ authStorage, + getEnvApiKey: () => undefined, validateApiKey: async () => ({ ok: true, message: "openai credentials validated" }), }); @@ -694,6 +695,7 @@ test("assembled settings controls keep retry visibility and daily-use mutations authStorage: AuthStorage.inMemory({ anthropic: { type: "api_key", key: "sk-test-assembled-settings" }, } as any), + getEnvApiKey: () => undefined, }); t.after(async () => { @@ -964,6 +966,7 @@ test("assembled slash-command behavior keeps built-ins safe while preserving GSD authStorage: AuthStorage.inMemory({ anthropic: { type: "api_key", key: "sk-test-assembled-slash" }, } as any), + getEnvApiKey: () => undefined, }); t.after(async () => { diff --git a/src/tests/integration/web-mode-cli.test.ts b/src/tests/integration/web-mode-cli.test.ts index 249e17568..9eee1f803 100644 --- a/src/tests/integration/web-mode-cli.test.ts +++ b/src/tests/integration/web-mode-cli.test.ts @@ -164,6 +164,8 @@ test('launchWebMode prefers the packaged standalone host and opens the resolved cwd: standaloneRoot, detached: true, stdio: 'ignore', + windowsHide: true, + shell: false, env: { TEST_ENV: '1', HOSTNAME: '127.0.0.1', diff --git a/src/tests/integration/web-mode-onboarding.test.ts b/src/tests/integration/web-mode-onboarding.test.ts index a3c9943a9..8977a42cf 100644 --- a/src/tests/integration/web-mode-onboarding.test.ts +++ b/src/tests/integration/web-mode-onboarding.test.ts @@ -301,6 +301,7 @@ test("successful browser onboarding restarts the stale bridge child and unlocks const harness = configureBridgeRuntime(fixture, authStorage); onboarding.configureOnboardingServiceForTests({ authStorage, + getEnvApiKey: () => undefined, validateApiKey: async () => ({ ok: true, message: "openai credentials validated" }), }); @@ -368,6 +369,7 @@ test("refresh failures keep the workspace locked and expose the failed bridge-re const harness = configureBridgeRuntime(fixture, authStorage, { failRestart: true }); onboarding.configureOnboardingServiceForTests({ authStorage, + getEnvApiKey: () => undefined, validateApiKey: async () => ({ ok: true, message: "openai credentials validated" }), }); diff --git a/src/tests/integration/web-mode-runtime-harness.ts b/src/tests/integration/web-mode-runtime-harness.ts index 62c491cec..3083d6bc9 100644 --- a/src/tests/integration/web-mode-runtime-harness.ts +++ b/src/tests/integration/web-mode-runtime-harness.ts @@ -13,6 +13,52 @@ const packagedWebHostPath = join(projectRoot, "dist", "web", "standalone", "serv let runtimeArtifactsReady = false +const SANITIZED_PROVIDER_ENV_KEYS = [ + "ANTHROPIC_OAUTH_TOKEN", + "ANTHROPIC_API_KEY", + "OPENAI_API_KEY", + "AZURE_OPENAI_API_KEY", + "GEMINI_API_KEY", + "GROQ_API_KEY", + "CEREBRAS_API_KEY", + "XAI_API_KEY", + "OPENROUTER_API_KEY", + "AI_GATEWAY_API_KEY", + "ZAI_API_KEY", + "MISTRAL_API_KEY", + "MINIMAX_API_KEY", + "MINIMAX_CN_API_KEY", + "HF_TOKEN", + "OPENCODE_API_KEY", + "KIMI_API_KEY", + "ALIBABA_API_KEY", + "COPILOT_GITHUB_TOKEN", + "GH_TOKEN", + "GITHUB_TOKEN", + "GOOGLE_APPLICATION_CREDENTIALS", + "GOOGLE_CLOUD_PROJECT", + "GCLOUD_PROJECT", + "GOOGLE_CLOUD_LOCATION", + "AWS_PROFILE", + "AWS_ACCESS_KEY_ID", + "AWS_SECRET_ACCESS_KEY", + "AWS_BEARER_TOKEN_BEDROCK", + "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI", + "AWS_CONTAINER_CREDENTIALS_FULL_URI", + "AWS_WEB_IDENTITY_TOKEN_FILE", +] as const + +function buildSanitizedRuntimeEnv(overrides?: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = { ...process.env } + for (const key of SANITIZED_PROVIDER_ENV_KEYS) { + env[key] = "" + } + return { + ...env, + ...overrides, + } +} + type RuntimeEndpoint = "boot" | "events" type RuntimeRequestDiagnostic = { @@ -147,12 +193,11 @@ export async function launchPackagedWebHost(options: { { cwd: options.launchCwd, env: { - ...process.env, + ...buildSanitizedRuntimeEnv(options.env), HOME: options.tempHome, PATH: `${fakeBin}:${process.env.PATH || ""}`, CI: "1", FORCE_COLOR: "0", - ...options.env, }, stdio: ["ignore", "pipe", "pipe"], }, diff --git a/src/tests/integration/web-mode-windows-hide.test.ts b/src/tests/integration/web-mode-windows-hide.test.ts new file mode 100644 index 000000000..c1b2902f5 --- /dev/null +++ b/src/tests/integration/web-mode-windows-hide.test.ts @@ -0,0 +1,125 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +const webMode = await import("../../web-mode.ts"); + +// --------------------------------------------------------------------------- +// #2628 — On Windows, child processes spawned by web-mode must set +// `windowsHide: true` to prevent console windows from flashing on screen. +// --------------------------------------------------------------------------- + +test("launchWebMode passes windowsHide: true in spawn options", async (t) => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-web-winhide-")); + const standaloneRoot = join(tmp, "dist", "web", "standalone"); + const serverPath = join(standaloneRoot, "server.js"); + mkdirSync(standaloneRoot, { recursive: true }); + writeFileSync(serverPath, 'console.log("stub")\n'); + + const pidFilePath = join(tmp, "web-server.pid"); + const registryPath = join(tmp, "web-instances.json"); + + let capturedOptions: Record | undefined; + + t.after(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + const status = await webMode.launchWebMode( + { + cwd: "/tmp/winhide-project", + projectSessionsDir: "/tmp/.gsd/sessions/winhide", + agentDir: "/tmp/.gsd/agent", + packageRoot: tmp, + }, + { + initResources: () => {}, + resolvePort: async () => 46000, + execPath: "/custom/node", + env: { TEST_ENV: "1" }, + spawn: (_command, _args, options) => { + capturedOptions = options as Record; + return { + pid: 70001, + once: () => undefined, + unref: () => {}, + } as any; + }, + waitForBootReady: async () => undefined, + openBrowser: () => {}, + pidFilePath, + writePidFile: webMode.writePidFile, + registryPath, + stderr: { write: () => true }, + }, + ); + + assert.equal(status.ok, true, "launch should succeed"); + assert.ok(capturedOptions, "spawn must have been called"); + assert.equal( + capturedOptions!.windowsHide, + true, + "spawn options must include windowsHide: true to prevent console window flashing on Windows (#2628)", + ); +}); + +test("launchWebMode source-dev host also passes windowsHide: true", async (t) => { + const tmp = mkdtempSync(join(tmpdir(), "gsd-web-winhide-src-")); + const webRoot = join(tmp, "web"); + mkdirSync(webRoot, { recursive: true }); + writeFileSync(join(webRoot, "package.json"), '{"name":"web"}\n'); + + const pidFilePath = join(tmp, "web-server.pid"); + const registryPath = join(tmp, "web-instances.json"); + + let capturedOptions: Record | undefined; + + t.after(() => { + rmSync(tmp, { recursive: true, force: true }); + }); + + const status = await webMode.launchWebMode( + { + cwd: "/tmp/winhide-src-project", + projectSessionsDir: "/tmp/.gsd/sessions/winhide-src", + agentDir: "/tmp/.gsd/agent", + packageRoot: tmp, + }, + { + initResources: () => {}, + resolvePort: async () => 46001, + execPath: "/custom/node", + env: { TEST_ENV: "1" }, + platform: "win32", + spawn: (_command, _args, options) => { + capturedOptions = options as Record; + return { + pid: 70002, + once: () => undefined, + unref: () => {}, + } as any; + }, + waitForBootReady: async () => undefined, + openBrowser: () => {}, + pidFilePath, + writePidFile: webMode.writePidFile, + registryPath, + stderr: { write: () => true }, + }, + ); + + assert.equal(status.ok, true, "launch should succeed"); + assert.ok(capturedOptions, "spawn must have been called"); + assert.equal( + capturedOptions!.windowsHide, + true, + "source-dev spawn must also include windowsHide: true (#2628)", + ); + assert.equal( + capturedOptions!.shell, + true, + "source-dev spawn must include shell: true when launching npm.cmd on Windows", + ); +}); diff --git a/src/tests/integration/web-onboarding-contract.test.ts b/src/tests/integration/web-onboarding-contract.test.ts index 3ed833368..016c7ae1e 100644 --- a/src/tests/integration/web-onboarding-contract.test.ts +++ b/src/tests/integration/web-onboarding-contract.test.ts @@ -348,7 +348,7 @@ test("boot and onboarding routes expose locked required state plus explicitly sk ]); const anthropicProvider = bootPayload.onboarding.required.providers.find((provider: any) => provider.id === "anthropic"); assert.equal(anthropicProvider.supports.apiKey, true); - assert.equal(anthropicProvider.supports.oauthAvailable, true); + assert.equal(anthropicProvider.supports.oauthAvailable, false); const onboardingResponse = await onboardingRoute.GET(projectRequest(fixture.projectCwd, "/api/onboarding")); assert.equal(onboardingResponse.status, 200); @@ -408,7 +408,7 @@ test("failed API-key validation stays locked, redacts the error, and is reflecte getEnvApiKey: noEnvApiKey, validateApiKey: async () => ({ ok: false, - message: "OpenAI rejected sk-test-secret-123456 because Bearer sk-test-secret-123456 is invalid", + message: "OpenAI rejected the provided key because Bearer invalid-demo-key is invalid", }), }); @@ -425,7 +425,7 @@ test("failed API-key validation stays locked, redacts the error, and is reflecte body: JSON.stringify({ action: "save_api_key", providerId: "openai", - apiKey: "sk-test-secret-123456", + apiKey: "invalid-demo-key", }), }), ); @@ -440,7 +440,7 @@ test("failed API-key validation stays locked, redacts the error, and is reflecte assert.equal(validationPayload.onboarding.lockReason, "required_setup"); assert.equal(validationPayload.onboarding.bridgeAuthRefresh.phase, "idle"); assert.match(validationPayload.onboarding.lastValidation.message, /OpenAI rejected/i); - assert.doesNotMatch(validationPayload.onboarding.lastValidation.message, /sk-test-secret-123456/); + assert.doesNotMatch(validationPayload.onboarding.lastValidation.message, /invalid-demo-key/); assert.equal(authStorage.hasAuth("openai"), false); const bootResponse = await bootRoute.GET(projectRequest(fixture.projectCwd, "/api/boot")); @@ -448,7 +448,7 @@ test("failed API-key validation stays locked, redacts the error, and is reflecte const bootPayload = (await bootResponse.json()) as any; assert.equal(bootPayload.onboarding.locked, true); assert.equal(bootPayload.onboarding.lastValidation.status, "failed"); - assert.doesNotMatch(bootPayload.onboarding.lastValidation.message, /sk-test-secret-123456/); + assert.doesNotMatch(bootPayload.onboarding.lastValidation.message, /invalid-demo-key/); }); test("direct prompt commands cannot bypass onboarding while required setup is still locked", async (t) => { diff --git a/src/tests/integration/web-project-tab-preservation.test.ts b/src/tests/integration/web-project-tab-preservation.test.ts new file mode 100644 index 000000000..4b7b5d2d1 --- /dev/null +++ b/src/tests/integration/web-project-tab-preservation.test.ts @@ -0,0 +1,243 @@ +import test, { describe } from "node:test"; +import assert from "node:assert/strict"; + +// --------------------------------------------------------------------------- +// Test: project switching preserves the active tab (view) instead of +// resetting to dashboard. +// +// Bug #2711: Switching projects always returns to dashboard. +// +// Root cause: handleSelectProject in ProjectsPanel dispatched +// gsd:navigate-view with { view: "dashboard" } on every switch. +// Additionally, the viewRestored flag in WorkspaceChrome was never +// reset when the project changed, so the per-project sessionStorage +// restore could not fire for the new project. +// +// These tests validate the corrected logic in isolation, without needing +// a full React DOM. +// --------------------------------------------------------------------------- + +// ── Simulated sessionStorage (mirrors browser sessionStorage API) ──────── + +class MockSessionStorage { + private store = new Map(); + + getItem(key: string): string | null { + return this.store.get(key) ?? null; + } + + setItem(key: string, value: string): void { + this.store.set(key, value); + } + + removeItem(key: string): void { + this.store.delete(key); + } + + clear(): void { + this.store.clear(); + } +} + +// ── Mirrors the KNOWN_VIEWS set and viewStorageKey from app-shell.tsx ───── + +const KNOWN_VIEWS = new Set([ + "dashboard", + "power", + "chat", + "roadmap", + "files", + "activity", + "visualize", +]); + +function viewStorageKey(projectCwd: string): string { + return `gsd-active-view:${projectCwd}`; +} + +// ── Simulated WorkspaceChrome view-restore logic ───────────────────────── +// This mirrors the useEffect in WorkspaceChrome that restores the persisted +// view when projectPath changes — with the fix applied. + +interface ChromeState { + activeView: string; + viewRestored: boolean; + projectPath: string | null; +} + +/** + * Simulates the view-restore effect. + * In the fixed code, viewRestored resets to false when projectPath changes, + * allowing the stored view to be read for the new project. + */ +function simulateViewRestoreEffect( + state: ChromeState, + storage: MockSessionStorage, +): ChromeState { + // The fix: if projectPath changed, reset viewRestored + // (In React this is a separate useEffect that depends on [projectPath]) + if (!state.viewRestored && state.projectPath) { + const stored = storage.getItem(viewStorageKey(state.projectPath)); + if (stored && KNOWN_VIEWS.has(stored)) { + return { ...state, activeView: stored, viewRestored: true }; + } + return { ...state, viewRestored: true }; + } + return state; +} + +/** + * Simulates switching to a new project path. + * The fix resets viewRestored so the restore effect can fire for the new project. + */ +function simulateProjectSwitch( + state: ChromeState, + newProjectPath: string, +): ChromeState { + return { + ...state, + projectPath: newProjectPath, + viewRestored: false, // <-- THE FIX: reset so restore runs for new project + }; +} + +// ── Simulated handleSelectProject (pre-fix vs post-fix) ────────────────── + +/** Pre-fix: always navigates to dashboard on project switch */ +function handleSelectProjectPreFix( + _state: ChromeState, + _projectPath: string, +): string { + // Bug: always forces dashboard + return "dashboard"; +} + +/** Post-fix: does NOT override the active view */ +function handleSelectProjectPostFix( + state: ChromeState, + _projectPath: string, +): string { + // Fix: preserve whatever view is active (restore logic handles per-project view) + return state.activeView; +} + +// --------------------------------------------------------------------------- +// Tests +// --------------------------------------------------------------------------- + +describe("project switch tab preservation (#2711)", () => { + test("BUG: pre-fix handleSelectProject always resets to dashboard", () => { + const state: ChromeState = { + activeView: "roadmap", + viewRestored: true, + projectPath: "/projects/alpha", + }; + + const viewAfterSwitch = handleSelectProjectPreFix(state, "/projects/beta"); + // This demonstrates the bug: user was on "roadmap" but got sent to "dashboard" + assert.equal(viewAfterSwitch, "dashboard"); + }); + + test("FIX: post-fix handleSelectProject preserves current view", () => { + const state: ChromeState = { + activeView: "roadmap", + viewRestored: true, + projectPath: "/projects/alpha", + }; + + const viewAfterSwitch = handleSelectProjectPostFix(state, "/projects/beta"); + assert.equal(viewAfterSwitch, "roadmap", "Should preserve the current tab"); + }); + + test("FIX: viewRestored resets on project switch, enabling per-project view restore", () => { + const storage = new MockSessionStorage(); + storage.setItem(viewStorageKey("/projects/alpha"), "files"); + storage.setItem(viewStorageKey("/projects/beta"), "activity"); + + // Start on project alpha, viewing files + let state: ChromeState = { + activeView: "dashboard", + viewRestored: false, + projectPath: "/projects/alpha", + }; + + // Initial restore for alpha + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "files"); + assert.equal(state.viewRestored, true); + + // Switch to project beta + state = simulateProjectSwitch(state, "/projects/beta"); + assert.equal(state.viewRestored, false, "viewRestored should reset on project switch"); + + // Restore effect fires for beta + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "activity", "Should restore beta's persisted view"); + }); + + test("FIX: switching to project with no stored view keeps current view", () => { + const storage = new MockSessionStorage(); + // Only alpha has a stored view + storage.setItem(viewStorageKey("/projects/alpha"), "roadmap"); + + let state: ChromeState = { + activeView: "roadmap", + viewRestored: true, + projectPath: "/projects/alpha", + }; + + // Switch to gamma (no stored view) + state = simulateProjectSwitch(state, "/projects/gamma"); + state = simulateViewRestoreEffect(state, storage); + + // Should keep the current view since gamma has no stored preference + assert.equal(state.activeView, "roadmap", "Should keep current view when new project has no stored view"); + }); + + test("FIX: stored view for invalid view name is ignored", () => { + const storage = new MockSessionStorage(); + storage.setItem(viewStorageKey("/projects/alpha"), "nonexistent-view"); + + let state: ChromeState = { + activeView: "power", + viewRestored: false, + projectPath: "/projects/alpha", + }; + + state = simulateViewRestoreEffect(state, storage); + // Invalid stored view should be ignored, keeping current view + assert.equal(state.activeView, "power"); + }); + + test("FIX: rapid project switches each get a fresh restore", () => { + const storage = new MockSessionStorage(); + storage.setItem(viewStorageKey("/projects/a"), "chat"); + storage.setItem(viewStorageKey("/projects/b"), "visualize"); + storage.setItem(viewStorageKey("/projects/c"), "files"); + + let state: ChromeState = { + activeView: "dashboard", + viewRestored: false, + projectPath: "/projects/a", + }; + + // Restore for A + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "chat"); + + // Switch to B + state = simulateProjectSwitch(state, "/projects/b"); + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "visualize"); + + // Switch to C + state = simulateProjectSwitch(state, "/projects/c"); + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "files"); + + // Switch back to A + state = simulateProjectSwitch(state, "/projects/a"); + state = simulateViewRestoreEffect(state, storage); + assert.equal(state.activeView, "chat", "Should restore A's view again after switching away and back"); + }); +}); diff --git a/src/tests/integration/web-state-surfaces-contract.test.ts b/src/tests/integration/web-state-surfaces-contract.test.ts index 58d9b89e9..120da7d25 100644 --- a/src/tests/integration/web-state-surfaces-contract.test.ts +++ b/src/tests/integration/web-state-surfaces-contract.test.ts @@ -487,6 +487,32 @@ test("terminal consumes activeToolExecution from store", () => { ); }); +test("chat tool blocks normalize Claude Code tool names before choosing built-in render treatment", () => { + const chatPath = resolve(import.meta.dirname, "../../../web/components/gsd/chat-mode.tsx"); + const source = readFileSync(chatPath, "utf-8"); + + assert.match( + source, + /const normalizedToolName = typeof tool\.name === "string" \? tool\.name\.toLowerCase\(\) : ""/, + "chat-mode.tsx must normalize Claude Code tool names before matching built-in tool render branches", + ); + assert.match( + source, + /normalizedToolName === "bash"/, + "chat-mode.tsx must use normalized tool names for bash command rendering", + ); + assert.match( + source, + /const autoExpandedRef = useRef\(false\)/, + "chat-mode.tsx must track one-time auto-expansion for completed tool output blocks", + ); + assert.match( + source, + /const hasVisibleResult = Boolean\(diff \|\| resultText\.trim\(\) \|\| isError\)/, + "chat-mode.tsx must auto-expand tool blocks when visible result content arrives", + ); +}); + test("live browser panels consume live selectors and expose inspectable freshness markers", () => { const contractPath = resolve(import.meta.dirname, "../../../web/lib/command-surface-contract.ts") const storePath = resolve(import.meta.dirname, "../../../web/lib/gsd-workspace-store.tsx") diff --git a/src/tests/integration/web-terminal-preservation.test.ts b/src/tests/integration/web-terminal-preservation.test.ts new file mode 100644 index 000000000..fb0cd2d1a --- /dev/null +++ b/src/tests/integration/web-terminal-preservation.test.ts @@ -0,0 +1,264 @@ +import test from "node:test"; +import assert from "node:assert/strict"; + +// --------------------------------------------------------------------------- +// Constants mirrored from the shutdown-gate and app-shell +// --------------------------------------------------------------------------- +const SHUTDOWN_DELAY_MS = 3_000; + +// --------------------------------------------------------------------------- +// Test 1: pagehide handler must NOT fire shutdown beacon on tab switches +// --------------------------------------------------------------------------- +// The bug: `pagehide` fires both on actual page unload AND on mobile/Safari +// tab switches (where event.persisted === true because the page enters bfcache). +// The current handler does not check event.persisted, so it fires shutdown +// beacons on tab switches — killing the server and all PTY sessions. + +/** + * Mirrors the pagehide handler logic from app-shell.tsx's + * ProjectAwareWorkspace component. The BUGGY version sends a shutdown + * beacon unconditionally. + */ +function buggyPageHideHandler(_event: { persisted: boolean }): boolean { + // Current code (buggy): always sends beacon regardless of event.persisted + return true; // true = beacon was sent +} + +/** + * Fixed version: only send shutdown beacon when the page is truly being + * unloaded (event.persisted === false). When persisted is true the page + * is being put into bfcache (tab switch, app backgrounding) and the + * server should stay alive. + */ +function fixedPageHideHandler(event: { persisted: boolean }): boolean { + if (event.persisted) { + // Page is entering bfcache (tab switch) — do NOT shut down + return false; + } + return true; // true = beacon was sent +} + +test("pagehide: buggy handler sends shutdown beacon on tab switch (persisted=true)", () => { + // This test documents the bug — the buggy handler fires on tab switches + const beaconSent = buggyPageHideHandler({ persisted: true }); + assert.equal(beaconSent, true, "Buggy handler sends beacon even on tab switch"); +}); + +test("pagehide: fixed handler skips shutdown beacon on tab switch (persisted=true)", () => { + const beaconSent = fixedPageHideHandler({ persisted: true }); + assert.equal(beaconSent, false, "Fixed handler must NOT send beacon on tab switch"); +}); + +test("pagehide: fixed handler still sends shutdown beacon on real page unload (persisted=false)", () => { + const beaconSent = fixedPageHideHandler({ persisted: false }); + assert.equal(beaconSent, true, "Fixed handler must send beacon on real unload"); +}); + +// --------------------------------------------------------------------------- +// Test 2: Project switching must NOT destroy PTY sessions +// --------------------------------------------------------------------------- +// The bug: ProjectStoreManager.switchProject() changes the active store, +// which causes React to unmount the entire WorkspaceChrome tree (including +// ShellTerminal). The PTY processes survive server-side, but the client +// loses all xterm state and SSE connections. When the user switches back, +// a NEW terminal is created instead of reconnecting to the existing one. + +/** + * Mirrors the session-id generation logic used by ShellTerminal. + * The BUGGY version generates a project-agnostic session ID, so switching + * projects and switching back creates a collision or a fresh session. + * + * The FIXED version namespaces session IDs by project so switching back + * reconnects to the same server-side PTY session via its stable ID. + */ + +interface TerminalSessionTracker { + /** Active PTY session IDs on the server (survives client unmount) */ + serverSessions: Map; + /** Client-side session IDs (destroyed on unmount) */ + clientSessions: Set; +} + +function createTracker(): TerminalSessionTracker { + return { + serverSessions: new Map(), + clientSessions: new Set(), + }; +} + +/** + * Simulates what happens when ShellTerminal mounts for a project. + * The BUGGY version uses a plain default ID with no project namespace. + */ +function buggyMountTerminal(tracker: TerminalSessionTracker, _projectCwd: string): string { + const sessionId = "default"; // No project namespace — always the same ID + tracker.serverSessions.set(sessionId, { alive: true, projectCwd: _projectCwd }); + tracker.clientSessions.add(sessionId); + return sessionId; +} + +/** + * Simulates what happens when ShellTerminal unmounts (project switch). + * Client-side state is destroyed but server session stays alive. + */ +function unmountTerminal(tracker: TerminalSessionTracker, sessionId: string): void { + tracker.clientSessions.delete(sessionId); + // Server session stays alive — this is the correct behavior +} + +/** + * FIXED mount: uses a project-scoped session ID so switching back to + * a project reconnects to the same server-side PTY. + */ +function fixedMountTerminal(tracker: TerminalSessionTracker, projectCwd: string): string { + const sessionId = `shell:${projectCwd}:default`; + // getOrCreateSession on the server: if alive, returns existing; if dead, creates new + if (!tracker.serverSessions.has(sessionId) || !tracker.serverSessions.get(sessionId)!.alive) { + tracker.serverSessions.set(sessionId, { alive: true, projectCwd }); + } + tracker.clientSessions.add(sessionId); + return sessionId; +} + +test("project switch: buggy flow reuses same session ID for different projects", () => { + const tracker = createTracker(); + + // Mount terminal for project A + const sessionA = buggyMountTerminal(tracker, "/projects/alpha"); + assert.equal(sessionA, "default"); + assert.equal(tracker.serverSessions.get("default")?.projectCwd, "/projects/alpha"); + + // Switch to project B — unmount A, mount B + unmountTerminal(tracker, sessionA); + const sessionB = buggyMountTerminal(tracker, "/projects/beta"); + + // Bug: same session ID, but now points to a different project + assert.equal(sessionB, "default"); + assert.equal( + tracker.serverSessions.get("default")?.projectCwd, + "/projects/beta", + "Buggy: server session is overwritten with new project", + ); +}); + +test("project switch: fixed flow preserves per-project session identity", () => { + const tracker = createTracker(); + + // Mount terminal for project A + const sessionA = fixedMountTerminal(tracker, "/projects/alpha"); + assert.ok(sessionA.includes("/projects/alpha"), "Session ID includes project path"); + + // Switch to project B — unmount A, mount B + unmountTerminal(tracker, sessionA); + const sessionB = fixedMountTerminal(tracker, "/projects/beta"); + + // Session IDs are different — no collision + assert.notEqual(sessionA, sessionB, "Different projects get different session IDs"); + + // Both server sessions exist independently + assert.equal(tracker.serverSessions.get(sessionA)?.alive, true); + assert.equal(tracker.serverSessions.get(sessionB)?.alive, true); + + // Switch back to project A — should reconnect to same session + unmountTerminal(tracker, sessionB); + const sessionA2 = fixedMountTerminal(tracker, "/projects/alpha"); + assert.equal(sessionA2, sessionA, "Switching back reconnects to the same session ID"); + assert.equal(tracker.serverSessions.get(sessionA)?.alive, true, "Original server session is still alive"); +}); + +// --------------------------------------------------------------------------- +// Test 3: Shutdown gate must differentiate tab-switch from real unload +// --------------------------------------------------------------------------- +// The shutdown gate has a 3s delay to allow page refreshes to cancel the +// shutdown. But on mobile tab switches that fire pagehide, the 3s timer +// starts — and if the user doesn't switch back within 3s, the server dies. +// The fix is to never start the timer on persisted pagehide events. + +interface ShutdownGateState { + timerScheduled: boolean; + shutdownExecuted: boolean; +} + +function createShutdownGate(): ShutdownGateState { + return { timerScheduled: false, shutdownExecuted: false }; +} + +function scheduleShutdownIfAllowed(gate: ShutdownGateState, event: { persisted: boolean }): void { + // Fixed: only schedule shutdown when the page is truly unloading + if (event.persisted) return; + gate.timerScheduled = true; +} + +function cancelShutdown(gate: ShutdownGateState): void { + gate.timerScheduled = false; +} + +test("shutdown gate: tab switch (persisted=true) must not schedule shutdown", () => { + const gate = createShutdownGate(); + scheduleShutdownIfAllowed(gate, { persisted: true }); + assert.equal(gate.timerScheduled, false, "No shutdown timer on tab switch"); +}); + +test("shutdown gate: real page unload (persisted=false) must schedule shutdown", () => { + const gate = createShutdownGate(); + scheduleShutdownIfAllowed(gate, { persisted: false }); + assert.equal(gate.timerScheduled, true, "Shutdown timer on real unload"); +}); + +test("shutdown gate: scheduled shutdown can still be cancelled by page refresh", () => { + const gate = createShutdownGate(); + scheduleShutdownIfAllowed(gate, { persisted: false }); + assert.equal(gate.timerScheduled, true); + cancelShutdown(gate); + assert.equal(gate.timerScheduled, false, "Timer cancelled on refresh"); +}); + +// --------------------------------------------------------------------------- +// Test 4: Shell terminal session ID must be project-scoped +// --------------------------------------------------------------------------- + +/** + * Mirrors the session ID derivation that ShellTerminal should use. + * The default session ID (when no sessionPrefix is given) must incorporate + * the project path so that different projects get different PTY sessions. + */ +function deriveSessionId( + projectCwd: string | undefined, + sessionPrefix?: string, + command?: string, +): string { + const base = sessionPrefix ?? (command ? "gsd-default" : "default"); + if (!projectCwd) return base; + // Stable hash-like key from the project path — keeps IDs short but unique + return `${base}:${projectCwd}`; +} + +test("session ID derivation: different projects produce different IDs", () => { + const idA = deriveSessionId("/projects/alpha"); + const idB = deriveSessionId("/projects/beta"); + assert.notEqual(idA, idB); +}); + +test("session ID derivation: same project produces stable ID", () => { + const id1 = deriveSessionId("/projects/alpha"); + const id2 = deriveSessionId("/projects/alpha"); + assert.equal(id1, id2); +}); + +test("session ID derivation: explicit sessionPrefix is preserved with project scope", () => { + const id = deriveSessionId("/projects/alpha", "my-prefix"); + assert.ok(id.includes("my-prefix"), "Prefix included"); + assert.ok(id.includes("/projects/alpha"), "Project path included"); +}); + +test("session ID derivation: command sessions are also project-scoped", () => { + const idA = deriveSessionId("/projects/alpha", undefined, "gsd"); + const idB = deriveSessionId("/projects/beta", undefined, "gsd"); + assert.notEqual(idA, idB); + assert.ok(idA.includes("gsd-default"), "Uses gsd-default base for command sessions"); +}); + +test("session ID derivation: no projectCwd falls back to plain base ID", () => { + const id = deriveSessionId(undefined); + assert.equal(id, "default"); +}); diff --git a/src/tests/mcp-client-oauth.test.ts b/src/tests/mcp-client-oauth.test.ts new file mode 100644 index 000000000..568e28eab --- /dev/null +++ b/src/tests/mcp-client-oauth.test.ts @@ -0,0 +1,219 @@ +/** + * Tests for MCP client OAuth auth provider support on HTTP transport. + * + * Verifies that: + * 1. HTTP server configs with `headers` pass them to the transport via requestInit + * 2. HTTP server configs with `oauth` config construct an OAuthClientProvider + * 3. Servers without auth still connect without an auth provider + * 4. Environment variable references in headers are resolved + * + * Reproduces issue #2160 — MCP HTTP transport lacks OAuth auth provider, + * causing 401 errors when connecting to remote MCP servers (Sentry, Linear, etc.) + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import { buildHttpTransportOpts } from "../resources/extensions/mcp-client/auth.ts"; + +// ── Transport construction (SDK sanity checks) ─────────────────────────────── + +test("HTTP transport without auth config creates transport with no authProvider", async () => { + const { StreamableHTTPClientTransport } = await import( + "@modelcontextprotocol/sdk/client/streamableHttp.js" + ); + + const transport = new StreamableHTTPClientTransport( + new URL("https://example.com/mcp"), + ); + assert.ok(transport, "Transport should be created without auth"); +}); + +test("HTTP transport with authProvider creates transport that can authenticate", async () => { + const { StreamableHTTPClientTransport } = await import( + "@modelcontextprotocol/sdk/client/streamableHttp.js" + ); + + // Minimal OAuthClientProvider mock + const mockAuthProvider = { + get redirectUrl() { return "http://localhost:3000/callback"; }, + get clientMetadata() { + return { + redirect_uris: ["http://localhost:3000/callback"], + client_name: "gsd-test", + }; + }, + clientInformation: () => undefined, + tokens: () => ({ access_token: "test-token", token_type: "Bearer" }), + saveTokens: () => {}, + redirectToAuthorization: () => {}, + saveCodeVerifier: () => {}, + codeVerifier: () => "verifier", + }; + + const transport = new StreamableHTTPClientTransport( + new URL("https://example.com/mcp"), + { authProvider: mockAuthProvider }, + ); + assert.ok(transport, "Transport should accept authProvider option"); +}); + +test("HTTP transport with requestInit headers passes them to requests", async () => { + const { StreamableHTTPClientTransport } = await import( + "@modelcontextprotocol/sdk/client/streamableHttp.js" + ); + + const transport = new StreamableHTTPClientTransport( + new URL("https://example.com/mcp"), + { + requestInit: { + headers: { + Authorization: "Bearer my-token", + }, + }, + }, + ); + assert.ok(transport, "Transport should accept requestInit with headers"); +}); + +// ── buildHttpTransportOpts ────────────────────────────────────────────────── + +test("buildHttpTransportOpts returns empty opts for config without auth", () => { + const opts = buildHttpTransportOpts({}); + assert.deepEqual(opts, {}, "No auth config should produce empty opts"); +}); + +test("buildHttpTransportOpts returns requestInit.headers for config with headers", () => { + const opts = buildHttpTransportOpts({ + headers: { Authorization: "Bearer tok_123" }, + }); + + assert.ok(opts.requestInit, "Should produce requestInit"); + const headers = opts.requestInit!.headers as Record; + assert.equal(headers.Authorization, "Bearer tok_123"); +}); + +test("buildHttpTransportOpts resolves env vars in header values", () => { + process.env.__TEST_MCP_TOKEN = "secret-456"; + + const opts = buildHttpTransportOpts({ + headers: { Authorization: "Bearer ${__TEST_MCP_TOKEN}" }, + }); + + const headers = opts.requestInit!.headers as Record; + assert.equal( + headers.Authorization, + "Bearer secret-456", + "Env vars in headers should be resolved", + ); + + delete process.env.__TEST_MCP_TOKEN; +}); + +test("buildHttpTransportOpts resolves multiple env vars in a single header", () => { + process.env.__TEST_MCP_USER = "alice"; + process.env.__TEST_MCP_PASS = "s3cret"; + + const opts = buildHttpTransportOpts({ + headers: { "X-Custom": "${__TEST_MCP_USER}:${__TEST_MCP_PASS}" }, + }); + + const headers = opts.requestInit!.headers as Record; + assert.equal(headers["X-Custom"], "alice:s3cret"); + + delete process.env.__TEST_MCP_USER; + delete process.env.__TEST_MCP_PASS; +}); + +test("buildHttpTransportOpts replaces missing env vars with empty string", () => { + delete process.env.__NONEXISTENT_VAR; + + const opts = buildHttpTransportOpts({ + headers: { Authorization: "Bearer ${__NONEXISTENT_VAR}" }, + }); + + const headers = opts.requestInit!.headers as Record; + assert.equal(headers.Authorization, "Bearer "); +}); + +test("buildHttpTransportOpts creates OAuthClientProvider for oauth config", () => { + const opts = buildHttpTransportOpts({ + oauth: { + clientId: "my-client", + scopes: ["read"], + }, + }); + + assert.ok(opts.authProvider, "OAuth config should produce an authProvider"); + assert.ok(opts.authProvider.clientMetadata, "authProvider should have clientMetadata"); + assert.equal(typeof opts.authProvider.tokens, "function", "authProvider.tokens should be a function"); + assert.equal(typeof opts.authProvider.saveTokens, "function", "authProvider.saveTokens should be a function"); + assert.equal(typeof opts.authProvider.redirectToAuthorization, "function"); + assert.equal(typeof opts.authProvider.codeVerifier, "function"); + assert.equal(typeof opts.authProvider.saveCodeVerifier, "function"); +}); + +test("OAuth provider clientInformation includes clientId", () => { + const opts = buildHttpTransportOpts({ + oauth: { + clientId: "test-id-123", + clientSecret: "test-secret", + }, + }); + + const info = opts.authProvider!.clientInformation(); + assert.ok(info, "clientInformation should return data"); + assert.equal(info!.client_id, "test-id-123"); + assert.equal((info as any).client_secret, "test-secret"); +}); + +test("OAuth provider clientMetadata includes scopes", () => { + const opts = buildHttpTransportOpts({ + oauth: { + clientId: "scoped-client", + scopes: ["issues:read", "issues:write"], + }, + }); + + const meta = opts.authProvider!.clientMetadata; + assert.ok(meta, "clientMetadata should exist"); + assert.equal((meta as any).scope, "issues:read issues:write"); +}); + +test("OAuth provider stores and retrieves tokens", () => { + const opts = buildHttpTransportOpts({ + oauth: { clientId: "token-test" }, + }); + + const provider = opts.authProvider!; + + // Initially no tokens + assert.equal(provider.tokens(), undefined); + + // Save tokens + const tokens = { access_token: "at_123", token_type: "Bearer", refresh_token: "rt_456" }; + provider.saveTokens(tokens); + + // Retrieve tokens + const stored = provider.tokens(); + assert.ok(stored); + assert.equal(stored!.access_token, "at_123"); +}); + +test("OAuth provider stores and retrieves code verifier", () => { + const opts = buildHttpTransportOpts({ + oauth: { clientId: "pkce-test" }, + }); + + const provider = opts.authProvider!; + provider.saveCodeVerifier("my-verifier-string"); + assert.equal(provider.codeVerifier(), "my-verifier-string"); +}); + +test("OAuth takes precedence over headers when both are provided", () => { + const opts = buildHttpTransportOpts({ + headers: { Authorization: "Bearer static-token" }, + oauth: { clientId: "oauth-client" }, + }); + + assert.ok(opts.authProvider, "OAuth should be used when both are provided"); + assert.ok(!opts.requestInit, "requestInit should not be set when OAuth is active"); +}); diff --git a/src/tests/mcp-createRequire.test.ts b/src/tests/mcp-createRequire.test.ts new file mode 100644 index 000000000..d16ebacd6 --- /dev/null +++ b/src/tests/mcp-createRequire.test.ts @@ -0,0 +1,35 @@ +/** + * Regression test for #3914 — MCP server uses explicit .js SDK subpaths. + * + * Extensionless wildcard exports for `server/stdio` and `types` do not resolve + * reliably across current Node / SDK combinations. The runtime import strings + * must include `.js`. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync(join(__dirname, '..', 'mcp-server.ts'), 'utf-8'); + +describe('MCP server SDK subpath imports (#3914)', () => { + test('server/stdio import uses explicit .js subpath', () => { + assert.match(source, /await import\(`\$\{MCP_PKG\}\/server\/stdio\.js`\)/, + 'server/stdio import should include the .js suffix'); + }); + + test('types import uses explicit .js subpath', () => { + assert.match(source, /await import\(`\$\{MCP_PKG\}\/types\.js`\)/, + 'types import should include the .js suffix'); + }); + + test('legacy createRequire-based resolution is gone', () => { + assert.doesNotMatch(source, /createRequire|_require\.resolve/, + 'legacy createRequire-based subpath resolution should not remain'); + }); +}); diff --git a/src/tests/mcp-server.test.ts b/src/tests/mcp-server.test.ts index 9581809dd..8a6a672f9 100644 --- a/src/tests/mcp-server.test.ts +++ b/src/tests/mcp-server.test.ts @@ -30,25 +30,11 @@ test('startMcpServer accepts the correct argument shape', async () => { assert.strictEqual(startMcpServer.length, 1, 'startMcpServer should accept one argument') }) -test('startMcpServer can be called with mock tools', async () => { - const { startMcpServer } = await import(distUrl('mcp-server.js')) +test('compiled MCP runtime dependencies resolve with explicit .js subpaths', async () => { + const stdioMod = await import('@modelcontextprotocol/sdk/server/stdio.js') + const typesMod = await import('@modelcontextprotocol/sdk/types.js') - // Create a mock tool matching the McpToolDef interface - const mockTool = { - name: 'test_tool', - description: 'A test tool', - parameters: { type: 'object', properties: {} }, - execute: async () => ({ - content: [{ type: 'text', text: 'hello' }], - }), - } - - // Verify the function can be called with the correct signature - // without throwing during argument validation. It will attempt to - // connect to stdin/stdout as an MCP transport, which won't work in - // a test environment, but the Server instance is created successfully. - assert.doesNotThrow(() => { - void startMcpServer({ tools: [mockTool], version: '0.0.0-test' }) - .catch(() => { /* expected: no MCP client on stdin */ }) - }) + assert.strictEqual(typeof stdioMod.StdioServerTransport, 'function') + assert.ok(typesMod.ListToolsRequestSchema, 'ListToolsRequestSchema should be exported') + assert.ok(typesMod.CallToolRequestSchema, 'CallToolRequestSchema should be exported') }) diff --git a/src/tests/model-registry-custom-provider.test.ts b/src/tests/model-registry-custom-provider.test.ts new file mode 100644 index 000000000..323b8776b --- /dev/null +++ b/src/tests/model-registry-custom-provider.test.ts @@ -0,0 +1,25 @@ +/** + * Regression test for #3531: models.json custom providers must be registered + * in registeredProviders so isProviderRequestReady() returns true. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +test("parseModels registers custom providers in registeredProviders (#3531)", () => { + const src = readFileSync( + join(__dirname, "..", "..", "packages", "pi-coding-agent", "src", "core", "model-registry.ts"), + "utf-8", + ); + // The fix adds registeredProviders.set() inside parseModels + const parseModelsBlock = src.slice(src.indexOf("private parseModels")); + assert.ok( + parseModelsBlock.includes("registeredProviders.set") || + parseModelsBlock.includes("this.registeredProviders.set"), + "parseModels must register custom providers in registeredProviders", + ); +}); diff --git a/src/tests/package-mcp-server-elicitation.test.ts b/src/tests/package-mcp-server-elicitation.test.ts new file mode 100644 index 000000000..a746d8094 --- /dev/null +++ b/src/tests/package-mcp-server-elicitation.test.ts @@ -0,0 +1,227 @@ +import test from 'node:test' +import assert from 'node:assert/strict' +import { Client } from '@modelcontextprotocol/sdk/client/index.js' +import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js' +import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js' + +import { + buildAskUserQuestionsElicitRequest, + createMcpServer, + formatAskUserQuestionsElicitResult, +} from '../../packages/mcp-server/src/server.js' + +function createSessionManagerStub() { + return { + startSession: async () => { + throw new Error('not implemented in test') + }, + getSession: () => undefined, + getResult: () => undefined, + cancelSession: async () => {}, + resolveBlocker: async () => {}, + } +} + +async function createConnectedClient(options?: { + onElicit?: (params: unknown) => Promise, +}) { + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair() + + const { server } = await createMcpServer(createSessionManagerStub() as never) + const client = new Client({ + name: 'test-client', + version: '0.0.0', + }, { + capabilities: { + elicitation: {}, + }, + }) + + if (options?.onElicit) { + client.setRequestHandler(ElicitRequestSchema, options.onElicit) + } + + await Promise.all([ + server.connect(serverTransport), + client.connect(clientTransport), + ]) + + return { + client, + close: async () => { + await client.close() + await server.close() + }, + } +} + +test('package MCP server exposes ask_user_questions over listTools', async () => { + const { client, close } = await createConnectedClient() + + try { + const tools = await client.listTools() + assert.ok(tools.tools.some(tool => tool.name === 'ask_user_questions')) + } finally { + await close() + } +}) + +test('ask_user_questions returns the packaged answers JSON shape for form elicitation', async () => { + const { client, close } = await createConnectedClient({ + onElicit: async (request) => { + const elicitation = (request as { + params?: { + message: string, + requestedSchema: { properties: Record, required?: string[] }, + }, + }).params ?? request as { + message: string, + requestedSchema: { properties: Record, required?: string[] }, + } + assert.match(elicitation.message, /Please answer the following question/) + assert.ok(elicitation.requestedSchema.properties.deployment) + assert.ok(elicitation.requestedSchema.properties['deployment__note']) + assert.ok(elicitation.requestedSchema.required?.includes('deployment')) + + return { + action: 'accept', + content: { + deployment: 'None of the above', + deployment__note: 'Need hybrid deployment.', + }, + } + }, + }) + + try { + const result = await client.callTool({ + name: 'ask_user_questions', + arguments: { + questions: [ + { + id: 'deployment', + header: 'Deploy', + question: 'Where will this run?', + options: [ + { label: 'Cloud', description: 'Managed hosting.' }, + { label: 'On-prem', description: 'Runs in customer infrastructure.' }, + ], + }, + ], + }, + }) + + const text = result.content.find(item => item.type === 'text') + assert.ok(text && 'text' in text) + assert.equal( + text.text, + JSON.stringify({ + answers: { + deployment: { + answers: ['None of the above', 'user_note: Need hybrid deployment.'], + }, + }, + }), + ) + } finally { + await close() + } +}) + +test('ask_user_questions returns an error result for invalid question payloads', async () => { + const { client, close } = await createConnectedClient() + + try { + const result = await client.callTool({ + name: 'ask_user_questions', + arguments: { + questions: [ + { + id: 'broken', + header: 'Broken', + question: 'This payload is invalid', + options: [], + }, + ], + }, + }) + + const text = result.content.find(item => item.type === 'text') + assert.ok(text && 'text' in text) + assert.equal(result.isError, true) + assert.match(text.text, /requires non-empty options/i) + } finally { + await close() + } +}) + +test('ask_user_questions returns the cancellation message when elicitation is declined', async () => { + const { client, close } = await createConnectedClient({ + onElicit: async () => ({ + action: 'decline', + }), + }) + + try { + const result = await client.callTool({ + name: 'ask_user_questions', + arguments: { + questions: [ + { + id: 'continue', + header: 'Continue', + question: 'Continue?', + options: [ + { label: 'Yes', description: 'Proceed.' }, + { label: 'No', description: 'Stop here.' }, + ], + }, + ], + }, + }) + + const text = result.content.find(item => item.type === 'text') + assert.ok(text && 'text' in text) + assert.equal(text.text, 'ask_user_questions was cancelled before receiving a response') + } finally { + await close() + } +}) + +test('helper formatting stays aligned with the tool contract', () => { + const questions = [ + { + id: 'focus_areas', + header: 'Focus', + question: 'Which areas matter most?', + allowMultiple: true, + options: [ + { label: 'Frontend', description: 'Prioritize the UI.' }, + { label: 'Backend', description: 'Prioritize server logic.' }, + ], + }, + ] + + const request = buildAskUserQuestionsElicitRequest(questions) + assert.equal(request.mode, 'form') + assert.ok(request.requestedSchema.properties.focus_areas) + assert.ok(!request.requestedSchema.properties['focus_areas__note']) + + const formatted = formatAskUserQuestionsElicitResult(questions, { + action: 'accept', + content: { + focus_areas: ['Frontend', 'Backend'], + }, + }) + + assert.equal( + formatted, + JSON.stringify({ + answers: { + focus_areas: { + answers: ['Frontend', 'Backend'], + }, + }, + }), + ) +}) diff --git a/src/tests/pi-ai-event-stream-factory.test.ts b/src/tests/pi-ai-event-stream-factory.test.ts new file mode 100644 index 000000000..e43b1df64 --- /dev/null +++ b/src/tests/pi-ai-event-stream-factory.test.ts @@ -0,0 +1,14 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { + AssistantMessageEventStream, + createAssistantMessageEventStream, +} from "@gsd/pi-ai"; + +describe("@gsd/pi-ai event stream exports", () => { + it("exports createAssistantMessageEventStream for package consumers", () => { + assert.equal(typeof createAssistantMessageEventStream, "function"); + const stream = createAssistantMessageEventStream(); + assert.ok(stream instanceof AssistantMessageEventStream); + }); +}); diff --git a/src/tests/provider-help-text.test.ts b/src/tests/provider-help-text.test.ts new file mode 100644 index 000000000..e66b9b3a6 --- /dev/null +++ b/src/tests/provider-help-text.test.ts @@ -0,0 +1,22 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; + +// Validate that help-text.ts includes updated provider references +const { printSubcommandHelp } = await import("../../dist/help-text.js"); + +describe("help-text provider references", () => { + it("config help mentions OpenRouter and Ollama", () => { + const lines: string[] = []; + const origWrite = process.stdout.write.bind(process.stdout); + (process.stdout as any).write = (chunk: string) => { lines.push(chunk); return true; }; + try { + printSubcommandHelp("config", "0.0.0"); + } finally { + (process.stdout as any).write = origWrite; + } + const text = lines.join(""); + assert.ok(text.includes("OpenRouter"), "OpenRouter should be mentioned in config help"); + assert.ok(text.includes("Ollama"), "Ollama should be mentioned in config help"); + assert.ok(text.includes("docs/providers.md"), "providers.md reference should be in config help"); + }); +}); diff --git a/src/tests/provider-manager-enter-key.test.ts b/src/tests/provider-manager-enter-key.test.ts new file mode 100644 index 000000000..ada68f245 --- /dev/null +++ b/src/tests/provider-manager-enter-key.test.ts @@ -0,0 +1,46 @@ +/** + * Regression test for #3579 — Enter key initiates auth setup in provider manager + * + * The provider manager component did not handle the Enter key, leaving users + * unable to initiate auth setup without knowing the 'd' keyboard shortcut. + * The fix adds a selectConfirm handler that calls onSetupAuth. + * + * Structural verification test — reads source to confirm selectConfirm handler + * and onSetupAuth callback exist in provider-manager.ts. + */ + +import { describe, test } from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); + +const source = readFileSync( + join(__dirname, '..', '..', 'packages', 'pi-coding-agent', 'src', 'modes', 'interactive', 'components', 'provider-manager.ts'), + 'utf-8', +); + +describe('provider manager Enter key handler (#3579)', () => { + test('onSetupAuth callback property exists', () => { + assert.match(source, /onSetupAuth/, + 'onSetupAuth callback should be defined'); + }); + + test('selectConfirm key handler exists', () => { + assert.match(source, /selectConfirm/, + 'selectConfirm key binding should be handled'); + }); + + test('onSetupAuth is called with provider name', () => { + assert.match(source, /this\.onSetupAuth\(provider\.name\)/, + 'onSetupAuth should be called with provider.name'); + }); + + test('setup auth hint is shown', () => { + assert.match(source, /setup auth/, + 'enter key hint should mention "setup auth"'); + }); +}); diff --git a/src/tests/provider-manager-remove.test.ts b/src/tests/provider-manager-remove.test.ts index e7faf9b0e..87ed9a144 100644 --- a/src/tests/provider-manager-remove.test.ts +++ b/src/tests/provider-manager-remove.test.ts @@ -86,7 +86,7 @@ function createComponent(options: { }; } -test("provider manager removes provider models and refreshes even when no auth is stored", (t) => { +test("provider manager skips remove when provider has no auth", (t) => { const modelsJsonPath = createTempModelsJsonPath(); const rootDir = join(modelsJsonPath, ".."); t.after(() => rmSync(rootDir, { recursive: true, force: true })); @@ -98,10 +98,35 @@ test("provider manager removes provider models and refreshes even when no auth i component.handleInput("r"); + // No auth means remove is a no-op + assert.deepEqual(removedProviders, []); + assert.deepEqual(readProviders(modelsJsonPath), ["custom"]); + assert.equal(getRefreshCalls(), 0); + assert.equal(getRenderCalls(), 0); +}); + +test("provider manager removes provider models with confirmation when auth is stored", (t) => { + const modelsJsonPath = createTempModelsJsonPath(); + const rootDir = join(modelsJsonPath, ".."); + t.after(() => rmSync(rootDir, { recursive: true, force: true })); + + const { component, removedProviders, getRefreshCalls, getRenderCalls } = createComponent({ + modelsJsonPath, + authProviders: ["custom"], + providers: [{ name: "custom", modelIds: ["local-model"] }], + }); + + // First press enters confirmation mode + component.handleInput("r"); + assert.deepEqual(removedProviders, []); + assert.equal((component as any).confirmingRemove, true); + + // Second press confirms removal + component.handleInput("r"); assert.deepEqual(removedProviders, ["custom"]); assert.deepEqual(readProviders(modelsJsonPath), []); assert.equal(getRefreshCalls(), 1); - assert.equal(getRenderCalls(), 1); + assert.ok(getRenderCalls() >= 2); assert.ok(!(component as any).providers.some((provider: { name: string; modelCount: number }) => provider.name === "custom" || provider.modelCount > 0, )); @@ -125,6 +150,9 @@ test("provider manager clamps selection after removing the selected provider", ( (component as any).selectedIndex = (component as any).providers.findIndex( (provider: { name: string }) => provider.name === "zeta", ); + + // Double-press r to confirm removal + component.handleInput("r"); component.handleInput("r"); assert.deepEqual(readProviders(modelsJsonPath), ["alpha"]); diff --git a/src/tests/provider-migrations.test.ts b/src/tests/provider-migrations.test.ts new file mode 100644 index 000000000..d23e22b99 --- /dev/null +++ b/src/tests/provider-migrations.test.ts @@ -0,0 +1,77 @@ +import test from "node:test" +import assert from "node:assert/strict" +import { hasDirectAnthropicApiKey, shouldMigrateAnthropicToClaudeCode } from "../provider-migrations.ts" + +function makeAuthStorage(credentials: unknown[]) { + return { + getCredentialsForProvider(provider: string) { + return provider === "anthropic" ? credentials : [] + }, + } +} + +test("hasDirectAnthropicApiKey detects non-empty auth storage keys", () => { + assert.equal( + hasDirectAnthropicApiKey( + makeAuthStorage([{ type: "api_key", key: "sk-ant-test" }]) as any, + {} as NodeJS.ProcessEnv, + ), + true, + ) +}) + +test("hasDirectAnthropicApiKey ignores empty placeholder keys", () => { + assert.equal( + hasDirectAnthropicApiKey( + makeAuthStorage([{ type: "api_key", key: "" }]) as any, + {} as NodeJS.ProcessEnv, + ), + false, + ) +}) + +test("hasDirectAnthropicApiKey detects ANTHROPIC_API_KEY env fallback", () => { + assert.equal( + hasDirectAnthropicApiKey( + makeAuthStorage([]) as any, + { ANTHROPIC_API_KEY: "sk-ant-env" } as NodeJS.ProcessEnv, + ), + true, + ) +}) + +test("shouldMigrateAnthropicToClaudeCode blocks migration for direct-key users", () => { + assert.equal( + shouldMigrateAnthropicToClaudeCode({ + authStorage: makeAuthStorage([{ type: "api_key", key: "sk-ant-test" }]) as any, + isClaudeCodeReady: true, + defaultProvider: "anthropic", + env: {} as NodeJS.ProcessEnv, + }), + false, + ) +}) + +test("shouldMigrateAnthropicToClaudeCode allows OAuth-only anthropic users", () => { + assert.equal( + shouldMigrateAnthropicToClaudeCode({ + authStorage: makeAuthStorage([{ type: "oauth" }]) as any, + isClaudeCodeReady: true, + defaultProvider: "anthropic", + env: {} as NodeJS.ProcessEnv, + }), + true, + ) +}) + +test("shouldMigrateAnthropicToClaudeCode stays off for other providers", () => { + assert.equal( + shouldMigrateAnthropicToClaudeCode({ + authStorage: makeAuthStorage([{ type: "oauth" }]) as any, + isClaudeCodeReady: true, + defaultProvider: "openai", + env: {} as NodeJS.ProcessEnv, + }), + false, + ) +}) diff --git a/src/tests/pty-chat-parser.test.ts b/src/tests/pty-chat-parser.test.ts index 5ed060fb0..07e21b63b 100644 --- a/src/tests/pty-chat-parser.test.ts +++ b/src/tests/pty-chat-parser.test.ts @@ -19,3 +19,131 @@ test("PtyChatParser.flush emits a trailing partial line without waiting for a ne assert.equal(latest[0]?.role, "assistant"); assert.equal(latest[0]?.content, "All slices are complete — nothing to discuss.\n"); }); + +// ─── Bug #2707: User messages omitted ──────────────────────────────────────── + +test("user input echoed on the same prompt line is classified as role=user", () => { + const parser = new PtyChatParser("test"); + let latest = parser.getMessages(); + parser.onMessage(() => { + latest = parser.getMessages(); + }); + + // GSD prints assistant response, then prompt with user input on same line + parser.feed("Here is your task summary.\n"); + parser.feed("❯ show status\n"); + + const userMsgs = latest.filter((m) => m.role === "user"); + assert.equal(userMsgs.length, 1, "should have exactly one user message"); + assert.equal(userMsgs[0].content, "show status"); +}); + +test("user input on a separate line after bare prompt is classified as role=user, not assistant", () => { + const parser = new PtyChatParser("test"); + let latest = parser.getMessages(); + parser.onMessage(() => { + latest = parser.getMessages(); + }); + + // GSD prints assistant text, then bare prompt on its own line + parser.feed("Done processing.\n"); + parser.feed("❯ \n"); + // User input appears on the next line (PTY echo without prompt prefix) + parser.feed("hello world\n"); + + const userMsgs = latest.filter((m) => m.role === "user"); + assert.equal(userMsgs.length, 1, "should have exactly one user message"); + assert.equal(userMsgs[0].content, "hello world"); + + // The user input must NOT appear as assistant content + const assistantMsgs = latest.filter((m) => m.role === "assistant"); + for (const msg of assistantMsgs) { + assert.ok( + !msg.content.includes("hello world"), + "user input must not be misclassified as assistant content", + ); + } +}); + +test("multiple user turns: each user input after prompt is role=user", () => { + const parser = new PtyChatParser("test"); + let latest = parser.getMessages(); + parser.onMessage(() => { + latest = parser.getMessages(); + }); + + // Turn 1: assistant response, prompt, user input + parser.feed("Welcome to GSD.\n"); + parser.feed("❯ \n"); + parser.feed("discuss\n"); + + // Turn 2: assistant response, prompt, user input + parser.feed("Starting discussion mode.\n"); + parser.feed("❯ \n"); + parser.feed("plan my milestone\n"); + + const userMsgs = latest.filter((m) => m.role === "user"); + assert.equal(userMsgs.length, 2, "should have two user messages"); + assert.equal(userMsgs[0].content, "discuss"); + assert.equal(userMsgs[1].content, "plan my milestone"); +}); + +test("awaitingInput is true after prompt line, false after user input arrives", () => { + const parser = new PtyChatParser("test"); + + parser.feed("Task complete.\n"); + assert.equal(parser.isAwaitingInput(), false, "not awaiting input before prompt"); + + parser.feed("❯ \n"); + assert.equal(parser.isAwaitingInput(), true, "awaiting input after bare prompt"); + + parser.feed("next command\n"); + assert.equal(parser.isAwaitingInput(), false, "no longer awaiting after user input"); +}); + +test("awaitingInput resets when assistant content follows user input", () => { + const parser = new PtyChatParser("test"); + + parser.feed("Hello.\n"); + parser.feed("❯ \n"); + assert.equal(parser.isAwaitingInput(), true); + + parser.feed("do something\n"); + assert.equal(parser.isAwaitingInput(), false); + + // Assistant responds + parser.feed("Working on it...\n"); + assert.equal(parser.isAwaitingInput(), false, "should stay false during assistant output"); +}); + +// ─── Bug #2707: Chat looks stuck ──────────────────────────────────────────── + +test("prompt with empty user text does not create a user message but signals awaiting input", () => { + const parser = new PtyChatParser("test"); + let latest = parser.getMessages(); + parser.onMessage(() => { + latest = parser.getMessages(); + }); + + parser.feed("All done.\n"); + parser.feed("❯ \n"); + + const userMsgs = latest.filter((m) => m.role === "user"); + assert.equal(userMsgs.length, 0, "bare prompt should not create a user message"); + assert.equal(parser.isAwaitingInput(), true, "parser should signal awaiting input"); +}); + +test("alternate prompt markers (› and >) also trigger awaiting input", () => { + const parser = new PtyChatParser("test"); + + parser.feed("Response text.\n"); + parser.feed("› \n"); + assert.equal(parser.isAwaitingInput(), true, "› prompt should trigger awaiting input"); + + parser.feed("user reply\n"); + assert.equal(parser.isAwaitingInput(), false); + + parser.feed("More output.\n"); + parser.feed("> \n"); + assert.equal(parser.isAwaitingInput(), true, "> prompt should trigger awaiting input"); +}); diff --git a/src/tests/read-tool-offset-clamp.test.ts b/src/tests/read-tool-offset-clamp.test.ts new file mode 100644 index 000000000..4dc4c5e78 --- /dev/null +++ b/src/tests/read-tool-offset-clamp.test.ts @@ -0,0 +1,106 @@ +/** + * Tests for read tool offset clamping (#3007). + * + * When offset exceeds file length, the read tool should clamp to the + * last line instead of throwing, preventing downstream JSON parse errors + * in auto-mode milestone completion. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; + +import { createReadTool } from "../../packages/pi-coding-agent/src/core/tools/read.ts"; + +// ─── Helpers ───────────────────────────────────────────────────────────────── + +function makeTmpDir(): { dir: string; cleanup: () => void } { + const dir = mkdtempSync(join(tmpdir(), "read-tool-test-")); + return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) }; +} + +function writeLines(dir: string, name: string, lineCount: number): string { + const lines = Array.from({ length: lineCount }, (_, i) => `Line ${i + 1}: content`); + const filePath = join(dir, name); + writeFileSync(filePath, lines.join("\n")); + return filePath; +} + +// ═══════════════════════════════════════════════════════════════════════════ +// Offset beyond file bounds — should clamp, not throw (#3007) +// ═══════════════════════════════════════════════════════════════════════════ + +test("read tool: offset exceeding file length should NOT throw (#3007)", async (t) => { + const { dir, cleanup } = makeTmpDir(); + t.after(cleanup); + writeLines(dir, "small-artifact.md", 13); + + const readTool = createReadTool(dir); + + // offset 30 on a 13-line file — exact reproduction of #3007 + const result = await readTool.execute("test-call", { + path: "small-artifact.md", + offset: 30, + }); + + assert.ok(result, "should return a result, not throw"); + assert.ok(result.content, "should have content"); + assert.ok(result.content.length > 0, "should have at least one content block"); + + const text = (result.content[0] as any).text as string; + assert.ok(typeof text === "string", "first content block should be text"); + // Should include the last line of the file (clamped) + assert.ok(text.includes("Line 13"), "should include last line of file after clamping"); +}); + +test("read tool: offset 100 on a 5-line file clamps to last line", async (t) => { + const { dir, cleanup } = makeTmpDir(); + t.after(cleanup); + writeLines(dir, "tiny-file.txt", 5); + + const readTool = createReadTool(dir); + const result = await readTool.execute("test-call", { + path: "tiny-file.txt", + offset: 100, + }); + + const text = (result.content[0] as any).text as string; + assert.ok(text.includes("Line 5"), "should include the last line of the file"); +}); + +test("read tool: offset at exact last line works normally", async (t) => { + const { dir, cleanup } = makeTmpDir(); + t.after(cleanup); + writeLines(dir, "exact-offset.txt", 5); + + const readTool = createReadTool(dir); + // offset 5 on a 5-line file — should return line 5 (valid, no clamping needed) + const result = await readTool.execute("test-call", { + path: "exact-offset.txt", + offset: 5, + }); + + const text = (result.content[0] as any).text as string; + assert.ok(text.includes("Line 5"), "should include line 5"); +}); + +test("read tool: clamped offset includes notice about adjustment", async (t) => { + const { dir, cleanup } = makeTmpDir(); + t.after(cleanup); + writeLines(dir, "notice-test.md", 10); + + const readTool = createReadTool(dir); + const result = await readTool.execute("test-call", { + path: "notice-test.md", + offset: 50, + }); + + const text = (result.content[0] as any).text as string; + // Should contain some notice that the offset was adjusted + assert.ok( + text.includes("clamped") || text.includes("adjusted") || text.includes("beyond"), + `should indicate offset was clamped, got: ${text.slice(0, 200)}`, + ); +}); diff --git a/src/tests/resource-loader-conflicts.test.ts b/src/tests/resource-loader-conflicts.test.ts new file mode 100644 index 000000000..19d13973e --- /dev/null +++ b/src/tests/resource-loader-conflicts.test.ts @@ -0,0 +1,235 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { join, resolve, relative, sep } from "node:path"; + +// ─── Inline the pure functions under test to avoid import-chain issues ─────── +// These are copied from packages/pi-coding-agent/src/core/resource-loader.ts +// (detectExtensionConflicts + extractExtensionKey). The test validates the +// algorithm; integration coverage lives in the full build tests. + +interface MinimalExtension { + path: string; + tools: Map; + commands: Map; + flags: Map; +} + +function extractExtensionKey(ownerPath: string, extensionsDir: string): string | undefined { + const normalizedDir = resolve(extensionsDir); + const normalizedPath = resolve(ownerPath); + const prefix = normalizedDir.endsWith(sep) ? normalizedDir : `${normalizedDir}${sep}`; + if (!normalizedPath.startsWith(prefix)) { + return undefined; + } + const relPath = relative(normalizedDir, normalizedPath); + const firstSegment = relPath.split(/[\\/]/)[0]; + return firstSegment?.replace(/\.(?:ts|js)$/, "") || undefined; +} + +function detectExtensionConflicts( + extensions: MinimalExtension[], + bundledExtensionKeys: Set, + extensionsDir: string, +): Array<{ path: string; message: string }> { + const conflicts: Array<{ path: string; message: string }> = []; + const toolOwners = new Map(); + const commandOwners = new Map(); + const flagOwners = new Map(); + + const isBundled = (ownerPath: string): boolean => { + const key = extractExtensionKey(ownerPath, extensionsDir); + return key !== undefined && bundledExtensionKeys.has(key); + }; + + for (const ext of extensions) { + for (const toolName of ext.tools.keys()) { + const existingOwner = toolOwners.get(toolName); + if (existingOwner && existingOwner !== ext.path) { + const hint = isBundled(existingOwner) + ? ` (built-in tool supersedes — consider removing ${ext.path})` + : ""; + conflicts.push({ path: ext.path, message: `Tool "${toolName}" conflicts with ${existingOwner}${hint}` }); + } else { + toolOwners.set(toolName, ext.path); + } + } + + for (const commandName of ext.commands.keys()) { + const existingOwner = commandOwners.get(commandName); + if (existingOwner && existingOwner !== ext.path) { + const hint = isBundled(existingOwner) + ? ` (built-in command supersedes — consider removing ${ext.path})` + : ""; + conflicts.push({ path: ext.path, message: `Command "/${commandName}" conflicts with ${existingOwner}${hint}` }); + } else { + commandOwners.set(commandName, ext.path); + } + } + + for (const flagName of ext.flags.keys()) { + const existingOwner = flagOwners.get(flagName); + if (existingOwner && existingOwner !== ext.path) { + conflicts.push({ path: ext.path, message: `Flag "--${flagName}" conflicts with ${existingOwner}` }); + } else { + flagOwners.set(flagName, ext.path); + } + } + } + + return conflicts; +} + +// ─── helpers ────────────────────────────────────────────────────────────────── + +function makeExtension( + path: string, + overrides: { tools?: string[]; commands?: string[]; flags?: string[] } = {}, +): MinimalExtension { + const tools = new Map(); + for (const name of overrides.tools ?? []) tools.set(name, {}); + const commands = new Map(); + for (const name of overrides.commands ?? []) commands.set(name, {}); + const flags = new Map(); + for (const name of overrides.flags ?? []) flags.set(name, {}); + return { path, tools, commands, flags }; +} + +// ─── extractExtensionKey ───────────────────────────────────────────────────── + +describe("extractExtensionKey", () => { + const extensionsDir = "/home/user/.gsd/agent/extensions"; + + it("extracts directory name from a nested extension path", () => { + assert.equal( + extractExtensionKey("/home/user/.gsd/agent/extensions/mcp-client/index.js", extensionsDir), + "mcp-client", + ); + }); + + it("strips .ts/.js suffix from flat extension files", () => { + assert.equal( + extractExtensionKey("/home/user/.gsd/agent/extensions/my-ext.ts", extensionsDir), + "my-ext", + ); + }); + + it("returns undefined when the path is not under extensionsDir", () => { + assert.equal( + extractExtensionKey("/other/path/some-ext/index.js", extensionsDir), + undefined, + ); + }); +}); + +// ─── detectExtensionConflicts ───────────────────────────────────────────────── + +describe("detectExtensionConflicts", () => { + const extensionsDir = "/home/user/.gsd/agent/extensions"; + + it("returns no conflicts when extensions have unique tool names", () => { + const extensions = [ + makeExtension(join(extensionsDir, "ext-a/index.js"), { tools: ["tool_a"] }), + makeExtension(join(extensionsDir, "ext-b/index.js"), { tools: ["tool_b"] }), + ]; + const conflicts = detectExtensionConflicts(extensions, new Set(["ext-a"]), extensionsDir); + assert.equal(conflicts.length, 0); + }); + + it("adds supersedes hint when first-registered tool owner is a bundled extension", () => { + const bundledPath = join(extensionsDir, "mcp-client/index.js"); + const userPath = join(extensionsDir, "mcporter/index.ts"); + + const extensions = [ + makeExtension(bundledPath, { tools: ["mcp_servers"] }), + makeExtension(userPath, { tools: ["mcp_servers"] }), + ]; + + const conflicts = detectExtensionConflicts(extensions, new Set(["mcp-client"]), extensionsDir); + + assert.equal(conflicts.length, 1); + assert.ok( + conflicts[0].message.includes("supersedes"), + `Expected "supersedes" in message, got: ${conflicts[0].message}`, + ); + assert.equal(conflicts[0].path, userPath); + }); + + it("omits supersedes hint when first-registered tool owner is NOT bundled", () => { + const userPathA = join(extensionsDir, "mcporter/index.ts"); + const userPathB = join(extensionsDir, "mcporter-v2/index.ts"); + + const extensions = [ + makeExtension(userPathA, { tools: ["mcp_servers"] }), + makeExtension(userPathB, { tools: ["mcp_servers"] }), + ]; + + const conflicts = detectExtensionConflicts(extensions, new Set(["mcp-client"]), extensionsDir); + + assert.equal(conflicts.length, 1); + assert.ok( + !conflicts[0].message.includes("supersedes"), + `Expected no "supersedes" in message, got: ${conflicts[0].message}`, + ); + }); + + it("adds supersedes hint for command conflicts with bundled extensions", () => { + const bundledPath = join(extensionsDir, "mcp-client/index.js"); + const userPath = join(extensionsDir, "mcporter/index.ts"); + + const extensions = [ + makeExtension(bundledPath, { commands: ["mcp"] }), + makeExtension(userPath, { commands: ["mcp"] }), + ]; + + const conflicts = detectExtensionConflicts(extensions, new Set(["mcp-client"]), extensionsDir); + + assert.equal(conflicts.length, 1); + assert.ok( + conflicts[0].message.includes("supersedes"), + `Expected "supersedes" in command conflict, got: ${conflicts[0].message}`, + ); + }); + + it("works with an empty bundledExtensionKeys set (backwards compat)", () => { + const pathA = join(extensionsDir, "ext-a/index.js"); + const pathB = join(extensionsDir, "ext-b/index.js"); + + const extensions = [ + makeExtension(pathA, { tools: ["shared_tool"] }), + makeExtension(pathB, { tools: ["shared_tool"] }), + ]; + + const conflicts = detectExtensionConflicts(extensions, new Set(), extensionsDir); + + assert.equal(conflicts.length, 1); + assert.ok( + !conflicts[0].message.includes("supersedes"), + `Expected no "supersedes" when bundledKeys empty, got: ${conflicts[0].message}`, + ); + }); + + it("reproduces issue #2075: bundled extension under /.gsd/agent/extensions/ was never identified as built-in", () => { + // Before the fix, the isBuiltIn check used path heuristics that excluded + // paths containing /.gsd/agent/extensions/, so bundled extensions placed + // there by initResources() could never be recognized as built-in. + const bundledPath = "/home/user/.gsd/agent/extensions/mcp-client/index.js"; + const userPath = "/home/user/.gsd/agent/extensions/mcporter/index.ts"; + + const extensions = [ + makeExtension(bundledPath, { tools: ["mcp_servers", "mcp_discover", "mcp_call"] }), + makeExtension(userPath, { tools: ["mcp_servers", "mcp_discover", "mcp_call"] }), + ]; + + const bundledKeys = new Set(["mcp-client"]); + const conflicts = detectExtensionConflicts(extensions, bundledKeys, "/home/user/.gsd/agent/extensions"); + + // All three conflicting tools should include the supersedes hint + assert.equal(conflicts.length, 3); + for (const conflict of conflicts) { + assert.ok( + conflict.message.includes("supersedes"), + `Conflict for tool should include "supersedes" hint, got: ${conflict.message}`, + ); + } + }); +}); diff --git a/src/tests/resource-loader.test.ts b/src/tests/resource-loader.test.ts index 12622a1ad..06dd615c5 100644 --- a/src/tests/resource-loader.test.ts +++ b/src/tests/resource-loader.test.ts @@ -1,6 +1,6 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join, parse } from "node:path"; import { tmpdir } from "node:os"; @@ -53,18 +53,24 @@ test("hasStaleCompiledExtensionSiblings only flags top-level .ts/.js sibling pai const { hasStaleCompiledExtensionSiblings } = await import("../resource-loader.ts"); const tmp = mkdtempSync(join(tmpdir(), "gsd-resource-loader-")); const extensionsDir = join(tmp, "extensions"); + const bundledDir = join(tmp, "bundled"); t.after(() => { rmSync(tmp, { recursive: true, force: true }); }); + mkdirSync(bundledDir, { recursive: true }); mkdirSync(join(extensionsDir, "gsd"), { recursive: true }); writeFileSync(join(extensionsDir, "gsd", "index.ts"), "export {};\n"); - assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir), false); + assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir, bundledDir), false); + writeFileSync(join(bundledDir, "ask-user-questions.js"), "export {};\n"); writeFileSync(join(extensionsDir, "ask-user-questions.js"), "export {};\n"); - assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir), false); + assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir, bundledDir), false); writeFileSync(join(extensionsDir, "ask-user-questions.ts"), "export {};\n"); - assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir), true); + assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir, bundledDir), true); + + writeFileSync(join(bundledDir, "ask-user-questions.ts"), "export {};\n"); + assert.equal(hasStaleCompiledExtensionSiblings(extensionsDir, bundledDir), false); }); test("buildResourceLoader excludes duplicate top-level pi extensions when bundled resources use .js", async (t) => { @@ -98,6 +104,39 @@ test("buildResourceLoader excludes duplicate top-level pi extensions when bundle ); }); +test("initResources manifest tracks all bundled extension subdirectories including remote-questions (#2367)", async () => { + const { initResources } = await import("../resource-loader.ts"); + const tmp = mkdtempSync(join(tmpdir(), "gsd-resource-loader-manifest-")); + const fakeAgentDir = join(tmp, "agent"); + + try { + initResources(fakeAgentDir); + + const manifestPath = join(fakeAgentDir, "managed-resources.json"); + assert.equal(existsSync(manifestPath), true, "managed-resources.json should exist after initResources"); + + const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")); + const installedDirs: string[] = manifest.installedExtensionDirs ?? []; + + // remote-questions uses mod.ts (not index.ts) as its entry point and has an + // extension-manifest.json — it must still appear in the manifest so that + // pruneRemovedBundledExtensions can track it across upgrades. + assert.ok( + installedDirs.includes("remote-questions"), + `installedExtensionDirs should include remote-questions but got: [${installedDirs.join(", ")}]`, + ); + + // Also verify that the synced remote-questions directory actually exists in the agent dir + assert.equal( + existsSync(join(fakeAgentDir, "extensions", "remote-questions")), + true, + "remote-questions directory should be synced to agent extensions", + ); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } +}); + test("initResources prunes stale top-level extension siblings next to bundled compiled extensions", async (t) => { const { initResources } = await import("../resource-loader.ts"); const tmp = mkdtempSync(join(tmpdir(), "gsd-resource-loader-sync-")); @@ -115,15 +154,75 @@ test("initResources prunes stale top-level extension siblings next to bundled co const staleSiblingPath = bundledPath.endsWith(".js") ? bundledTsPath : bundledJsPath; + const siblingWasBundled = existsSync(staleSiblingPath); + const staleContent = "export {};\n"; assert.equal(existsSync(bundledPath), true, "bundled top-level extension should exist"); // Simulate a stale opposite-format sibling left from a previous sync/build mismatch. - writeFileSync(staleSiblingPath, "export {};\n"); + writeFileSync(staleSiblingPath, staleContent); assert.equal(existsSync(staleSiblingPath), true); + // Force a full resync so this test exercises the prune/copy path rather than + // the early-return manifest fast path. + const manifestPath = join(fakeAgentDir, "managed-resources.json"); + const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")); + manifest.contentHash = "force-resync"; + writeFileSync(manifestPath, JSON.stringify(manifest)); + initResources(fakeAgentDir); - assert.equal(existsSync(staleSiblingPath), false, "stale top-level sibling should be removed during sync"); + if (siblingWasBundled) { + assert.equal(existsSync(staleSiblingPath), true, "bundled sibling should be restored during sync"); + assert.notEqual(readFileSync(staleSiblingPath, "utf-8"), staleContent, "bundled sibling should overwrite stale contents"); + } else { + assert.equal(existsSync(staleSiblingPath), false, "stale top-level sibling should be removed during sync"); + } assert.equal(existsSync(bundledPath), true, "bundled extension should remain after cleanup"); }); + +test("pruneRemovedBundledExtensions removes stale subdirectory extensions not in current bundle", async () => { + const { initResources } = await import("../resource-loader.ts"); + const tmp = mkdtempSync(join(tmpdir(), "gsd-resource-loader-prune-dirs-")); + const fakeAgentDir = join(tmp, "agent"); + + try { + // First sync — seeds the agent dir and writes the manifest. + initResources(fakeAgentDir); + + // Simulate a stale subdirectory extension left from a previous GSD version. + // This mirrors the mcporter scenario: it was bundled before, synced to + // ~/.gsd/agent/extensions/, then removed from the bundle in a newer version. + const staleExtDir = join(fakeAgentDir, "extensions", "mcporter"); + mkdirSync(staleExtDir, { recursive: true }); + writeFileSync(join(staleExtDir, "index.ts"), 'export default { name: "mcporter" };\n'); + assert.equal(existsSync(staleExtDir), true, "stale subdir extension should exist before prune"); + + // Read the manifest to verify subdirectory extensions are tracked. + const manifestPath = join(fakeAgentDir, "managed-resources.json"); + const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")); + + // The manifest must record installed extension directories so the pruner + // can detect when one has been removed from the bundle. + assert.ok( + Array.isArray(manifest.installedExtensionDirs), + "manifest should contain installedExtensionDirs array", + ); + + // Bump the manifest version to force a re-sync (simulates upgrading GSD). + manifest.gsdVersion = "0.0.0-force-resync"; + manifest.contentHash = "0000000000000000"; + writeFileSync(manifestPath, JSON.stringify(manifest)); + + // Second sync — the bundle no longer contains mcporter/, so it must be pruned. + initResources(fakeAgentDir); + + assert.equal( + existsSync(staleExtDir), + false, + "stale subdirectory extension (mcporter/) should be pruned after upgrade", + ); + } finally { + rmSync(tmp, { recursive: true, force: true }); + } +}); diff --git a/src/tests/rtk-session-stats.test.ts b/src/tests/rtk-session-stats.test.ts index 88a14e944..5b6f1791d 100644 --- a/src/tests/rtk-session-stats.test.ts +++ b/src/tests/rtk-session-stats.test.ts @@ -1,4 +1,4 @@ -import test from "node:test"; +import test, { beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; import { chmodSync, copyFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs"; import { join } from "node:path"; @@ -12,6 +12,24 @@ import { } from "../resources/extensions/shared/rtk-session-stats.ts"; import { createFakeRtk } from "./rtk-test-utils.ts"; +// Store original env values for restoration +let originalRtkDisabled: string | undefined; + +beforeEach(() => { + // Save and clear GSD_RTK_DISABLED so tests can use fake RTK binaries + originalRtkDisabled = process.env.GSD_RTK_DISABLED; + delete process.env.GSD_RTK_DISABLED; +}); + +afterEach(() => { + // Restore original env + if (originalRtkDisabled !== undefined) { + process.env.GSD_RTK_DISABLED = originalRtkDisabled; + } else { + delete process.env.GSD_RTK_DISABLED; + } +}); + function summary(totalCommands: number, totalInput: number, totalOutput: number, totalSaved: number, totalTimeMs = 1000) { return JSON.stringify({ summary: { diff --git a/src/tests/rtk.test.ts b/src/tests/rtk.test.ts index c51e2d7cf..8c9c76071 100644 --- a/src/tests/rtk.test.ts +++ b/src/tests/rtk.test.ts @@ -1,4 +1,4 @@ -import test from "node:test"; +import test, { beforeEach, afterEach } from "node:test"; import assert from "node:assert/strict"; import { chmodSync, copyFileSync, mkdirSync, mkdtempSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; @@ -19,6 +19,24 @@ import { } from "../rtk.ts"; import { createFakeRtk } from "./rtk-test-utils.ts"; +// Store original env values for restoration +let originalRtkDisabled: string | undefined; + +beforeEach(() => { + // Save and clear GSD_RTK_DISABLED so tests can use fake RTK binaries + originalRtkDisabled = process.env.GSD_RTK_DISABLED; + delete process.env.GSD_RTK_DISABLED; +}); + +afterEach(() => { + // Restore original env + if (originalRtkDisabled !== undefined) { + process.env.GSD_RTK_DISABLED = originalRtkDisabled; + } else { + delete process.env.GSD_RTK_DISABLED; + } +}); + test("resolveRtkAssetName maps supported release assets correctly", () => { assert.equal(resolveRtkAssetName("darwin", "arm64"), "rtk-aarch64-apple-darwin.tar.gz"); assert.equal(resolveRtkAssetName("darwin", "x64"), "rtk-x86_64-apple-darwin.tar.gz"); diff --git a/src/tests/security-overrides.test.ts b/src/tests/security-overrides.test.ts new file mode 100644 index 000000000..826065dbd --- /dev/null +++ b/src/tests/security-overrides.test.ts @@ -0,0 +1,105 @@ +import { describe, it, beforeEach, afterEach } from "node:test"; +import assert from "node:assert/strict"; +import { SettingsManager, getAllowedCommandPrefixes, SAFE_COMMAND_PREFIXES, setAllowedCommandPrefixes } from "@gsd/pi-coding-agent"; +import { getFetchAllowedUrls, setFetchAllowedUrls } from "../resources/extensions/search-the-web/url-utils.ts"; +import { applySecurityOverrides } from "../security-overrides.ts"; + +describe("applySecurityOverrides — env var and settings precedence", () => { + const savedEnv: Record = {}; + + beforeEach(() => { + // Snapshot env vars we might touch + savedEnv.GSD_ALLOWED_COMMAND_PREFIXES = process.env.GSD_ALLOWED_COMMAND_PREFIXES; + savedEnv.GSD_FETCH_ALLOWED_URLS = process.env.GSD_FETCH_ALLOWED_URLS; + delete process.env.GSD_ALLOWED_COMMAND_PREFIXES; + delete process.env.GSD_FETCH_ALLOWED_URLS; + + // Reset runtime state to defaults + setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES); + setFetchAllowedUrls([]); + }); + + afterEach(() => { + // Restore env vars + for (const [key, val] of Object.entries(savedEnv)) { + if (val === undefined) { + delete process.env[key]; + } else { + process.env[key] = val; + } + } + // Restore runtime defaults + setAllowedCommandPrefixes(SAFE_COMMAND_PREFIXES); + setFetchAllowedUrls([]); + }); + + // --- Command prefixes --- + + it("applies command prefixes from settings when no env var is set", () => { + const sm = SettingsManager.inMemory({ allowedCommandPrefixes: ["sops", "doppler"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getAllowedCommandPrefixes()], ["sops", "doppler"]); + }); + + it("env var overrides settings for command prefixes", () => { + process.env.GSD_ALLOWED_COMMAND_PREFIXES = "age,infisical"; + const sm = SettingsManager.inMemory({ allowedCommandPrefixes: ["sops", "doppler"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getAllowedCommandPrefixes()], ["age", "infisical"]); + }); + + it("empty env var does not override settings (falls through to settings)", () => { + process.env.GSD_ALLOWED_COMMAND_PREFIXES = ""; + const sm = SettingsManager.inMemory({ allowedCommandPrefixes: ["sops"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getAllowedCommandPrefixes()], ["sops"]); + }); + + it("env var with whitespace and trailing commas is trimmed correctly", () => { + process.env.GSD_ALLOWED_COMMAND_PREFIXES = " sops , doppler , , "; + const sm = SettingsManager.inMemory(); + applySecurityOverrides(sm); + assert.deepEqual([...getAllowedCommandPrefixes()], ["sops", "doppler"]); + }); + + it("keeps built-in defaults when neither env var nor settings are set", () => { + const sm = SettingsManager.inMemory(); + applySecurityOverrides(sm); + assert.deepEqual([...getAllowedCommandPrefixes()], [...SAFE_COMMAND_PREFIXES]); + }); + + // --- Fetch URL allowlist --- + + it("applies fetch allowed URLs from settings when no env var is set", () => { + const sm = SettingsManager.inMemory({ fetchAllowedUrls: ["internal.co", "192.168.1.50"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getFetchAllowedUrls()].sort(), ["192.168.1.50", "internal.co"]); + }); + + it("env var overrides settings for fetch allowed URLs", () => { + process.env.GSD_FETCH_ALLOWED_URLS = "my-docs.internal"; + const sm = SettingsManager.inMemory({ fetchAllowedUrls: ["other.internal"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getFetchAllowedUrls()], ["my-docs.internal"]); + }); + + it("empty env var does not override settings for fetch URLs", () => { + process.env.GSD_FETCH_ALLOWED_URLS = ""; + const sm = SettingsManager.inMemory({ fetchAllowedUrls: ["docs.internal"] }); + applySecurityOverrides(sm); + assert.deepEqual([...getFetchAllowedUrls()], ["docs.internal"]); + }); + + it("env var with whitespace and trailing commas is trimmed correctly for URLs", () => { + process.env.GSD_FETCH_ALLOWED_URLS = " a.internal , b.internal , , "; + const sm = SettingsManager.inMemory(); + applySecurityOverrides(sm); + assert.deepEqual([...getFetchAllowedUrls()].sort(), ["a.internal", "b.internal"]); + }); + + it("keeps empty allowlist when neither env var nor settings are set", () => { + const sm = SettingsManager.inMemory(); + applySecurityOverrides(sm); + assert.deepEqual([...getFetchAllowedUrls()], []); + }); +}); diff --git a/src/tests/session-memory-leaks.test.ts b/src/tests/session-memory-leaks.test.ts new file mode 100644 index 000000000..17a3590bb --- /dev/null +++ b/src/tests/session-memory-leaks.test.ts @@ -0,0 +1,144 @@ +/** + * Regression tests for CPU/memory leak fixes in long-running sessions. + * + * Structural tests that verify the fix patterns are present in source — + * NOT runtime integration tests. This approach is chosen because: + * - The leaks manifest over hours of real usage, not in unit test timescales + * - The fixes are defensive guards (caps, disposal, handler cleanup) + * - Structural verification catches regressions when code is refactored + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +// ── Helpers ────────────────────────────────────────────────────────── + +function readSource(relativePath: string): string { + return readFileSync(join(import.meta.dirname, "..", "..", relativePath), "utf-8"); +} + +function extractFunctionBody(src: string, name: string): string { + const fnStart = src.indexOf(name); + assert.ok(fnStart > -1, `${name} must exist in source`); + let depth = 0; + let fnEnd = -1; + for (let i = src.indexOf("{", fnStart); i < src.length; i++) { + if (src[i] === "{") depth++; + if (src[i] === "}") depth--; + if (depth === 0) { fnEnd = i; break; } + } + return src.slice(fnStart, fnEnd + 1); +} + +// ── TUI render-skip ───────────────────────────────────────────────── + +test("Container caches render output for stable-reference comparison", () => { + const src = readSource("packages/pi-tui/src/tui.ts"); + assert.ok( + src.includes("_prevRender"), + "Container must have _prevRender cache for render-skip optimization", + ); +}); + +test("TUI skips post-processing when component output is unchanged", () => { + const src = readSource("packages/pi-tui/src/tui.ts"); + assert.ok( + src.includes("_lastRenderedComponents"), + "TUI must track _lastRenderedComponents for reference-equality skip", + ); +}); + +// ── Loader frame isolation ────────────────────────────────────────── + +test("Loader does not call setText on every spinner tick", () => { + const src = readSource("packages/pi-tui/src/components/loader.ts"); + // The old pattern was: setText(`${frame} ${message}`) inside the interval + // The new pattern: only update Text when message changes, prepend frame in render() + assert.ok( + src.includes("_lastMessage"), + "Loader must track _lastMessage to avoid setText on every tick", + ); + // Verify the interval does NOT call setText or updateDisplay + const intervalMatch = src.match(/setInterval\s*\(\s*\(\)\s*=>\s*\{([^}]+)\}/s); + assert.ok(intervalMatch, "Loader must have a setInterval callback"); + const intervalBody = intervalMatch[1]; + assert.ok( + !intervalBody.includes("setText") && !intervalBody.includes("updateDisplay"), + "Loader interval must NOT call setText or updateDisplay — " + + "frame rotation should only trigger requestRender()", + ); +}); + +// ── Text cache guard ──────────────────────────────────────────────── + +test("Text.setText returns early when text is unchanged", () => { + const src = readSource("packages/pi-tui/src/components/text.ts"); + const setTextBody = extractFunctionBody(src, "setText("); + assert.ok( + setTextBody.includes("if (this.text === text) return"), + "setText must early-return when text is identical to prevent cache invalidation", + ); +}); + +// ── Chat component cap ────────────────────────────────────────────── + +test("InteractiveMode caps rendered chat components", () => { + const src = readSource("packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts"); + assert.ok( + src.includes("MAX_CHAT_COMPONENTS"), + "InteractiveMode must define MAX_CHAT_COMPONENTS to prevent unbounded growth", + ); + assert.ok( + src.includes("trimChatHistory"), + "InteractiveMode must call trimChatHistory to enforce the cap", + ); +}); + +// ── ToolExecution dispose ─────────────────────────────────────────── + +test("ToolExecutionComponent has dispose() to clear heavy references", () => { + const src = readSource("packages/pi-coding-agent/src/modes/interactive/components/tool-execution.ts"); + assert.ok( + src.includes("dispose()"), + "ToolExecutionComponent must have dispose() for GC of image maps, diff previews, etc.", + ); +}); + +// ── Orphan process prevention ─────────────────────────────────────── + +test("InteractiveMode kills descendant processes on shutdown", () => { + const src = readSource("packages/pi-coding-agent/src/modes/interactive/interactive-mode.ts"); + assert.ok( + src.includes("listDescendants"), + "Shutdown must use listDescendants to find orphan child processes", + ); + assert.ok( + src.includes("SIGTERM") && src.includes("SIGKILL"), + "Shutdown must send SIGTERM then SIGKILL to descendants", + ); +}); + +// ── Signal handler accumulation ───────────────────────────────────── + +test("bg-shell removes signal handlers on session_shutdown", () => { + const src = readSource("src/resources/extensions/bg-shell/bg-shell-lifecycle.ts"); + assert.ok( + src.includes('process.off("SIGTERM"') || src.includes("process.off('SIGTERM'"), + "session_shutdown must remove SIGTERM handler to prevent accumulation", + ); + assert.ok( + src.includes('process.off("SIGINT"') || src.includes("process.off('SIGINT'"), + "session_shutdown must remove SIGINT handler to prevent accumulation", + ); +}); + +// ── Alert queue cap ───────────────────────────────────────────────── + +test("pendingAlerts has a maximum size cap", () => { + const src = readSource("src/resources/extensions/bg-shell/process-manager.ts"); + assert.ok( + src.includes("MAX_PENDING_ALERTS"), + "process-manager must cap pendingAlerts to prevent unbounded growth", + ); +}); diff --git a/src/tests/startup-model-validation.test.ts b/src/tests/startup-model-validation.test.ts new file mode 100644 index 000000000..fc124a132 --- /dev/null +++ b/src/tests/startup-model-validation.test.ts @@ -0,0 +1,124 @@ +/** + * GSD-2 — Regression tests for startup model validation (#3534) + * + * Verifies that validateConfiguredModel() correctly handles extension-provided + * models and that stale model IDs (e.g. claude-opus-4-6[1m]) trigger fallback. + */ + +import { describe, it, beforeEach } from "node:test"; +import assert from "node:assert/strict"; +import { validateConfiguredModel } from "../startup-model-validation.js"; + +// ─── Helpers ──────────────────────────────────────────────────────────────── + +interface MockModel { + provider: string; + id: string; +} + +function createMockRegistry(allModels: MockModel[], availableModels?: MockModel[]) { + return { + getAll: () => allModels, + getAvailable: () => availableModels ?? allModels, + }; +} + +function createMockSettings(defaults: { provider?: string; model?: string; thinking?: "off" | "high" }) { + let currentProvider = defaults.provider; + let currentModel = defaults.model; + let currentThinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" = defaults.thinking ?? "off"; + + return { + getDefaultProvider: () => currentProvider, + getDefaultModel: () => currentModel, + getDefaultThinkingLevel: () => currentThinking, + setDefaultModelAndProvider: (provider: string, modelId: string) => { + currentProvider = provider; + currentModel = modelId; + }, + setDefaultThinkingLevel: (level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh") => { + currentThinking = level; + }, + // Expose for assertions + get _provider() { return currentProvider; }, + get _model() { return currentModel; }, + get _thinking() { return currentThinking; }, + }; +} + +// ─── Tests ────────────────────────────────────────────────────────────────── + +describe("validateConfiguredModel — regression #3534", () => { + it("preserves valid extension-provided model without overwriting", () => { + // Simulate: user configured claude-code/claude-opus-4-6, extension has registered it + const registry = createMockRegistry([ + { provider: "claude-code", id: "claude-opus-4-6" }, + { provider: "google", id: "gemini-2.5-pro" }, + ]); + const settings = createMockSettings({ provider: "claude-code", model: "claude-opus-4-6" }); + + validateConfiguredModel(registry, settings); + + // Should NOT have changed the settings — the model is valid + assert.equal(settings._provider, "claude-code"); + assert.equal(settings._model, "claude-opus-4-6"); + }); + + it("falls back when configured model ID does not exist in registry", () => { + // Simulate: user configured claude-opus-4-6[1m] but registry only has claude-opus-4-6 + const registry = createMockRegistry([ + { provider: "anthropic", id: "claude-opus-4-6" }, + { provider: "google", id: "gemini-2.5-pro" }, + ]); + const settings = createMockSettings({ provider: "anthropic", model: "claude-opus-4-6[1m]" }); + + validateConfiguredModel(registry, settings); + + // Should have replaced with a fallback — the [1m] variant doesn't exist + assert.notEqual(settings._model, "claude-opus-4-6[1m]"); + }); + + it("does not fall back to google when anthropic models are available", () => { + // Simulate: stale setting triggers fallback, anthropic should be preferred over google + const registry = createMockRegistry([ + { provider: "anthropic", id: "claude-opus-4-6" }, + { provider: "google", id: "gemini-2.5-pro" }, + ]); + const settings = createMockSettings({ provider: "anthropic", model: "nonexistent-model" }); + + validateConfiguredModel(registry, settings); + + // Should pick anthropic fallback, not google + assert.equal(settings._provider, "anthropic"); + assert.equal(settings._model, "claude-opus-4-6"); + }); + + it("resets thinking level when model is replaced", () => { + const registry = createMockRegistry([ + { provider: "anthropic", id: "claude-opus-4-6" }, + ]); + const settings = createMockSettings({ + provider: "anthropic", + model: "nonexistent-model", + thinking: "high", + }); + + validateConfiguredModel(registry, settings); + + assert.equal(settings._thinking, "off"); + }); + + it("is a no-op when no model is configured at all", () => { + const registry = createMockRegistry([ + { provider: "anthropic", id: "claude-opus-4-6" }, + { provider: "google", id: "gemini-2.5-pro" }, + ]); + const settings = createMockSettings({ provider: undefined, model: undefined }); + + validateConfiguredModel(registry, settings); + + // Should pick a fallback since nothing was configured + assert.ok(settings._provider); + assert.ok(settings._model); + }); +}); diff --git a/src/tests/tui-autocomplete-ghost-lines.test.ts b/src/tests/tui-autocomplete-ghost-lines.test.ts new file mode 100644 index 000000000..601692e2a --- /dev/null +++ b/src/tests/tui-autocomplete-ghost-lines.test.ts @@ -0,0 +1,88 @@ +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { CURSOR_MARKER, TUI, type Component, type Terminal } from "@gsd/pi-tui"; + +class MockTTYTerminal implements Terminal { + public writtenData: string[] = []; + + readonly isTTY = true; + + start(_onInput: (data: string) => void, _onResize: () => void): void {} + stop(): void {} + async drainInput(_maxMs?: number, _idleMs?: number): Promise {} + + write(data: string): void { + this.writtenData.push(data); + } + + get columns(): number { + return 80; + } + + get rows(): number { + return 24; + } + + get kittyProtocolActive(): boolean { + return false; + } + + moveBy(_lines: number): void {} + hideCursor(): void {} + showCursor(): void {} + clearLine(): void {} + clearFromCursor(): void {} + clearScreen(): void {} + setTitle(_title: string): void {} +} + +class DynamicLinesComponent implements Component { + public lines: string[]; + + constructor(lines: string[]) { + this.lines = lines; + } + + render(_width: number): string[] { + return this.lines; + } + + invalidate(): void {} +} + +describe("TUI autocomplete shrink clearing (#3721)", () => { + it("clears deleted autocomplete rows relative to the content bottom, not the IME cursor row", () => { + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + const component = new DynamicLinesComponent([ + "top border", + `prompt${CURSOR_MARKER}`, + "editor body", + "autocomplete row 1", + "autocomplete row 2", + "autocomplete row 3", + ]); + + tui.addChild(component); + (tui as any).doRender(); + + terminal.writtenData = []; + component.lines = [ + "top border", + `prompt${CURSOR_MARKER}`, + "editor body", + "autocomplete row 1", + ]; + + (tui as any).doRender(); + + assert.ok(terminal.writtenData.length >= 1, "shrink render should write a differential buffer"); + // After IME positioning, cursor is at row 1 (CURSOR_MARKER line). + // To clear deleted rows 4-5, cursor must move DOWN to content bottom (row 3), + // then clear the extra lines below. Movement is relative to actual cursor position. + assert.ok( + terminal.writtenData[0].startsWith("\x1b[?2026h\x1b[2B\r"), + `expected shrink diff to move down from IME cursor to content bottom, got ${JSON.stringify(terminal.writtenData[0])}`, + ); + }); +}); diff --git a/src/tests/tui-content-cursor-desync.test.ts b/src/tests/tui-content-cursor-desync.test.ts new file mode 100644 index 000000000..b2a99c206 --- /dev/null +++ b/src/tests/tui-content-cursor-desync.test.ts @@ -0,0 +1,318 @@ +/** + * Regression test for #3764: TUI input clears and jumps up after PR #3744. + * + * PR #3744 introduced contentCursorRow which diverged from the actual terminal + * cursor position, causing computeLineDiff to compute wrong movement deltas. + * The fix reverts to using hardwareCursorRow (actual cursor position) as the + * baseline for all cursor movement calculations. + */ + +import { describe, it } from "node:test"; +import assert from "node:assert/strict"; +import { CURSOR_MARKER, TUI, type Component, type Terminal } from "@gsd/pi-tui"; + +class MockTTYTerminal implements Terminal { + public writtenData: string[] = []; + + readonly isTTY = true; + + start(_onInput: (data: string) => void, _onResize: () => void): void {} + stop(): void {} + async drainInput(_maxMs?: number, _idleMs?: number): Promise {} + + write(data: string): void { + this.writtenData.push(data); + } + + get columns(): number { + return 80; + } + + get rows(): number { + return 24; + } + + get kittyProtocolActive(): boolean { + return false; + } + + moveBy(_lines: number): void {} + hideCursor(): void {} + showCursor(): void {} + clearLine(): void {} + clearFromCursor(): void {} + clearScreen(): void {} + setTitle(_title: string): void {} +} + +class DynamicLinesComponent implements Component { + public lines: string[]; + + constructor(lines: string[]) { + this.lines = lines; + } + + render(_width: number): string[] { + return this.lines; + } + + invalidate(): void {} +} + +describe("TUI cursor tracking regression (#3764)", () => { + it("does not produce spurious cursor jumps when content changes after IME positioning", () => { + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + const component = new DynamicLinesComponent([ + "header", + `input: hello${CURSOR_MARKER}`, + "status line", + ]); + + tui.addChild(component); + (tui as any).doRender(); + + // After first render, hardwareCursorRow is at IME position (row 1) + assert.strictEqual( + (tui as any).hardwareCursorRow, + 1, + "hardwareCursorRow should be at IME cursor position (row 1)", + ); + + // Simulate typing — content changes on the same line + terminal.writtenData = []; + component.lines = [ + "header", + `input: hello world${CURSOR_MARKER}`, + "status line", + ]; + + (tui as any).doRender(); + + assert.ok(terminal.writtenData.length >= 1, "typing should trigger a render"); + + const buffer = terminal.writtenData[0]; + // Should not contain large upward jumps (3+ rows) + const largeUpJump = buffer.match(/\x1b\[([3-9]|\d{2,})A/); + assert.strictEqual( + largeUpJump, + null, + `should not produce large upward cursor jumps, got: ${JSON.stringify(buffer)}`, + ); + }); + + it("handles editor-to-selector swap without cursor corruption", () => { + // Simulates /gsd prefs: editor with CURSOR_MARKER is replaced by + // a selector component (no CURSOR_MARKER) that has different line count. + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + + // Initial state: chat + editor with cursor marker (typical idle state) + const chatLines = Array.from({ length: 15 }, (_, i) => `chat line ${i}`); + const editorComponent = new DynamicLinesComponent([ + ...chatLines, + `> ${CURSOR_MARKER}`, // editor input line with cursor + ]); + + tui.addChild(editorComponent); + (tui as any).doRender(); + + // Cursor should be at the CURSOR_MARKER line (row 15) + assert.strictEqual( + (tui as any).hardwareCursorRow, + 15, + "hardwareCursorRow should be at editor cursor position (row 15)", + ); + + // Now swap editor for selector (simulating showExtensionSelector) + terminal.writtenData = []; + editorComponent.lines = [ + ...chatLines, + "─── Select preference ───", + "→ Model routing", + " Timeouts", + " Budget", + " Cancel", + "─────────────────────────", + ]; + + (tui as any).doRender(); + + assert.ok(terminal.writtenData.length >= 1, "selector render should produce output"); + + const buffer = terminal.writtenData[0]; + // Verify no extremely large cursor jumps that would cause visual corruption + const hugeJump = buffer.match(/\x1b\[(\d{2,})A/); + if (hugeJump) { + const jumpSize = parseInt(hugeJump[1], 10); + assert.ok( + jumpSize < 20, + `cursor jump of ${jumpSize} rows is too large — likely a baseline desync, got: ${JSON.stringify(buffer.slice(0, 200))}`, + ); + } + + // hardwareCursorRow should NOT be at old IME position + // since there's no CURSOR_MARKER in the selector + const hwRow = (tui as any).hardwareCursorRow; + assert.ok( + hwRow >= 15 && hwRow <= 20, + `hardwareCursorRow should be at rendered content (${hwRow}), not stuck at old IME position`, + ); + + // Now simulate user pressing ↓ in selector (one line changes) + terminal.writtenData = []; + editorComponent.lines = [ + ...chatLines, + "─── Select preference ───", + " Model routing", + "→ Timeouts", + " Budget", + " Cancel", + "─────────────────────────", + ]; + + (tui as any).doRender(); + + if (terminal.writtenData.length > 0) { + const navBuffer = terminal.writtenData[0]; + // The differential render should only update the 2 changed lines (16 and 17) + // Verify no large upward jumps from wrong baseline + const navJump = navBuffer.match(/\x1b\[(\d{2,})A/); + if (navJump) { + const jumpSize = parseInt(navJump[1], 10); + assert.ok( + jumpSize < 20, + `navigation caused jump of ${jumpSize} rows — cursor baseline may be wrong`, + ); + } + } + }); + + it("handles selector-to-editor swap restoring cursor correctly", () => { + // After dismissing a selector, the editor returns with CURSOR_MARKER. + // The cursor must move to the new marker position without corruption. + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + + const chatLines = Array.from({ length: 10 }, (_, i) => `chat ${i}`); + const component = new DynamicLinesComponent([ + ...chatLines, + "─── Selector ───", + "→ Option A", + " Option B", + "────────────────", + ]); + + tui.addChild(component); + (tui as any).doRender(); + + // No CURSOR_MARKER → cursor stays at last rendered line + const hwRowAfterSelector = (tui as any).hardwareCursorRow; + + // Swap back to editor with CURSOR_MARKER + terminal.writtenData = []; + component.lines = [ + ...chatLines, + `> ${CURSOR_MARKER}`, + ]; + + (tui as any).doRender(); + + // CURSOR_MARKER is at row 10 — cursor should be positioned there + assert.strictEqual( + (tui as any).hardwareCursorRow, + 10, + "hardwareCursorRow should move to editor cursor after selector dismiss", + ); + }); + + it("handles input component swap (prefs wizard text input)", () => { + // Simulates /gsd prefs input step: selector replaced by text input with cursor + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + + const chatLines = Array.from({ length: 8 }, (_, i) => `msg ${i}`); + const component = new DynamicLinesComponent([ + ...chatLines, + "─── Enter value ───", + `Value: ${CURSOR_MARKER}`, + "───────────────────", + ]); + + tui.addChild(component); + (tui as any).doRender(); + + assert.strictEqual( + (tui as any).hardwareCursorRow, + 9, + "hardwareCursorRow should be at input cursor (row 9)", + ); + + // Simulate typing in the input + terminal.writtenData = []; + component.lines = [ + ...chatLines, + "─── Enter value ───", + `Value: hello${CURSOR_MARKER}`, + "───────────────────", + ]; + + (tui as any).doRender(); + + assert.ok(terminal.writtenData.length >= 1, "typing should trigger render"); + + const buffer = terminal.writtenData[0]; + // Should not jump to wrong row — only line 9 changed + const upJump = buffer.match(/\x1b\[(\d+)A/); + if (upJump) { + const jumpSize = parseInt(upJump[1], 10); + // Cursor was at row 9 (IME), need to go to row 9 (changed line) = no jump needed + assert.ok(jumpSize <= 1, `typing in input caused unexpected up-jump of ${jumpSize}`); + } + + assert.strictEqual( + (tui as any).hardwareCursorRow, + 9, + "hardwareCursorRow should stay at input cursor after typing", + ); + }); + + it("hardwareCursorRow tracks actual terminal position through IME and shrink", () => { + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal, false); + const component = new DynamicLinesComponent([ + "line 1", + `line 2${CURSOR_MARKER}`, + "line 3", + "line 4", + "line 5", + ]); + + tui.addChild(component); + (tui as any).doRender(); + + // After IME positioning, hardwareCursorRow is at CURSOR_MARKER line (row 1) + assert.strictEqual( + (tui as any).hardwareCursorRow, + 1, + "hardwareCursorRow should be at IME position (row 1) after first render", + ); + + // Shrink content + terminal.writtenData = []; + component.lines = [ + "line 1", + `line 2${CURSOR_MARKER}`, + "line 3", + ]; + + (tui as any).doRender(); + + // After shrink, hardwareCursorRow should be at IME position again + assert.strictEqual( + (tui as any).hardwareCursorRow, + 1, + "hardwareCursorRow should be at IME position after shrink render", + ); + }); +}); diff --git a/src/tests/tui-non-tty-render-loop.test.ts b/src/tests/tui-non-tty-render-loop.test.ts new file mode 100644 index 000000000..2e6e4677d --- /dev/null +++ b/src/tests/tui-non-tty-render-loop.test.ts @@ -0,0 +1,143 @@ +/** + * Test: RPC bridge TUI render loop must not burn CPU on non-TTY stdout. + * + * When gsd is spawned as an RPC bridge child process, stdout is a pipe + * (process.stdout.isTTY === undefined). The TUI render loop must not + * start in that scenario — otherwise it runs at ~4,600 renders/second + * consuming 500%+ CPU doing nothing useful. + * + * Regression test for: https://github.com/gsd-build/gsd-2/issues/3095 + */ +import { describe, it, beforeEach } from "node:test"; +import assert from "node:assert/strict"; +import { ProcessTerminal } from "@gsd/pi-tui"; +import { TUI } from "@gsd/pi-tui"; +import type { Terminal } from "@gsd/pi-tui"; + +/** + * A mock terminal that tracks writes and render activity. + * Simulates a non-TTY environment (isTTY = false). + */ +class MockNonTTYTerminal implements Terminal { + public started = false; + public writeCount = 0; + public writtenData: string[] = []; + private _onInput?: (data: string) => void; + private _onResize?: () => void; + + /** Simulates non-TTY stdout */ + readonly isTTY = false; + + start(onInput: (data: string) => void, onResize: () => void): void { + this.started = true; + this._onInput = onInput; + this._onResize = onResize; + } + + stop(): void { + this.started = false; + } + + async drainInput(_maxMs?: number, _idleMs?: number): Promise {} + + write(data: string): void { + this.writeCount++; + this.writtenData.push(data); + } + + get columns(): number { return 80; } + get rows(): number { return 24; } + get kittyProtocolActive(): boolean { return false; } + + moveBy(_lines: number): void {} + hideCursor(): void {} + showCursor(): void {} + clearLine(): void {} + clearFromCursor(): void {} + clearScreen(): void {} + setTitle(_title: string): void {} +} + +/** + * A mock terminal that behaves like a real TTY. + */ +class MockTTYTerminal extends MockNonTTYTerminal { + override readonly isTTY = true as const; +} + +describe("TUI non-TTY render loop guard (issue #3095)", () => { + it("ProcessTerminal.start() should be a no-op when stdout is not a TTY", () => { + // ProcessTerminal.start() accesses process.stdout directly. + // We verify it exposes isTTY so callers can check before starting. + const terminal = new ProcessTerminal(); + // ProcessTerminal.isTTY should reflect process.stdout.isTTY + assert.equal( + typeof terminal.isTTY, + "boolean", + "ProcessTerminal must expose an isTTY property" + ); + }); + + it("TUI.start() must not render when terminal.isTTY is false", async () => { + const terminal = new MockNonTTYTerminal(); + const tui = new TUI(terminal); + + tui.start(); + + // Wait for any nextTick-scheduled renders to fire + await new Promise((resolve) => setTimeout(resolve, 50)); + + // The TUI should NOT have produced any render output on a non-TTY terminal + assert.equal( + terminal.writeCount, + 0, + `TUI rendered ${terminal.writeCount} times on non-TTY stdout — ` + + `this would cause the CPU burn described in #3095. ` + + `Expected 0 writes when isTTY is false.` + ); + + // Clean up + tui.stop(); + }); + + it("TUI.start() renders normally when terminal.isTTY is true", async () => { + const terminal = new MockTTYTerminal(); + const tui = new TUI(terminal); + + tui.start(); + + // Wait for nextTick-scheduled render + await new Promise((resolve) => setTimeout(resolve, 50)); + + // On a TTY terminal, at least one render should have occurred + assert.ok( + terminal.writeCount > 0, + "TUI should render at least once on a TTY terminal" + ); + + tui.stop(); + }); + + it("requestRender() must be a no-op when terminal.isTTY is false", async () => { + const terminal = new MockNonTTYTerminal(); + const tui = new TUI(terminal); + + tui.start(); + + // Force multiple render requests + tui.requestRender(); + tui.requestRender(); + tui.requestRender(); + + // Wait for any scheduled renders + await new Promise((resolve) => setTimeout(resolve, 50)); + + assert.equal( + terminal.writeCount, + 0, + "requestRender() must not write to non-TTY stdout" + ); + + tui.stop(); + }); +}); diff --git a/src/tests/update-check.test.ts b/src/tests/update-check.test.ts index caa712533..40d2c5f28 100644 --- a/src/tests/update-check.test.ts +++ b/src/tests/update-check.test.ts @@ -5,7 +5,7 @@ import { join } from 'node:path' import { tmpdir } from 'node:os' import { createServer } from 'node:http' -import { compareSemver, readUpdateCache, writeUpdateCache, checkForUpdates } from '../update-check.js' +import { compareSemver, readUpdateCache, writeUpdateCache, checkForUpdates, fetchLatestVersionFromRegistry } from '../update-check.js' // --------------------------------------------------------------------------- // compareSemver @@ -315,3 +315,23 @@ test('checkForUpdates handles missing version field in response', async (t) => { assert.ok(!called, 'onUpdate should not be called when response has no version') }) + +test('fetchLatestVersionFromRegistry returns the registry version string', async (t) => { + const registry = await startMockRegistry({ version: '2.67.0' }) + t.after(async () => { + await registry.close() + }) + + const latest = await fetchLatestVersionFromRegistry(registry.url, 5000) + assert.equal(latest, '2.67.0') +}) + +test('fetchLatestVersionFromRegistry returns null for blank version strings', async (t) => { + const registry = await startMockRegistry({ version: '' }) + t.after(async () => { + await registry.close() + }) + + const latest = await fetchLatestVersionFromRegistry(registry.url, 5000) + assert.equal(latest, null) +}) diff --git a/src/tests/update-cmd-diagnostics.test.ts b/src/tests/update-cmd-diagnostics.test.ts new file mode 100644 index 000000000..8f3c5c088 --- /dev/null +++ b/src/tests/update-cmd-diagnostics.test.ts @@ -0,0 +1,34 @@ +/** + * Regression test for #3445: gsd update must print both current and latest + * versions for diagnostics, and bypass npm cache. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +test("update-cmd prints latest version before comparison (#3445)", () => { + const src = readFileSync(join(__dirname, "..", "update-cmd.ts"), "utf-8"); + const latestPrintIdx = src.indexOf("Latest version:"); + const comparisonIdx = src.indexOf("compareSemver(latest, current)"); + assert.ok(latestPrintIdx !== -1, "Must print latest version"); + assert.ok(latestPrintIdx < comparisonIdx, "Must print latest BEFORE comparison"); +}); + +test("update commands use the registry fetch helper instead of npm view (#3806)", () => { + const src = readFileSync(join(__dirname, "..", "update-cmd.ts"), "utf-8"); + const handlerSrc = readFileSync(join(__dirname, "..", "resources", "extensions", "gsd", "commands-handlers.ts"), "utf-8"); + assert.ok( + src.includes("fetchLatestVersionFromRegistry"), + "update-cmd should use the shared registry fetch helper", + ); + assert.ok(!src.includes("npm view "), "update-cmd should no longer shell out to npm view"); + assert.ok( + handlerSrc.includes("fetchLatestVersionForCommand"), + "/gsd update should fetch the latest version through a registry helper too", + ); + assert.ok(!handlerSrc.includes("npm view "), "/gsd update should no longer shell out to npm view"); +}); diff --git a/src/tests/url-utils.test.ts b/src/tests/url-utils.test.ts index c73b359a7..300dbd084 100644 --- a/src/tests/url-utils.test.ts +++ b/src/tests/url-utils.test.ts @@ -1,6 +1,6 @@ -import { describe, it } from "node:test"; +import { describe, it, afterEach } from "node:test"; import assert from "node:assert/strict"; -import { isBlockedUrl } from "../resources/extensions/search-the-web/url-utils.ts"; +import { isBlockedUrl, setFetchAllowedUrls, getFetchAllowedUrls } from "../resources/extensions/search-the-web/url-utils.ts"; describe("isBlockedUrl — SSRF protection", () => { it("blocks localhost", () => { @@ -57,3 +57,70 @@ describe("isBlockedUrl — SSRF protection", () => { assert.equal(isBlockedUrl("https://1.1.1.1/"), false); }); }); + +describe("REGRESSION #666: private URL blocked with no override", () => { + afterEach(() => { + setFetchAllowedUrls([]); + }); + + it("private IP is blocked by default, then unblocked by setFetchAllowedUrls", () => { + const internalUrl = "http://192.168.1.100/internal-docs/api-reference"; + + // Bug: private IP is blocked with no way to allowlist + assert.equal(isBlockedUrl(internalUrl), true, "private IP is blocked by the hardcoded blocklist"); + + // Fix: override the allowlist to include this host + setFetchAllowedUrls(["192.168.1.100"]); + assert.equal(isBlockedUrl(internalUrl), false, "private IP must not be blocked after override"); + }); +}); + +describe("setFetchAllowedUrls — user override", () => { + afterEach(() => { + setFetchAllowedUrls([]); + }); + + it("defaults to empty allowlist", () => { + assert.deepEqual(getFetchAllowedUrls(), []); + }); + + it("exempts an allowed hostname from blocking", () => { + assert.equal(isBlockedUrl("http://192.168.1.100/docs"), true, "blocked by default"); + setFetchAllowedUrls(["192.168.1.100"]); + assert.equal(isBlockedUrl("http://192.168.1.100/docs"), false, "allowed after override"); + }); + + it("exempts localhost when explicitly allowed", () => { + assert.equal(isBlockedUrl("http://localhost:3000/api"), true, "blocked by default"); + setFetchAllowedUrls(["localhost"]); + assert.equal(isBlockedUrl("http://localhost:3000/api"), false, "allowed after override"); + }); + + it("exempts cloud metadata hostname when allowed", () => { + assert.equal(isBlockedUrl("http://metadata.google.internal/computeMetadata/"), true, "blocked by default"); + setFetchAllowedUrls(["metadata.google.internal"]); + assert.equal(isBlockedUrl("http://metadata.google.internal/computeMetadata/"), false, "allowed after override"); + }); + + it("does not affect URLs not in the allowlist", () => { + setFetchAllowedUrls(["192.168.1.100"]); + assert.equal(isBlockedUrl("http://192.168.1.200/secret"), true, "other private IPs still blocked"); + assert.equal(isBlockedUrl("http://localhost/admin"), true, "localhost still blocked"); + }); + + it("still allows public URLs without configuration", () => { + setFetchAllowedUrls(["192.168.1.100"]); + assert.equal(isBlockedUrl("https://example.com"), false); + }); + + it("still blocks non-HTTP protocols even with allowlist", () => { + setFetchAllowedUrls(["localhost"]); + assert.equal(isBlockedUrl("file:///etc/passwd"), true, "file:// still blocked"); + assert.equal(isBlockedUrl("ftp://localhost/data"), true, "ftp:// still blocked"); + }); + + it("is case-insensitive for hostnames", () => { + setFetchAllowedUrls(["MyHost.Internal"]); + assert.equal(isBlockedUrl("http://myhost.internal/api"), false); + }); +}); \ No newline at end of file diff --git a/src/tests/web-subprocess-runner.test.ts b/src/tests/web-subprocess-runner.test.ts new file mode 100644 index 000000000..ab3004619 --- /dev/null +++ b/src/tests/web-subprocess-runner.test.ts @@ -0,0 +1,177 @@ +import test from "node:test" +import assert from "node:assert/strict" + +const { runSubprocess, resolveModulePaths } = await import("../web/subprocess-runner.ts") + +// --------------------------------------------------------------------------- +// resolveModulePaths — centralised TS loader + module path resolution +// --------------------------------------------------------------------------- + +test("resolveModulePaths returns tsLoaderPath and validates it exists", () => { + const packageRoot = "/fake/package" + const result = resolveModulePaths(packageRoot, { + modules: [{ envKey: "MOD", relativePath: "src/mod.ts" }], + existsSync: () => true, + }) + assert.equal( + result.tsLoaderPath, + "/fake/package/src/resources/extensions/gsd/tests/resolve-ts.mjs", + ) +}) + +test("resolveModulePaths throws when TS loader is missing", () => { + const packageRoot = "/fake/package" + assert.throws( + () => + resolveModulePaths(packageRoot, { + modules: [{ envKey: "MOD", relativePath: "src/mod.ts" }], + existsSync: () => false, + label: "test-service", + }), + (error: Error) => { + assert.match(error.message, /test-service/) + assert.match(error.message, /not found/) + return true + }, + ) +}) + +test("resolveModulePaths throws when any module path is missing", () => { + const packageRoot = "/fake/package" + const existingSets = new Set([ + "/fake/package/src/resources/extensions/gsd/tests/resolve-ts.mjs", + ]) + assert.throws( + () => + resolveModulePaths(packageRoot, { + modules: [ + { envKey: "MOD_A", relativePath: "src/a.ts" }, + { envKey: "MOD_B", relativePath: "src/b.ts" }, + ], + existsSync: (p: string) => existingSets.has(p), + label: "multi-mod", + }), + (error: Error) => { + assert.match(error.message, /multi-mod/) + return true + }, + ) +}) + +test("resolveModulePaths returns env entries for each module", () => { + const packageRoot = "/fake/package" + const result = resolveModulePaths(packageRoot, { + modules: [ + { envKey: "GSD_MOD_A", relativePath: "src/a.ts" }, + { envKey: "GSD_MOD_B", relativePath: "src/b.ts" }, + ], + existsSync: () => true, + }) + assert.deepEqual(result.env, { + GSD_MOD_A: "/fake/package/src/a.ts", + GSD_MOD_B: "/fake/package/src/b.ts", + }) +}) + +// --------------------------------------------------------------------------- +// runSubprocess — shared execFile + JSON.parse wrapper +// --------------------------------------------------------------------------- + +test("runSubprocess returns parsed JSON from a child process", async () => { + const result = await runSubprocess<{ hello: string }>({ + packageRoot: process.cwd(), + script: 'process.stdout.write(JSON.stringify({ hello: "world" }));', + env: {}, + label: "test", + }) + assert.deepEqual(result, { hello: "world" }) +}) + +test("runSubprocess rejects when child process exits with error", async () => { + await assert.rejects( + () => + runSubprocess({ + packageRoot: process.cwd(), + script: 'process.exit(1);', + env: {}, + label: "exit-test", + }), + (error: Error) => { + assert.match(error.message, /exit-test/) + assert.match(error.message, /subprocess failed/) + return true + }, + ) +}) + +test("runSubprocess rejects on invalid JSON output", async () => { + await assert.rejects( + () => + runSubprocess({ + packageRoot: process.cwd(), + script: 'process.stdout.write("not json");', + env: {}, + label: "json-test", + }), + (error: Error) => { + assert.match(error.message, /json-test/) + assert.match(error.message, /invalid JSON/) + return true + }, + ) +}) + +test("runSubprocess applies timeout option", async () => { + await assert.rejects( + () => + runSubprocess({ + packageRoot: process.cwd(), + script: 'setTimeout(() => {}, 60000);', + env: {}, + label: "timeout-test", + timeoutMs: 500, + }), + (error: Error) => { + assert.match(error.message, /timeout-test/) + return true + }, + ) +}) + +test("runSubprocess accepts custom maxBuffer", async () => { + // Verify it does not throw with a reasonable buffer + const result = await runSubprocess<{ ok: boolean }>({ + packageRoot: process.cwd(), + script: 'process.stdout.write(JSON.stringify({ ok: true }));', + env: {}, + label: "buffer-test", + maxBuffer: 512, + }) + assert.equal(result.ok, true) +}) + +test("runSubprocess passes env vars to child process", async () => { + const result = await runSubprocess<{ val: string }>({ + packageRoot: process.cwd(), + script: 'process.stdout.write(JSON.stringify({ val: process.env.TEST_VAR }));', + env: { TEST_VAR: "hello_from_parent" }, + label: "env-test", + }) + assert.equal(result.val, "hello_from_parent") +}) + +test("runSubprocess includes stderr in error message on failure", async () => { + await assert.rejects( + () => + runSubprocess({ + packageRoot: process.cwd(), + script: 'process.stderr.write("detailed error info"); process.exit(1);', + env: {}, + label: "stderr-test", + }), + (error: Error) => { + assert.match(error.message, /detailed error info/) + return true + }, + ) +}) diff --git a/src/tests/welcome-screen.test.ts b/src/tests/welcome-screen.test.ts index cfea992c5..dcc7f8105 100644 --- a/src/tests/welcome-screen.test.ts +++ b/src/tests/welcome-screen.test.ts @@ -71,3 +71,30 @@ test('renders without model or provider', () => { const out = strip(capture({ version: '3.0.0' })) assert.ok(out.includes('v3.0.0'), 'version missing when no model provided') }) + +test('renders remote channel in tools row', () => { + const out = strip(capture({ version: '1.0.0', remoteChannel: 'discord' })) + assert.ok(out.includes('Discord'), 'remote channel name missing') +}) + +test('omits remote channel when not provided', () => { + const out = strip(capture({ version: '1.0.0' })) + assert.ok(!out.includes('Discord'), 'should not show Discord when no remote') + assert.ok(!out.includes('Slack'), 'should not show Slack when no remote') + assert.ok(!out.includes('Telegram'), 'should not show Telegram when no remote') +}) + +test('separator lines extend to full terminal width on wide terminals', (t) => { + const origColumns = process.stderr.columns + ;(process.stderr as any).columns = 250 + t.after(() => { ;(process.stderr as any).columns = origColumns }) + + const out = strip(capture({ version: '1.0.0' })) + const lines = out.split('\n') + // Top and bottom separator bars should be 249 chars (columns - 1) + const separatorLines = lines.filter(l => /^─+$/.test(l.trim())) + assert.ok(separatorLines.length >= 2, 'expected at least 2 full-width separator lines') + for (const sep of separatorLines) { + assert.equal(sep.trim().length, 249, `separator should be 249 chars wide, got ${sep.trim().length}`) + } +}) diff --git a/src/tests/windows-portability.test.ts b/src/tests/windows-portability.test.ts new file mode 100644 index 000000000..30dbde0e5 --- /dev/null +++ b/src/tests/windows-portability.test.ts @@ -0,0 +1,78 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { resolveLocalBinaryPath } from "../../packages/pi-coding-agent/src/core/lsp/config.ts"; +import { encodeCwd } from "../resources/extensions/subagent/isolation.ts"; + +function makeTempDir(prefix: string): string { + const dir = path.join( + os.tmpdir(), + `gsd-windows-portability-${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, + ); + mkdirSync(dir, { recursive: true }); + return dir; +} + +test("resolveLocalBinaryPath finds Windows npm shims", () => { + const dir = makeTempDir("lsp-shim"); + try { + writeFileSync(path.join(dir, "package.json"), "{}"); + mkdirSync(path.join(dir, "node_modules", ".bin"), { recursive: true }); + const shimPath = path.join(dir, "node_modules", ".bin", "tsc.cmd"); + writeFileSync(shimPath, "@echo off\r\n"); + + const resolved = resolveLocalBinaryPath("tsc", dir, true); + assert.equal(resolved, shimPath); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("resolveLocalBinaryPath finds Windows venv Scripts executables", () => { + const dir = makeTempDir("lsp-scripts"); + try { + writeFileSync(path.join(dir, "pyproject.toml"), ""); + mkdirSync(path.join(dir, "venv", "Scripts"), { recursive: true }); + const exePath = path.join(dir, "venv", "Scripts", "python.exe"); + writeFileSync(exePath, ""); + + const resolved = resolveLocalBinaryPath("python", dir, true); + assert.equal(resolved, exePath); + } finally { + rmSync(dir, { recursive: true, force: true }); + } +}); + +test("encodeCwd produces a filesystem-safe token for Windows paths", () => { + const encoded = encodeCwd("C:\\Users\\Alice\\repo"); + assert.match(encoded, /^[A-Za-z0-9_-]+$/); + assert.ok(!encoded.includes(":")); + assert.ok(!encoded.includes("\\")); + assert.ok(!encoded.includes("/")); +}); + +test("Windows launch points use shell-safe shims", () => { + const gsdClient = readFileSync( + path.join(process.cwd(), "vscode-extension", "src", "gsd-client.ts"), + "utf8", + ); + const updateService = readFileSync( + path.join(process.cwd(), "src", "web", "update-service.ts"), + "utf8", + ); + const preExecution = readFileSync( + path.join(process.cwd(), "src", "resources", "extensions", "gsd", "pre-execution-checks.ts"), + "utf8", + ); + const validatePack = readFileSync( + path.join(process.cwd(), "scripts", "validate-pack.js"), + "utf8", + ); + + assert.match(gsdClient, /shell:\s*process\.platform === "win32"/); + assert.match(updateService, /npm\.cmd/); + assert.match(preExecution, /npm\.cmd/); + assert.match(validatePack, /shell:\s*process\.platform === 'win32'/); +}); diff --git a/src/update-check.ts b/src/update-check.ts index 784eeb900..d560c318b 100644 --- a/src/update-check.ts +++ b/src/update-check.ts @@ -8,6 +8,7 @@ const CACHE_FILE = join(appRoot, '.update-check') const NPM_PACKAGE_NAME = 'gsd-pi' const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000 // 24 hours const FETCH_TIMEOUT_MS = 5000 +const DEFAULT_REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest` interface UpdateCheckCache { lastCheck: number @@ -47,6 +48,32 @@ export function writeUpdateCache(cache: UpdateCheckCache, cachePath: string = CA } } +function normalizeLatestVersion(version: unknown): string | null { + if (typeof version !== 'string') return null + const trimmed = version.trim().replace(/^v/, '') + return trimmed.length > 0 ? trimmed : null +} + +export async function fetchLatestVersionFromRegistry( + registryUrl: string = DEFAULT_REGISTRY_URL, + fetchTimeoutMs: number = FETCH_TIMEOUT_MS, +): Promise { + const controller = new AbortController() + const timeout = setTimeout(() => controller.abort(), fetchTimeoutMs) + + try { + const res = await fetch(registryUrl, { signal: controller.signal }) + if (!res.ok) return null + + const data = (await res.json()) as { version?: string } + return normalizeLatestVersion(data.version) + } catch { + return null + } finally { + clearTimeout(timeout) + } +} + function printUpdateBanner(current: string, latest: string): void { process.stderr.write( ` ${chalk.yellow('Update available:')} ${chalk.dim(`v${current}`)} → ${chalk.bold(`v${latest}`)}\n` + @@ -70,7 +97,7 @@ export interface UpdateCheckOptions { export async function checkForUpdates(options: UpdateCheckOptions = {}): Promise { const currentVersion = options.currentVersion || process.env.GSD_VERSION || '0.0.0' const cachePath = options.cachePath || CACHE_FILE - const registryUrl = options.registryUrl || `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest` + const registryUrl = options.registryUrl || DEFAULT_REGISTRY_URL const checkIntervalMs = options.checkIntervalMs ?? CHECK_INTERVAL_MS const fetchTimeoutMs = options.fetchTimeoutMs ?? FETCH_TIMEOUT_MS const onUpdate = options.onUpdate || printUpdateBanner @@ -84,18 +111,8 @@ export async function checkForUpdates(options: UpdateCheckOptions = {}): Promise return } - // Fetch latest version from npm registry - const controller = new AbortController() - const timeout = setTimeout(() => controller.abort(), fetchTimeoutMs) - try { - const res = await fetch(registryUrl, { signal: controller.signal }) - clearTimeout(timeout) - - if (!res.ok) return - - const data = (await res.json()) as { version?: string } - const latestVersion = data.version + const latestVersion = await fetchLatestVersionFromRegistry(registryUrl, fetchTimeoutMs) if (!latestVersion) return writeUpdateCache({ lastCheck: Date.now(), latestVersion }, cachePath) @@ -105,8 +122,6 @@ export async function checkForUpdates(options: UpdateCheckOptions = {}): Promise } } catch { // Network error or timeout — silently ignore, don't block startup - } finally { - clearTimeout(timeout) } } @@ -123,7 +138,7 @@ const PROMPT_TIMEOUT_MS = 30_000 export async function checkAndPromptForUpdates(options: UpdateCheckOptions = {}): Promise { const currentVersion = options.currentVersion || process.env.GSD_VERSION || '0.0.0' const cachePath = options.cachePath || CACHE_FILE - const registryUrl = options.registryUrl || `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest` + const registryUrl = options.registryUrl || DEFAULT_REGISTRY_URL const checkIntervalMs = options.checkIntervalMs ?? CHECK_INTERVAL_MS const fetchTimeoutMs = options.fetchTimeoutMs ?? FETCH_TIMEOUT_MS @@ -134,22 +149,13 @@ export async function checkAndPromptForUpdates(options: UpdateCheckOptions = {}) if (cache && Date.now() - cache.lastCheck < checkIntervalMs) { latestVersion = cache.latestVersion } else { - const controller = new AbortController() - const timeout = setTimeout(() => controller.abort(), fetchTimeoutMs) try { - const res = await fetch(registryUrl, { signal: controller.signal }) - clearTimeout(timeout) - if (res.ok) { - const data = (await res.json()) as { version?: string } - if (data.version) { - latestVersion = data.version - writeUpdateCache({ lastCheck: Date.now(), latestVersion }, cachePath) - } + latestVersion = await fetchLatestVersionFromRegistry(registryUrl, fetchTimeoutMs) + if (latestVersion) { + writeUpdateCache({ lastCheck: Date.now(), latestVersion }, cachePath) } } catch { // Network unavailable — silently skip - } finally { - clearTimeout(timeout) } } diff --git a/src/update-cmd.ts b/src/update-cmd.ts index ac16a8209..18dcd0c48 100644 --- a/src/update-cmd.ts +++ b/src/update-cmd.ts @@ -1,5 +1,5 @@ import { execSync } from 'node:child_process' -import { compareSemver } from './update-check.js' +import { compareSemver, fetchLatestVersionFromRegistry } from './update-check.js' const NPM_PACKAGE = 'gsd-pi' @@ -14,18 +14,14 @@ export async function runUpdate(): Promise { process.stdout.write(`${dim}Current version:${reset} v${current}\n`) process.stdout.write(`${dim}Checking npm registry...${reset}\n`) - // Fetch latest version - let latest: string - try { - latest = execSync(`npm view ${NPM_PACKAGE} version`, { - encoding: 'utf-8', - stdio: ['ignore', 'pipe', 'ignore'], - }).trim() - } catch { + const latest = await fetchLatestVersionFromRegistry() + if (!latest) { process.stderr.write(`${yellow}Failed to reach npm registry.${reset}\n`) process.exit(1) } + process.stdout.write(`${dim}Latest version:${reset} v${latest}\n`) + if (compareSemver(latest, current) <= 0) { process.stdout.write(`${green}Already up to date.${reset}\n`) return diff --git a/src/web-mode.ts b/src/web-mode.ts index 42683a667..3d917431c 100644 --- a/src/web-mode.ts +++ b/src/web-mode.ts @@ -14,7 +14,7 @@ const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '. function openBrowser(url: string): void { if (process.platform === 'win32') { // PowerShell's Start-Process handles URLs with '&' safely; cmd /c start does not. - execFile('powershell', ['-c', `Start-Process '${url.replace(/'/g, "''")}'`], () => {}) + execFile('powershell', ['-c', `Start-Process '${url.replace(/'/g, "''")}'`], { windowsHide: true }, () => {}) } else { const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open' execFile(cmd, [url], () => {}) @@ -353,6 +353,10 @@ function getSpawnCommandForSourceHost(platform: NodeJS.Platform): string { return platform === 'win32' ? 'npm.cmd' : 'npm' } +function needsWindowsShell(command: string, platform: NodeJS.Platform): boolean { + return platform === 'win32' && /\.(cmd|bat)$/i.test(command) +} + function formatLaunchStatus(status: WebModeLaunchStatus): string { if (status.ok) { return `[gsd] Web mode startup: status=started cwd=${status.cwd} port=${status.port} host=${status.hostPath} kind=${status.hostKind} url=${status.url}\n` @@ -635,6 +639,8 @@ export async function launchWebMode( cwd: spawnSpec.cwd, detached: true, stdio: 'ignore', + windowsHide: true, + shell: needsWindowsShell(spawnSpec.command, deps.platform ?? process.platform), env, }, ) diff --git a/src/web/auto-dashboard-service.ts b/src/web/auto-dashboard-service.ts index 31afe3ef8..972c7474f 100644 --- a/src/web/auto-dashboard-service.ts +++ b/src/web/auto-dashboard-service.ts @@ -1,5 +1,5 @@ import { execFile } from "node:child_process"; -import { existsSync } from "node:fs"; +import { existsSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { pathToFileURL } from "node:url"; @@ -42,6 +42,64 @@ export function collectTestOnlyFallbackAutoDashboardData(): AutoDashboardData { return fallbackAutoDashboardData(); } +/** + * Check if a PID is alive by sending signal 0. + */ +function isPidAlive(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch { + return false; + } +} + +/** + * Reconcile subprocess auto dashboard data with on-disk session state. + * + * The subprocess always starts with fresh module state (s.active === false), + * so it can never report active/paused correctly. We check: + * 1. .gsd/auto.lock — if present and its PID is alive, auto IS running. + * 2. .gsd/runtime/paused-session.json — if present, auto IS paused. + * + * See #2705. + */ +function reconcileWithDiskState( + data: AutoDashboardData, + projectCwd: string, + checkExists: (path: string) => boolean, +): AutoDashboardData { + // If the subprocess already reports active or paused, trust it. + if (data.active || data.paused) return data; + + // Check for paused-session.json first (paused takes precedence). + const pausedPath = join(projectCwd, ".gsd", "runtime", "paused-session.json"); + if (checkExists(pausedPath)) { + try { + // Validate the file is readable JSON (not corrupt). + JSON.parse(readFileSync(pausedPath, "utf-8")); + return { ...data, paused: true }; + } catch { + // Corrupt or unreadable — ignore. + } + } + + // Check for session lock with a live PID. + const lockPath = join(projectCwd, ".gsd", "auto.lock"); + if (checkExists(lockPath)) { + try { + const lockData = JSON.parse(readFileSync(lockPath, "utf-8")) as { pid?: number }; + if (typeof lockData.pid === "number" && isPidAlive(lockData.pid)) { + return { ...data, active: true }; + } + } catch { + // Corrupt or unreadable — ignore. + } + } + + return data; +} + export async function collectAuthoritativeAutoDashboardData( packageRoot: string, options: AutoDashboardServiceOptions = {}, @@ -95,6 +153,7 @@ export async function collectAuthoritativeAutoDashboardData( [AUTO_DASHBOARD_MODULE_ENV]: autoModulePath, }, maxBuffer: AUTO_DASHBOARD_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { @@ -103,7 +162,12 @@ export async function collectAuthoritativeAutoDashboardData( } try { - resolveResult(JSON.parse(stdout) as AutoDashboardData); + const parsed = JSON.parse(stdout) as AutoDashboardData; + const projectCwd = env.GSD_WEB_PROJECT_CWD || ""; + const reconciled = projectCwd + ? reconcileWithDiskState(parsed, projectCwd, checkExists) + : parsed; + resolveResult(reconciled); } catch (parseError) { reject( new Error( diff --git a/src/web/bridge-service.ts b/src/web/bridge-service.ts index f1faac3aa..b5f87cdce 100644 --- a/src/web/bridge-service.ts +++ b/src/web/bridge-service.ts @@ -2,9 +2,10 @@ import { execFile, spawn, type ChildProcess, type SpawnOptions } from "node:chil import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"; import { StringDecoder } from "node:string_decoder"; import type { Readable } from "node:stream"; -import { join, resolve, dirname } from "node:path"; -import { fileURLToPath, pathToFileURL } from "node:url"; +import { join, resolve } from "node:path"; +import { pathToFileURL } from "node:url"; import { resolveTypeStrippingFlag, resolveSubprocessModule, buildSubprocessPrefixArgs } from "./ts-subprocess-flags.ts"; +import { safePackageRootFromImportUrl } from "./safe-import-meta-resolve.ts"; import type { AgentSessionEvent, SessionStateChangeReason } from "../../packages/pi-coding-agent/src/core/agent-session.ts"; import type { @@ -39,23 +40,14 @@ import { } from "./auto-dashboard-service.ts"; import { resolveGsdCliEntry } from "./cli-entry.ts"; -// Lazily computed fallback — import.meta.url is baked in at build time by -// webpack, so when the standalone bundle built on Linux CI runs on Windows the -// literal file:// URL contains a Unix path that fileURLToPath() rejects. -// Deferring the computation means it only fires when GSD_WEB_PACKAGE_ROOT is -// absent, and if it does fire we handle the cross-platform failure gracefully. +// The standalone Next.js bundle bakes import.meta.url at build time with the +// CI runner's absolute path. On Windows, fileURLToPath() rejects a Linux +// file:// URL at module load time. Use a lazy getter so the derivation is +// deferred to first use (not module load) and falls back to cwd on failure. let _defaultPackageRoot: string | undefined; function getDefaultPackageRoot(): string { if (_defaultPackageRoot !== undefined) return _defaultPackageRoot; - try { - _defaultPackageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../.."); - } catch { - // Standalone bundle running on a different OS than the builder — the - // baked-in import.meta.url is not a valid local file URL. Fall back to - // cwd which is the best available approximation; callers that need the - // real package root should set GSD_WEB_PACKAGE_ROOT. - _defaultPackageRoot = process.cwd(); - } + _defaultPackageRoot = safePackageRootFromImportUrl(import.meta.url) ?? process.cwd(); return _defaultPackageRoot; } @@ -63,6 +55,7 @@ function getDefaultPackageRoot(): string { export function resetDefaultPackageRootForTests(): void { _defaultPackageRoot = undefined; } + const RESPONSE_TIMEOUT_MS = 30_000; const START_TIMEOUT_MS = 150_000; const MAX_STDERR_BUFFER = 8_000; @@ -659,6 +652,7 @@ export type BridgeLiveStateDomain = "auto" | "workspace" | "recovery" | "resumab export type BridgeLiveStateInvalidationSource = "bridge_event" | "rpc_command" | "session_manage"; export type BridgeLiveStateInvalidationReason = | "agent_end" + | "turn_end" | "auto_retry_start" | "auto_retry_end" | "auto_compaction_start" @@ -771,6 +765,7 @@ async function loadSessionBrowserSessionsViaChildProcess(config: BridgeRuntimeCo GSD_SESSION_BROWSER_DIR: config.projectSessionsDir, }, maxBuffer: 1024 * 1024, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { @@ -832,6 +827,7 @@ async function appendSessionInfoViaChildProcess( GSD_TARGET_SESSION_NAME: name, }, maxBuffer: 1024 * 1024, + windowsHide: true, }, (error, _stdout, stderr) => { if (error) { @@ -1030,6 +1026,7 @@ async function loadWorkspaceIndexViaChildProcess(basePath: string, packageRoot: GSD_WORKSPACE_BASE: basePath, }, maxBuffer: 1024 * 1024, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { @@ -1251,6 +1248,13 @@ function createLiveStateInvalidationFromBridgeEvent( domains: ["auto", "workspace", "recovery"], workspaceIndexCacheInvalidated: true, }; + case "turn_end": + return { + reason: "turn_end", + source: "bridge_event", + domains: ["workspace"], + workspaceIndexCacheInvalidated: true, + }; case "auto_retry_start": return { reason: "auto_retry_start", @@ -1616,6 +1620,7 @@ export class BridgeService { cwd: cliEntry.cwd, env: childEnv, stdio: ["pipe", "pipe", "pipe"], + windowsHide: true, }) as SpawnedRpcChild; this.process = child; @@ -1771,6 +1776,7 @@ export class BridgeService { const eventType = (event as { type?: string }).type; if ( eventType === "agent_end" || + eventType === "turn_end" || eventType === "auto_retry_start" || eventType === "auto_retry_end" || eventType === "auto_compaction_start" || diff --git a/src/web/captures-service.ts b/src/web/captures-service.ts index 1f7cb1189..2a8b4c9b8 100644 --- a/src/web/captures-service.ts +++ b/src/web/captures-service.ts @@ -64,6 +64,7 @@ export async function collectCapturesData(projectCwdOverride?: string): Promise< GSD_CAPTURES_BASE: projectCwd, }, maxBuffer: CAPTURES_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { @@ -136,6 +137,7 @@ export async function resolveCaptureAction(request: CaptureResolveRequest, proje GSD_CAPTURES_BASE: projectCwd, }, maxBuffer: CAPTURES_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/cleanup-service.ts b/src/web/cleanup-service.ts index 145201f31..2ef778a4e 100644 --- a/src/web/cleanup-service.ts +++ b/src/web/cleanup-service.ts @@ -78,6 +78,7 @@ export async function collectCleanupData(projectCwdOverride?: string): Promise { if (error) { @@ -170,6 +171,7 @@ export async function executeCleanup( GSD_CLEANUP_SNAPSHOTS: JSON.stringify(pruneSnapshots), }, maxBuffer: CLEANUP_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/doctor-service.ts b/src/web/doctor-service.ts index 8fac5b272..ec5bc4dac 100644 --- a/src/web/doctor-service.ts +++ b/src/web/doctor-service.ts @@ -41,6 +41,7 @@ function runDoctorChild( GSD_DOCTOR_SCOPE: scope ?? "", }, maxBuffer: DOCTOR_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/export-service.ts b/src/web/export-service.ts index 431f31473..002c98a94 100644 --- a/src/web/export-service.ts +++ b/src/web/export-service.ts @@ -74,6 +74,7 @@ export async function collectExportData( GSD_EXPORT_FORMAT: format, }, maxBuffer: EXPORT_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/forensics-service.ts b/src/web/forensics-service.ts index 445fa59e6..ac74855d6 100644 --- a/src/web/forensics-service.ts +++ b/src/web/forensics-service.ts @@ -94,6 +94,7 @@ export async function collectForensicsData(projectCwdOverride?: string): Promise GSD_FORENSICS_BASE: projectCwd, }, maxBuffer: FORENSICS_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/history-service.ts b/src/web/history-service.ts index a2ee75c68..ac1808aa2 100644 --- a/src/web/history-service.ts +++ b/src/web/history-service.ts @@ -66,6 +66,7 @@ export async function collectHistoryData(projectCwdOverride?: string): Promise { if (error) { diff --git a/src/web/hooks-service.ts b/src/web/hooks-service.ts index 9eeac1276..5eebcf4d9 100644 --- a/src/web/hooks-service.ts +++ b/src/web/hooks-service.ts @@ -66,6 +66,7 @@ export async function collectHooksData(projectCwdOverride?: string): Promise { if (error) { diff --git a/src/web/notifications-service.ts b/src/web/notifications-service.ts new file mode 100644 index 000000000..5253d8a77 --- /dev/null +++ b/src/web/notifications-service.ts @@ -0,0 +1,143 @@ +// GSD Web — Notifications Service +// Loads notification data via a child process that imports the notification store. + +import { execFile } from "node:child_process" +import { existsSync } from "node:fs" +import { join } from "node:path" +import { pathToFileURL } from "node:url" + +import { resolveBridgeRuntimeConfig } from "./bridge-service.ts" +import { resolveTypeStrippingFlag, resolveSubprocessModule, buildSubprocessPrefixArgs } from "./ts-subprocess-flags.ts" + +export interface NotificationsData { + entries: Array<{ + id: string + ts: string + severity: string + message: string + source: string + read: boolean + }> + unreadCount: number + totalCount: number +} + +const NOTIFICATIONS_MAX_BUFFER = 2 * 1024 * 1024 +const NOTIFICATIONS_MODULE_ENV = "GSD_NOTIFICATIONS_MODULE" + +function resolveTsLoaderPath(packageRoot: string): string { + return join(packageRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs") +} + +export async function collectNotificationsData(projectCwdOverride?: string): Promise { + const config = resolveBridgeRuntimeConfig(undefined, projectCwdOverride) + const { packageRoot, projectCwd } = config + + const resolveTsLoader = resolveTsLoaderPath(packageRoot) + const moduleResolution = resolveSubprocessModule(packageRoot, "resources/extensions/gsd/notification-store.ts") + const modulePath = moduleResolution.modulePath + + if (!moduleResolution.useCompiledJs && (!existsSync(resolveTsLoader) || !existsSync(modulePath))) { + throw new Error( + `notifications data provider not found; checked=${resolveTsLoader},${modulePath}`, + ) + } + if (moduleResolution.useCompiledJs && !existsSync(modulePath)) { + throw new Error(`notifications data provider not found; checked=${modulePath}`) + } + + const script = [ + 'const { pathToFileURL } = await import("node:url");', + `const mod = await import(pathToFileURL(process.env.${NOTIFICATIONS_MODULE_ENV}).href);`, + 'const basePath = process.env.GSD_NOTIFICATIONS_BASE;', + 'const entries = mod.readNotifications(basePath);', + 'const unread = entries.filter(e => !e.read).length;', + 'const result = { entries, unreadCount: unread, totalCount: entries.length };', + 'process.stdout.write(JSON.stringify(result));', + ].join(" ") + + const prefixArgs = buildSubprocessPrefixArgs(packageRoot, moduleResolution, pathToFileURL(resolveTsLoader).href) + + return await new Promise((resolveResult, reject) => { + execFile( + process.execPath, + [ + ...prefixArgs, + "--eval", + script, + ], + { + cwd: packageRoot, + env: { + ...process.env, + [NOTIFICATIONS_MODULE_ENV]: modulePath, + GSD_NOTIFICATIONS_BASE: projectCwd, + }, + maxBuffer: NOTIFICATIONS_MAX_BUFFER, + timeout: 10_000, + }, + (err, stdout, stderr) => { + if (err) { + reject(new Error(`notifications subprocess failed: ${err.message}${stderr ? `\nstderr: ${stderr}` : ""}`)) + return + } + try { + const parsed = JSON.parse(stdout) as NotificationsData + resolveResult(parsed) + } catch (parseErr) { + reject(new Error(`Failed to parse notifications output: ${(parseErr as Error).message}`)) + } + }, + ) + }) +} + +export async function clearNotificationsData(projectCwdOverride?: string): Promise { + const config = resolveBridgeRuntimeConfig(undefined, projectCwdOverride) + const { packageRoot, projectCwd } = config + + const resolveTsLoader = resolveTsLoaderPath(packageRoot) + const moduleResolution = resolveSubprocessModule(packageRoot, "resources/extensions/gsd/notification-store.ts") + const modulePath = moduleResolution.modulePath + + if (moduleResolution.useCompiledJs && !existsSync(modulePath)) { + throw new Error(`notifications data provider not found; checked=${modulePath}`) + } + + const script = [ + 'const { pathToFileURL } = await import("node:url");', + `const mod = await import(pathToFileURL(process.env.${NOTIFICATIONS_MODULE_ENV}).href);`, + 'mod.clearNotifications(process.env.GSD_NOTIFICATIONS_BASE);', + 'process.stdout.write("ok");', + ].join(" ") + + const prefixArgs = buildSubprocessPrefixArgs(packageRoot, moduleResolution, pathToFileURL(resolveTsLoader).href) + + return await new Promise((resolveResult, reject) => { + execFile( + process.execPath, + [ + ...prefixArgs, + "--eval", + script, + ], + { + cwd: packageRoot, + env: { + ...process.env, + [NOTIFICATIONS_MODULE_ENV]: modulePath, + GSD_NOTIFICATIONS_BASE: projectCwd, + }, + maxBuffer: NOTIFICATIONS_MAX_BUFFER, + timeout: 10_000, + }, + (err, _stdout, stderr) => { + if (err) { + reject(new Error(`clear notifications subprocess failed: ${err.message}${stderr ? `\nstderr: ${stderr}` : ""}`)) + return + } + resolveResult() + }, + ) + }) +} diff --git a/src/web/onboarding-service.ts b/src/web/onboarding-service.ts index 26f4d6883..764949c58 100644 --- a/src/web/onboarding-service.ts +++ b/src/web/onboarding-service.ts @@ -142,7 +142,7 @@ type ProviderFlowRuntime = { }; const REQUIRED_PROVIDER_CATALOG: RequiredProviderCatalogEntry[] = [ - { id: "anthropic", label: "Anthropic (Claude)", supportsApiKey: true, supportsOAuth: true, recommended: true }, + { id: "anthropic", label: "Anthropic (Claude)", supportsApiKey: true, supportsOAuth: false, recommended: true }, { id: "openai", label: "OpenAI", supportsApiKey: true, supportsOAuth: false }, { id: "github-copilot", label: "GitHub Copilot", supportsApiKey: false, supportsOAuth: true }, { id: "openai-codex", label: "ChatGPT Plus/Pro (Codex Subscription)", supportsApiKey: false, supportsOAuth: true }, @@ -231,7 +231,9 @@ function resolveOnboardingLockReason( function hasStoredCredentialValue(authStorage: AuthStorageInstance, providerId: string): boolean { return authStorage.getCredentialsForProvider(providerId).some((credential) => { - if (credential.type === "oauth") return true; + if (credential.type === "oauth") { + return typeof credential.access === "string" && credential.access.trim().length > 0; + } return typeof credential.key === "string" && credential.key.trim().length > 0; }); } @@ -247,9 +249,6 @@ function resolveCredentialSource( if (getEnvApiKeyFn(providerId)) { return "environment"; } - if (authStorage.getCredentialsForProvider(providerId).length > 0) { - return "runtime"; - } return null; } diff --git a/src/web/recovery-diagnostics-service.ts b/src/web/recovery-diagnostics-service.ts index ee5abeb92..cc9c8b9e8 100644 --- a/src/web/recovery-diagnostics-service.ts +++ b/src/web/recovery-diagnostics-service.ts @@ -491,6 +491,7 @@ async function collectRecoveryDiagnosticsChildPayload( GSD_RECOVERY_FORENSICS_MODULE: sessionForensicsModulePath, }, maxBuffer: RECOVERY_DIAGNOSTICS_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/safe-import-meta-resolve.ts b/src/web/safe-import-meta-resolve.ts new file mode 100644 index 000000000..95c388c5a --- /dev/null +++ b/src/web/safe-import-meta-resolve.ts @@ -0,0 +1,33 @@ +import { dirname, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +/** + * Derive a package root from an import.meta.url, returning null on failure. + * + * The Next.js standalone build bakes import.meta.url as the CI runner's + * absolute path (e.g. file:///home/runner/work/gsd-2/gsd-2/src/web/bridge-service.ts). + * On Windows, fileURLToPath() rejects this Linux path with + * "File URL path must be absolute". + * + * This helper catches that error so the module-level constant never throws, + * letting resolveBridgeRuntimeConfig() fall through to the GSD_WEB_PACKAGE_ROOT + * env var that web-mode.ts always sets at launch time. + * + * @param importUrl - The value of import.meta.url at the call site. + * @param ancestorLevels - How many directory levels to ascend from the module's + * directory to reach the package root (default 2: src/web/ -> root). + * @returns Resolved absolute package root path, or null if the URL cannot be + * converted to a native path on this platform. + */ +export function safePackageRootFromImportUrl( + importUrl: string, + ancestorLevels = 2, +): string | null { + try { + const moduleDir = dirname(fileURLToPath(importUrl)); + const segments = Array.from({ length: ancestorLevels }, () => ".."); + return resolve(moduleDir, ...segments); + } catch { + return null; + } +} diff --git a/src/web/settings-service.ts b/src/web/settings-service.ts index 8e1b5c6ea..f9c850420 100644 --- a/src/web/settings-service.ts +++ b/src/web/settings-service.ts @@ -73,8 +73,23 @@ export async function collectSettingsData(projectCwdOverride?: string): Promise< 'let preferences = null;', 'if (loaded) {', ' const p = loaded.preferences;', + ' const models = {};', + ' if (p.models && typeof p.models === "object") {', + ' for (const [phase, value] of Object.entries(p.models)) {', + ' if (typeof value === "string") {', + ' models[phase] = value;', + ' continue;', + ' }', + ' if (value && typeof value === "object" && typeof value.model === "string") {', + ' models[phase] = typeof value.provider === "string" && value.provider && !value.model.includes("/")', + ' ? `${value.provider}/${value.model}`', + ' : value.model;', + ' }', + ' }', + ' }', ' preferences = {', ' mode: p.mode,', + ' models: Object.keys(models).length > 0 ? models : undefined,', ' budgetCeiling: p.budget_ceiling,', ' budgetEnforcement: p.budget_enforcement,', ' tokenProfile: p.token_profile,', @@ -142,6 +157,7 @@ export async function collectSettingsData(projectCwdOverride?: string): Promise< GSD_SETTINGS_BASE: projectCwd, }, maxBuffer: SETTINGS_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/skill-health-service.ts b/src/web/skill-health-service.ts index 60834dc96..43d586884 100644 --- a/src/web/skill-health-service.ts +++ b/src/web/skill-health-service.ts @@ -61,6 +61,7 @@ export async function collectSkillHealthData(projectCwdOverride?: string): Promi GSD_SKILL_HEALTH_BASE: projectCwd, }, maxBuffer: SKILL_HEALTH_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/web/subprocess-runner.ts b/src/web/subprocess-runner.ts new file mode 100644 index 000000000..e4d67710f --- /dev/null +++ b/src/web/subprocess-runner.ts @@ -0,0 +1,168 @@ +/** + * Shared subprocess runner for web service files. + * + * Every web service that loads upstream GSD extension modules needs to spawn + * a Node child process with the TS loader, type-stripping flag, and --eval. + * This module centralises that boilerplate so services only specify what + * varies: the script, env vars, and module paths. + */ + +import { execFile } from "node:child_process" +import { existsSync as defaultExistsSync } from "node:fs" +import { join } from "node:path" +import { pathToFileURL } from "node:url" + +import { resolveTypeStrippingFlag } from "./ts-subprocess-flags.ts" + +const DEFAULT_MAX_BUFFER = 2 * 1024 * 1024 +const DEFAULT_TIMEOUT_MS = 30_000 + +// --------------------------------------------------------------------------- +// Module path resolution +// --------------------------------------------------------------------------- + +export interface ModuleSpec { + /** Environment variable name the child process reads to find this module. */ + envKey: string + /** Path relative to packageRoot (e.g. "src/resources/extensions/gsd/doctor.ts"). */ + relativePath: string +} + +export interface ResolveModulePathsOptions { + modules: ModuleSpec[] + /** Override for testing — defaults to fs.existsSync. */ + existsSync?: (path: string) => boolean + /** Label used in error messages (e.g. "doctor-service"). */ + label?: string +} + +export interface ResolvedPaths { + /** Absolute path to resolve-ts.mjs. */ + tsLoaderPath: string + /** Environment variable entries mapping each module's envKey to its absolute path. */ + env: Record +} + +/** + * Resolves the TS loader path and all module paths, validating that every + * path exists on disk. Throws a descriptive error if any path is missing. + */ +export function resolveModulePaths( + packageRoot: string, + options: ResolveModulePathsOptions, +): ResolvedPaths { + const checkExists = options.existsSync ?? defaultExistsSync + const label = options.label ?? "subprocess" + + const tsLoaderPath = join( + packageRoot, + "src", + "resources", + "extensions", + "gsd", + "tests", + "resolve-ts.mjs", + ) + + const modulePaths: Record = {} + const allPaths = [tsLoaderPath] + + for (const mod of options.modules) { + const fullPath = join(packageRoot, mod.relativePath) + modulePaths[mod.envKey] = fullPath + allPaths.push(fullPath) + } + + for (const p of allPaths) { + if (!checkExists(p)) { + throw new Error(`${label} data provider not found; missing=${p}`) + } + } + + return { tsLoaderPath, env: modulePaths } +} + +// --------------------------------------------------------------------------- +// Subprocess runner +// --------------------------------------------------------------------------- + +export interface RunSubprocessOptions { + /** Absolute path to the package root (used as cwd and for flag resolution). */ + packageRoot: string + /** The --eval script to run in the child process. */ + script: string + /** Extra environment variables merged onto process.env for the child. */ + env: Record + /** Label for error messages (e.g. "doctor", "forensics"). */ + label: string + /** Override cwd (defaults to packageRoot). */ + cwd?: string + /** Max stdout buffer in bytes. Defaults to 2 MB. */ + maxBuffer?: number + /** Subprocess timeout in milliseconds. Defaults to 30 s. */ + timeoutMs?: number + /** Resolved TS loader path — if omitted, resolves from packageRoot. */ + tsLoaderPath?: string + /** Override process.execPath for testing. */ + execPath?: string +} + +/** + * Spawns a Node child process that evaluates `script` with the TS loader and + * type-stripping flag, parses the stdout as JSON, and returns the result. + * + * Replaces the identical `new Promise((resolve, reject) => execFile(...))` + * callback boilerplate that was duplicated across 12+ web service files. + */ +export async function runSubprocess(options: RunSubprocessOptions): Promise { + const { + packageRoot, + script, + env: extraEnv, + label, + cwd = packageRoot, + maxBuffer = DEFAULT_MAX_BUFFER, + timeoutMs = DEFAULT_TIMEOUT_MS, + execPath = process.execPath, + } = options + + const tsLoaderPath = + options.tsLoaderPath ?? + join(packageRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs") + + return await new Promise((resolveResult, reject) => { + execFile( + execPath, + [ + "--import", + pathToFileURL(tsLoaderPath).href, + resolveTypeStrippingFlag(packageRoot), + "--input-type=module", + "--eval", + script, + ], + { + cwd, + env: { ...process.env, ...extraEnv }, + maxBuffer, + timeout: timeoutMs, + }, + (error, stdout, stderr) => { + if (error) { + reject(new Error(`${label} subprocess failed: ${stderr || error.message}`)) + return + } + + try { + resolveResult(JSON.parse(stdout) as T) + } catch (parseError) { + reject( + new Error( + `${label} subprocess returned invalid JSON: ${parseError instanceof Error ? parseError.message : String(parseError)}`, + ), + ) + } + }, + ) + }) +} diff --git a/src/web/undo-service.ts b/src/web/undo-service.ts index ad339a359..2a218cc54 100644 --- a/src/web/undo-service.ts +++ b/src/web/undo-service.ts @@ -195,6 +195,7 @@ export async function executeUndo(projectCwdOverride?: string): Promise { if (error) { diff --git a/src/web/update-service.ts b/src/web/update-service.ts index 1ec44aa1a..5b6ccfef8 100644 --- a/src/web/update-service.ts +++ b/src/web/update-service.ts @@ -4,6 +4,7 @@ import { compareSemver } from "../update-check.ts" const NPM_PACKAGE_NAME = "gsd-pi" const REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest` const FETCH_TIMEOUT_MS = 5000 +const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm" // --- Version check --- @@ -69,10 +70,12 @@ export function triggerUpdate(targetVersion?: string): boolean { updateState = { status: "running", targetVersion } - const child = spawn("npm", ["install", "-g", "gsd-pi@latest"], { + const child = spawn(NPM_COMMAND, ["install", "-g", "gsd-pi@latest"], { stdio: ["ignore", "ignore", "pipe"], // Detach so the child process is not killed if the parent exits detached: false, + windowsHide: true, + shell: process.platform === "win32", }) let stderr = "" diff --git a/src/web/visualizer-service.ts b/src/web/visualizer-service.ts index 93b1fcdd0..11a21e8f8 100644 --- a/src/web/visualizer-service.ts +++ b/src/web/visualizer-service.ts @@ -98,6 +98,7 @@ export async function collectVisualizerData(projectCwdOverride?: string): Promis GSD_VISUALIZER_BASE: projectCwd, }, maxBuffer: VISUALIZER_MAX_BUFFER, + windowsHide: true, }, (error, stdout, stderr) => { if (error) { diff --git a/src/welcome-screen.ts b/src/welcome-screen.ts index 7b8d37773..80f7b03aa 100644 --- a/src/welcome-screen.ts +++ b/src/welcome-screen.ts @@ -6,14 +6,17 @@ * Falls back to simple text on narrow terminals (<70 cols) or non-TTY. */ +import { execFileSync } from 'node:child_process' import os from 'node:os' import chalk from 'chalk' +import stripAnsi from 'strip-ansi' import { GSD_LOGO } from './logo.js' export interface WelcomeScreenOptions { version: string modelName?: string provider?: string + remoteChannel?: string } function getShortCwd(): string { @@ -24,7 +27,7 @@ function getShortCwd(): string { /** Visible length — strips ANSI escape codes before measuring. */ function visLen(s: string): number { - return s.replace(/\x1b\[[0-9;]*m/g, '').length + return stripAnsi(s).length } /** Right-pad a string to the given visible width. */ @@ -32,12 +35,26 @@ function rpad(s: string, w: number): string { return s + ' '.repeat(Math.max(0, w - visLen(s))) } +/** Read the current git branch name. Returns undefined on failure. */ +function getGitBranch(): string | undefined { + try { + return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { + encoding: 'utf-8', + timeout: 2000, + stdio: ['ignore', 'pipe', 'ignore'], + }).trim() || undefined + } catch { + return undefined + } +} + export function printWelcomeScreen(opts: WelcomeScreenOptions): void { if (!process.stderr.isTTY) return - const { version, modelName, provider } = opts + const { version, modelName, provider, remoteChannel } = opts const shortCwd = getShortCwd() - const termWidth = Math.min((process.stderr.columns || 80) - 1, 200) + const branch = getGitBranch() + const termWidth = (process.stderr.columns || 80) - 1 // Narrow terminal fallback if (termWidth < 70) { @@ -69,6 +86,7 @@ export function printWelcomeScreen(opts: WelcomeScreenOptions): void { if (process.env.JINA_API_KEY) toolParts.push('Jina ✓') if (process.env.TAVILY_API_KEY) toolParts.push('Tavily ✓') if (process.env.CONTEXT7_API_KEY) toolParts.push('Context7 ✓') + if (remoteChannel) toolParts.push(`${remoteChannel.charAt(0).toUpperCase() + remoteChannel.slice(1)} ✓`) // Tools left, hint right-aligned on the same row const toolsLeft = toolParts.length > 0 ? chalk.dim(' ' + toolParts.join(' · ')) : '' @@ -76,16 +94,26 @@ export function printWelcomeScreen(opts: WelcomeScreenOptions): void { const footerFill = RIGHT_INNER - visLen(toolsLeft) - visLen(hintRight) const footerRow = toolsLeft + ' '.repeat(Math.max(1, footerFill)) + hintRight + // Combined session line: "provider / model" or just model or just provider + const sessionParts = [provider, modelName].filter(Boolean) + const sessionLine = sessionParts.length > 0 + ? ` Session ${chalk.dim(sessionParts.join(' / '))}` + : '' + + // Combined project line: "~/path [branch]" + const branchSuffix = branch ? ` [${branch}]` : '' + const projectLine = ` Project ${chalk.dim(shortCwd + branchSuffix)}` + const DIVIDER = null const rightRows: (string | null)[] = [ titleRow, DIVIDER, - modelName ? ` Model ${chalk.dim(modelName)}` : '', - provider ? ` Provider ${chalk.dim(provider)}` : '', - ` Directory ${chalk.dim(shortCwd)}`, + '', + sessionLine, + projectLine, + '', DIVIDER, footerRow, - '', ] // ── Render ────────────────────────────────────────────────────────────────── diff --git a/tsconfig.test.json b/tsconfig.test.json index cdd2e38ab..d1fb9db80 100644 --- a/tsconfig.test.json +++ b/tsconfig.test.json @@ -4,6 +4,6 @@ "declaration": false, "noEmit": false }, - "include": ["src/tests/headless-cli-surface.test.ts", "src/headless-events.ts", "src/headless-types.ts"], + "include": ["src/tests/headless-cli-surface.test.ts", "src/tests/ensure-workspace-builds.test.ts", "src/headless-events.ts", "src/headless-types.ts", "src/tests/google-search-oauth-shape.test.ts", "src/tests/google-search-auth.repro.test.ts"], "exclude": [] } diff --git a/vscode-extension/CHANGELOG.md b/vscode-extension/CHANGELOG.md index fd532537d..98266e301 100644 --- a/vscode-extension/CHANGELOG.md +++ b/vscode-extension/CHANGELOG.md @@ -1,24 +1,45 @@ # Changelog +## [0.3.0] + +### Added + +- **SCM provider** — "GSD Agent" appears in Source Control panel with accept/discard per-file diffs +- **Change tracker** — captures original file content before agent modifications for diff and rollback +- **Checkpoints** — automatic snapshots on each agent turn with restore capability +- **Diagnostic bridge** — "Fix Problems in File" and "Fix All Problems" commands read VS Code diagnostics and send to agent +- **Line-level decorations** — green/yellow highlights on agent-modified lines with gutter indicators +- **Chat context injection** — auto-includes editor selection and file diagnostics when relevant +- **Git integration** — commit agent changes, create branches, show diffs +- **Approval modes** — auto-approve, ask (prompts before writes), plan-only (read-only) +- **UI request handling** — agent questions, confirmations, and selections now show as VS Code dialogs instead of hanging +- **Fix Errors button** — quick access to diagnostic fixing in sidebar Actions +- **5 new settings** — `showProgressNotifications`, `activityFeedMaxItems`, `showContextWarning`, `contextWarningThreshold`, `approvalMode` + +### Changed + +- **Sidebar redesign** — compact card-based layout with collapsible sections, pill toggles, hidden empty data +- **Workflow buttons** now route through Chat panel so responses are visible +- **Slash completion** filtered to `/gsd` commands only +- **Checkpoint labels** show timestamp + first action (e.g., "10:32 — Edit sidebar.ts") +- **Session tree** supports ISO timestamp filenames (GSD's actual format) +- **Session persistence** enabled (removed `--no-session` flag) +- **Progress notifications** disabled by default (Chat panel provides inline progress) +- **Sidebar reduced** from 6 panels to 3 (GSD Agent, Sessions, Activity) +- **Settings section** starts collapsed by default + ## [0.2.0] ### Added -- **Activity feed** — real-time TreeView showing tool executions (Read, Write, Edit, Bash, Grep, Glob) with status icons, duration, and click-to-open -- **Workflow controls** — sidebar buttons for Auto, Next, Quick Task, Capture, Status, and Fork that send `/gsd` slash commands -- **Progress notifications** — VS Code notification with cancel button while the agent is working -- **Context window indicator** — color-coded usage bar (green/yellow/red) in sidebar with configurable threshold warnings -- **Session forking** — fork from any message via QuickPick using `get_fork_messages` and `fork` RPC commands -- **Queue mode controls** — toggle steering and follow-up modes (all vs one-at-a-time) from the sidebar -- **Enhanced conversation history** — tool call rendering, collapsible thinking blocks, search/filter, fork-from-here buttons -- **Enhanced code lens** — Refactor, Find Bugs, and Generate Tests actions alongside Ask GSD -- **4 new settings** — `showProgressNotifications`, `activityFeedMaxItems`, `showContextWarning`, `contextWarningThreshold` -- **8 new commands** (33 total) — `clearActivity`, `forkSession`, `toggleSteeringMode`, `toggleFollowUpMode`, `refactorSymbol`, `findBugsSymbol`, `generateTestsSymbol` - -### Changed - -- Sidebar session table now shows steering and follow-up queue mode with clickable toggle badges -- Token usage section includes context window usage bar when model context window is known +- **Activity feed** — real-time TreeView showing tool executions with status icons, duration, and click-to-open +- **Workflow controls** — sidebar buttons for Auto, Next, Quick Task, Capture +- **Context window indicator** — color-coded usage bar in sidebar with threshold warnings +- **Session forking** — fork from any message via QuickPick +- **Queue mode controls** — toggle steering and follow-up modes from the sidebar +- **Enhanced conversation history** — tool call rendering, collapsible thinking blocks, search/filter, fork-from-here +- **Enhanced code lens** — Refactor, Find Bugs, and Generate Tests alongside Ask GSD +- **8 new commands** (33 total) ## [0.1.0] @@ -31,7 +52,7 @@ Initial release. - Bash terminal — pseudoterminal routing agent Bash tool output - Session tree — browse and switch between session files - Conversation history — webview panel with full chat log -- Slash command completion — auto-complete for `/gsd` commands in editors +- Slash command completion — auto-complete for `/gsd` commands - Code lens — "Ask GSD" above functions and classes in TS/JS/Python/Go/Rust - 25 commands with 6 keyboard shortcuts - Auto-start, auto-compaction, and code lens configuration diff --git a/vscode-extension/README.md b/vscode-extension/README.md index f0f249c43..899012880 100644 --- a/vscode-extension/README.md +++ b/vscode-extension/README.md @@ -1,88 +1,193 @@ # GSD-2 — VS Code Extension -Control the [GSD-2 coding agent](https://github.com/gsd-build/gsd-2) directly from VS Code. Run autonomous coding sessions, chat with `@gsd` in VS Code Chat, and monitor your agent from a sidebar dashboard — all without leaving the editor. +Control the [GSD-2 coding agent](https://github.com/gsd-build/gsd-2) directly from VS Code. Run autonomous coding sessions, chat with `@gsd`, monitor agent activity in real-time, review and accept/reject changes, and manage your workflow — all without leaving the editor. + +![GSD Extension Overview](docs/images/overview.png) ## Requirements -GSD must be installed before activating this extension: - -```bash -npm install -g gsd-pi -``` - -Node.js ≥ 22.0.0 and Git are required. - -## Features - -### Sidebar Dashboard - -Click the GSD icon in the Activity Bar to open the agent dashboard. It shows: - -- Connection status (connected / disconnected) -- Active model and provider -- Thinking level -- Token usage and session cost -- Quick action buttons: Start, Stop, New Session, Compact, Abort - -### Chat Integration (`@gsd`) - -Use `@gsd` in VS Code Chat (`Ctrl+Shift+I`) to send messages to the agent: - -``` -@gsd refactor the auth module to use JWT -@gsd /gsd auto -@gsd what's the current milestone status? -``` - -### Commands - -All commands are accessible via `Ctrl+Shift+P`: - -| Command | Description | -|---------|-------------| -| **GSD: Start Agent** | Connect to the GSD agent | -| **GSD: Stop Agent** | Disconnect the agent | -| **GSD: New Session** | Start a fresh conversation | -| **GSD: Send Message** | Send a message to the agent | -| **GSD: Abort Current Operation** | Interrupt the current operation | -| **GSD: Steer Agent** | Send a steering message mid-operation | -| **GSD: Switch Model** | Pick a model from QuickPick | -| **GSD: Cycle Model** | Rotate to the next configured model | -| **GSD: Set Thinking Level** | Choose off / low / medium / high | -| **GSD: Cycle Thinking Level** | Rotate through thinking levels | -| **GSD: Compact Context** | Manually trigger context compaction | -| **GSD: Export Conversation as HTML** | Save the session as HTML | -| **GSD: Show Session Stats** | Display token usage and cost | -| **GSD: Run Bash Command** | Execute a shell command via the agent | -| **GSD: List Available Commands** | Browse and run GSD slash commands | - -### Keyboard Shortcuts - -| Shortcut | Command | -|----------|---------| -| `Ctrl+Shift+G Ctrl+Shift+N` | New Session | -| `Ctrl+Shift+G Ctrl+Shift+M` | Cycle Model | -| `Ctrl+Shift+G Ctrl+Shift+T` | Cycle Thinking Level | - -## Configuration - -| Setting | Default | Description | -|---------|---------|-------------| -| `gsd.binaryPath` | `"gsd"` | Path to the GSD binary if not on PATH | -| `gsd.autoStart` | `false` | Start the agent automatically when the extension activates | -| `gsd.autoCompaction` | `true` | Enable automatic context compaction | +- **GSD-2** installed globally: `npm install -g gsd-pi` +- **Node.js** >= 22.0.0 +- **Git** installed and on PATH +- **VS Code** >= 1.95.0 ## Quick Start 1. Install GSD: `npm install -g gsd-pi` 2. Install this extension 3. Open a project folder in VS Code -4. `Ctrl+Shift+P` → **GSD: Start Agent** -5. Use `@gsd` in Chat or the sidebar to interact with the agent +4. Click the **GSD icon** in the Activity Bar (left sidebar) +5. Click **Start Agent** or run `Ctrl+Shift+P` > **GSD: Start Agent** +6. Start chatting with `@gsd` in Chat or click **Auto** in the sidebar + +--- + +## Features + +### Sidebar Dashboard + +Click the **GSD icon** in the Activity Bar. The compact header shows connection status, model, session, message count, thinking level, context usage bar, and cost — all in two lines. Sections (Workflow, Stats, Actions, Settings) are collapsible and remember their state. + +### Workflow Controls + +One-click buttons for GSD's core commands. All route through the Chat panel so you see the full response: + +| Button | What it does | +|--------|-------------| +| **Auto** | Start autonomous mode — research, plan, execute | +| **Next** | Execute one unit of work, then pause | +| **Quick** | Quick task without planning (opens input) | +| **Capture** | Capture a thought for later triage | + +### Chat Integration (`@gsd`) + +Use `@gsd` in VS Code Chat (`Cmd+Shift+I`) to talk to the agent: + +``` +@gsd refactor the auth module to use JWT +@gsd /gsd auto +@gsd fix the errors in this file +``` + +- **Auto-starts** the agent if not running +- **File context** via `#file` references +- **Selection context** — automatically includes selected code +- **Diagnostic context** — auto-includes errors/warnings when you mention "fix" or "error" +- **Streaming** progress, file anchors, token usage footer + +### Source Control Integration + +Agent-modified files appear in a dedicated **"GSD Agent"** section of the Source Control panel: + +- **Click any file** to see a before/after diff in VS Code's native diff editor +- **Accept** or **Discard** changes per-file via inline buttons +- **Accept All** / **Discard All** via the SCM title bar +- Gutter diff indicators (green/red bars) show exactly what changed + +### Line-Level Decorations + +When the agent modifies a file, you'll see: +- **Green background** on newly added lines +- **Yellow background** on modified lines +- **Left border gutter indicator** on all agent-touched lines +- **Hover** any decorated line to see "Modified by GSD Agent" + +### Checkpoints & Rollback + +Automatic checkpoints are created at the start of each agent turn. Use **Discard All** in the SCM panel to revert all agent changes to their original state, or discard individual files. + +### Activity Feed + +The **Activity** panel shows a real-time log of every tool the agent executes — Read, Write, Edit, Bash, Grep, Glob — with status icons (running/success/error), duration, and click-to-open for file operations. + +### Sessions + +The **Sessions** panel lists all past sessions for the current workspace. Click any session to switch to it. The current session is highlighted green. Sessions persist to disk automatically. + +### Diagnostic Integration + +- **Fix Errors** button in the sidebar reads the active file's diagnostics from the Problems panel and sends them to the agent +- **Fix All Problems** (`Cmd+Shift+P` > GSD: Fix All Problems) collects errors/warnings across the workspace +- Works automatically in chat — mention "fix" or "error" and diagnostics are included + +### Code Lens + +Four inline actions above every function and class (TS/JS/Python/Go/Rust): + +| Action | What it does | +|--------|-------------| +| **Ask GSD** | Explain the function/class | +| **Refactor** | Improve clarity, performance, or structure | +| **Find Bugs** | Review for bugs and edge cases | +| **Tests** | Generate test coverage | + +### Git Integration + +- **Commit Agent Changes** — stages and commits modified files with your message +- **Create Branch** — create a new branch for agent work +- **Show Diff** — view git diff of agent changes + +### Approval Modes + +Control how much autonomy the agent has: + +| Mode | Behavior | +|------|----------| +| **Auto-approve** | Agent runs freely (default) | +| **Ask** | Prompts before file writes and commands | +| **Plan-only** | Read-only — agent can analyze but not modify | + +Change via Settings section or `Cmd+Shift+P` > **GSD: Select Approval Mode**. + +### Agent UI Requests + +When the agent needs input (questions, confirmations, selections), VS Code dialogs appear automatically — no more hanging on `ask_user_questions`. + +### Additional Features + +- **Conversation History** — full message viewer with tool calls, thinking blocks, search, and fork-from-here +- **Slash Command Completion** — type `/` for auto-complete of `/gsd` commands +- **File Decorations** — "G" badge on agent-modified files in the Explorer +- **Bash Terminal** — dedicated terminal for agent shell output +- **Context Window Warning** — notification when context exceeds threshold +- **Progress Notifications** — optional notification with cancel button (off by default) + +--- + +## All Commands + +| Command | Shortcut | Description | +|---------|----------|-------------| +| **GSD: Start Agent** | | Connect to the GSD agent | +| **GSD: Stop Agent** | | Disconnect the agent | +| **GSD: New Session** | `Cmd+Shift+G` `Cmd+Shift+N` | Start a fresh conversation | +| **GSD: Send Message** | `Cmd+Shift+G` `Cmd+Shift+P` | Send a message to the agent | +| **GSD: Abort** | `Cmd+Shift+G` `Cmd+Shift+A` | Interrupt the current operation | +| **GSD: Steer Agent** | `Cmd+Shift+G` `Cmd+Shift+I` | Steering message mid-operation | +| **GSD: Switch Model** | | Pick a model from QuickPick | +| **GSD: Cycle Model** | `Cmd+Shift+G` `Cmd+Shift+M` | Rotate to the next model | +| **GSD: Set Thinking Level** | | Choose off / low / medium / high | +| **GSD: Cycle Thinking** | `Cmd+Shift+G` `Cmd+Shift+T` | Rotate through thinking levels | +| **GSD: Compact Context** | | Trigger context compaction | +| **GSD: Export HTML** | | Save session as HTML | +| **GSD: Session Stats** | | Display token usage and cost | +| **GSD: Run Bash** | | Execute a shell command | +| **GSD: List Commands** | | Browse slash commands | +| **GSD: Set Session Name** | | Rename current session | +| **GSD: Copy Last Response** | | Copy to clipboard | +| **GSD: Switch Session** | | Load a different session | +| **GSD: Show History** | | Open conversation viewer | +| **GSD: Fork Session** | | Fork from a previous message | +| **GSD: Fix Problems in File** | | Send file diagnostics to agent | +| **GSD: Fix All Problems** | | Send workspace errors to agent | +| **GSD: Commit Agent Changes** | | Git commit modified files | +| **GSD: Create Branch** | | Create branch for agent work | +| **GSD: Show Agent Diff** | | View git diff | +| **GSD: Accept All Changes** | | Accept all SCM changes | +| **GSD: Discard All Changes** | | Revert all agent modifications | +| **GSD: Select Approval Mode** | | Choose auto-approve/ask/plan-only | +| **GSD: Cycle Approval Mode** | | Rotate through approval modes | +| **GSD: Code Lens** actions | | Ask, Refactor, Find Bugs, Tests | + +> On Windows/Linux, replace `Cmd` with `Ctrl`. + +## Configuration + +| Setting | Default | Description | +|---------|---------|-------------| +| `gsd.binaryPath` | `"gsd"` | Path to the GSD binary | +| `gsd.autoStart` | `false` | Start agent on extension activation | +| `gsd.autoCompaction` | `true` | Automatic context compaction | +| `gsd.codeLens` | `true` | Code lens above functions/classes | +| `gsd.showProgressNotifications` | `false` | Progress notification (off — Chat shows progress) | +| `gsd.activityFeedMaxItems` | `100` | Max items in Activity feed | +| `gsd.showContextWarning` | `true` | Warn when context exceeds threshold | +| `gsd.contextWarningThreshold` | `80` | Context % that triggers warning | +| `gsd.approvalMode` | `"auto-approve"` | Agent permission mode | ## How It Works -The extension spawns `gsd --mode rpc` in the background and communicates over JSON-RPC via stdin/stdout. All RPC commands are supported, including streaming events for real-time sidebar updates. +The extension spawns `gsd --mode rpc` and communicates over JSON-RPC via stdin/stdout. Agent events stream in real-time. The change tracker captures file state before modifications for SCM diffs and rollback. UI requests from the agent (questions, confirmations) are handled via VS Code dialogs. ## Links diff --git a/vscode-extension/docs/images/overview.png b/vscode-extension/docs/images/overview.png new file mode 100644 index 000000000..eafd6a1df Binary files /dev/null and b/vscode-extension/docs/images/overview.png differ diff --git a/vscode-extension/package-lock.json b/vscode-extension/package-lock.json index 67102cd86..c7a0636db 100644 --- a/vscode-extension/package-lock.json +++ b/vscode-extension/package-lock.json @@ -1,12 +1,12 @@ { "name": "gsd-2", - "version": "0.1.0", + "version": "0.3.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "gsd-2", - "version": "0.1.0", + "version": "0.3.0", "license": "MIT", "devDependencies": { "@types/vscode": "^1.95.0", @@ -955,9 +955,9 @@ "license": "BSD-2-Clause" }, "node_modules/brace-expansion": { - "version": "1.1.12", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", - "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "version": "1.1.13", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.13.tgz", + "integrity": "sha512-9ZLprWS6EENmhEOpjCYW2c8VkmOvckIJZfkr7rBW6dObmfgJ/L1GpSYW5Hpo9lDz4D1+n0Ckz8rU7FwHDQiG/w==", "dev": true, "license": "MIT", "dependencies": { @@ -1808,9 +1808,9 @@ } }, "node_modules/glob/node_modules/brace-expansion": { - "version": "5.0.4", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz", - "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==", + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", + "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", "dev": true, "license": "MIT", "dependencies": { @@ -2352,9 +2352,9 @@ } }, "node_modules/lodash": { - "version": "4.17.23", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz", - "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==", + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz", + "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==", "dev": true, "license": "MIT" }, @@ -2903,9 +2903,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz", - "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==", + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", "dev": true, "license": "MIT", "engines": { diff --git a/vscode-extension/package.json b/vscode-extension/package.json index 8ea2de271..2a2088fdf 100644 --- a/vscode-extension/package.json +++ b/vscode-extension/package.json @@ -3,7 +3,7 @@ "displayName": "GSD-2", "description": "VS Code integration for the GSD-2 coding agent — sidebar dashboard, @gsd chat participant, activity feed, conversation history, code lens, session forking, slash command completion, workflow controls, and 33 commands", "publisher": "FluxLabs", - "version": "0.2.0", + "version": "0.3.0", "icon": "logo.jpg", "license": "MIT", "repository": { @@ -168,6 +168,67 @@ { "command": "gsd.generateTestsSymbol", "title": "GSD: Generate Tests for Symbol" + }, + { + "command": "gsd.acceptAllChanges", + "title": "GSD: Accept All Agent Changes", + "icon": "$(check-all)" + }, + { + "command": "gsd.discardAllChanges", + "title": "GSD: Discard All Agent Changes", + "icon": "$(discard)" + }, + { + "command": "gsd.acceptFileChanges", + "title": "Accept Changes", + "icon": "$(check)" + }, + { + "command": "gsd.discardFileChanges", + "title": "Discard Changes", + "icon": "$(discard)" + }, + { + "command": "gsd.restoreCheckpoint", + "title": "GSD: Restore Checkpoint" + }, + { + "command": "gsd.fixProblemsInFile", + "title": "GSD: Fix Problems in File" + }, + { + "command": "gsd.fixAllProblems", + "title": "GSD: Fix All Problems" + }, + { + "command": "gsd.clearDiagnostics", + "title": "GSD: Clear Agent Diagnostics" + }, + { + "command": "gsd.commitAgentChanges", + "title": "GSD: Commit Agent Changes" + }, + { + "command": "gsd.createAgentBranch", + "title": "GSD: Create Branch for Agent Work" + }, + { + "command": "gsd.showAgentDiff", + "title": "GSD: Show Agent Diff" + }, + { + "command": "gsd.clearPlan", + "title": "GSD: Clear Plan View", + "icon": "$(clear-all)" + }, + { + "command": "gsd.cycleApprovalMode", + "title": "GSD: Cycle Approval Mode" + }, + { + "command": "gsd.selectApprovalMode", + "title": "GSD: Select Approval Mode" } ], "keybindings": [ @@ -240,6 +301,30 @@ "when": "view == gsd-activity", "group": "navigation" } + ], + "scm/title": [ + { + "command": "gsd.acceptAllChanges", + "group": "navigation", + "when": "scmProvider == gsd" + }, + { + "command": "gsd.discardAllChanges", + "group": "navigation", + "when": "scmProvider == gsd" + } + ], + "scm/resourceState/context": [ + { + "command": "gsd.acceptFileChanges", + "group": "inline", + "when": "scmProvider == gsd" + }, + { + "command": "gsd.discardFileChanges", + "group": "inline", + "when": "scmProvider == gsd" + } ] }, "chatParticipants": [ @@ -276,7 +361,7 @@ }, "gsd.showProgressNotifications": { "type": "boolean", - "default": true, + "default": false, "description": "Show progress notification while the agent is working" }, "gsd.activityFeedMaxItems": { @@ -297,6 +382,17 @@ "minimum": 50, "maximum": 95, "description": "Context window usage percentage that triggers a warning" + }, + "gsd.approvalMode": { + "type": "string", + "default": "auto-approve", + "enum": ["auto-approve", "ask", "plan-only"], + "enumDescriptions": [ + "Agent runs freely without prompts", + "Prompt before file changes and commands", + "Read-only mode — agent can analyze but not modify" + ], + "description": "Approval mode for agent actions" } } } diff --git a/vscode-extension/src/change-tracker.ts b/vscode-extension/src/change-tracker.ts new file mode 100644 index 000000000..f10191d65 --- /dev/null +++ b/vscode-extension/src/change-tracker.ts @@ -0,0 +1,295 @@ +import * as vscode from "vscode"; +import * as fs from "node:fs"; +import type { GsdClient, AgentEvent } from "./gsd-client.js"; + +export interface FileSnapshot { + uri: vscode.Uri; + originalContent: string; + timestamp: number; +} + +export interface Checkpoint { + id: number; + label: string; + timestamp: number; + /** Map of file path → original content at checkpoint creation time */ + snapshots: Map; +} + +/** + * Tracks file changes made by the GSD agent. Stores original file content + * before the agent modifies it, enabling diff views, SCM integration, + * and checkpoint/rollback functionality. + */ +export class GsdChangeTracker implements vscode.Disposable { + /** file path → original content (before first agent modification this session) */ + private originals = new Map(); + /** Set of file paths modified in the current agent turn */ + private currentTurnFiles = new Set(); + /** Ordered list of checkpoints */ + private _checkpoints: Checkpoint[] = []; + private nextCheckpointId = 1; + /** toolUseId → file path for in-flight tool executions */ + private pendingTools = new Map(); + /** Whether the current turn has been described in the checkpoint label */ + private turnDescribed = false; + + private readonly _onDidChange = new vscode.EventEmitter(); + /** Fires when the set of tracked files changes. Payload is array of changed file paths. */ + readonly onDidChange = this._onDidChange.event; + + private readonly _onCheckpointChange = new vscode.EventEmitter(); + readonly onCheckpointChange = this._onCheckpointChange.event; + + private disposables: vscode.Disposable[] = []; + + constructor(private readonly client: GsdClient) { + this.disposables.push(this._onDidChange, this._onCheckpointChange); + + this.disposables.push( + client.onEvent((evt) => this.handleEvent(evt)), + client.onConnectionChange((connected) => { + if (!connected) { + this.reset(); + } + }), + ); + } + + /** All file paths that have been modified by the agent */ + get modifiedFiles(): string[] { + return [...this.originals.keys()]; + } + + /** Get the original content of a file (before agent first modified it) */ + getOriginal(filePath: string): string | undefined { + return this.originals.get(filePath); + } + + /** Whether the tracker has any modifications */ + get hasChanges(): boolean { + return this.originals.size > 0; + } + + /** Current checkpoints (newest first) */ + get checkpoints(): readonly Checkpoint[] { + return this._checkpoints; + } + + /** + * Discard agent changes to a single file — restore original content. + * Returns true if the file was restored. + */ + async discardFile(filePath: string): Promise { + const original = this.originals.get(filePath); + if (original === undefined) return false; + + try { + await fs.promises.writeFile(filePath, original, "utf8"); + this.originals.delete(filePath); + this._onDidChange.fire([filePath]); + return true; + } catch { + return false; + } + } + + /** + * Discard all agent changes — restore all files to their original state. + */ + async discardAll(): Promise { + let count = 0; + const paths = [...this.originals.keys()]; + for (const filePath of paths) { + if (await this.discardFile(filePath)) { + count++; + } + } + return count; + } + + /** + * Accept changes to a file — remove from tracking (keep the current content). + */ + acceptFile(filePath: string): void { + if (this.originals.delete(filePath)) { + this._onDidChange.fire([filePath]); + } + } + + /** + * Accept all changes — clear all tracking. + */ + acceptAll(): void { + const paths = [...this.originals.keys()]; + this.originals.clear(); + if (paths.length > 0) { + this._onDidChange.fire(paths); + } + } + + /** + * Restore all files to a checkpoint state. + */ + async restoreCheckpoint(checkpointId: number): Promise { + const idx = this._checkpoints.findIndex((c) => c.id === checkpointId); + if (idx === -1) return 0; + + const checkpoint = this._checkpoints[idx]; + let count = 0; + + for (const [filePath, content] of checkpoint.snapshots) { + try { + await fs.promises.writeFile(filePath, content, "utf8"); + count++; + } catch { + // skip files that can't be restored + } + } + + // Reset originals to the checkpoint state + this.originals = new Map(checkpoint.snapshots); + + // Remove all checkpoints after this one + this._checkpoints = this._checkpoints.slice(0, idx); + + this._onDidChange.fire([...checkpoint.snapshots.keys()]); + this._onCheckpointChange.fire(); + return count; + } + + /** Clear all tracking state */ + reset(): void { + const paths = [...this.originals.keys()]; + this.originals.clear(); + this.currentTurnFiles.clear(); + this.pendingTools.clear(); + this._checkpoints = []; + this.nextCheckpointId = 1; + if (paths.length > 0) { + this._onDidChange.fire(paths); + } + this._onCheckpointChange.fire(); + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } + + private handleEvent(evt: AgentEvent): void { + switch (evt.type) { + case "agent_start": + this.createCheckpoint(); + this.currentTurnFiles.clear(); + this.turnDescribed = false; + break; + + case "tool_execution_start": { + const toolName = String(evt.toolName ?? ""); + const toolInput = (evt.toolInput ?? {}) as Record; + const toolUseId = String(evt.toolUseId ?? ""); + + // Update checkpoint label with first action description + if (!this.turnDescribed) { + this.turnDescribed = true; + this.updateLatestCheckpointLabel(describeAction(toolName, toolInput)); + } + + if (toolName !== "Write" && toolName !== "Edit") break; + + const filePath = String(toolInput.file_path ?? toolInput.path ?? ""); + + if (!filePath) break; + + // Store the original content before the agent modifies it + // Only capture on FIRST modification (don't overwrite) + if (!this.originals.has(filePath)) { + try { + if (fs.existsSync(filePath)) { + const content = fs.readFileSync(filePath, "utf8"); + this.originals.set(filePath, content); + } else { + // File doesn't exist yet — original is "empty" (new file) + this.originals.set(filePath, ""); + } + } catch { + // Can't read file, skip tracking + } + } + + if (toolUseId) { + this.pendingTools.set(toolUseId, filePath); + } + break; + } + + case "tool_execution_end": { + const toolUseId = String(evt.toolUseId ?? ""); + const filePath = this.pendingTools.get(toolUseId); + if (filePath) { + this.pendingTools.delete(toolUseId); + this.currentTurnFiles.add(filePath); + this._onDidChange.fire([filePath]); + } + break; + } + } + } + + private createCheckpoint(): void { + const now = Date.now(); + const time = new Date(now).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }); + const fileCount = this.originals.size; + const label = fileCount > 0 + ? `${time} (${fileCount} file${fileCount !== 1 ? "s" : ""} tracked)` + : `${time} (start)`; + + const checkpoint: Checkpoint = { + id: this.nextCheckpointId++, + label, + timestamp: now, + snapshots: new Map(this.originals), + }; + this._checkpoints.push(checkpoint); + this._onCheckpointChange.fire(); + } + + /** + * Update the label of the latest checkpoint with a description + * of the first action taken (called after first tool execution in a turn). + */ + private updateLatestCheckpointLabel(description: string): void { + if (this._checkpoints.length === 0) return; + const latest = this._checkpoints[this._checkpoints.length - 1]; + const time = new Date(latest.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }); + latest.label = `${time} — ${description}`; + this._onCheckpointChange.fire(); + } +} + +function describeAction(toolName: string, input: Record): string { + switch (toolName) { + case "Read": { + const p = String(input.file_path ?? input.path ?? ""); + return `Read ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Write": { + const p = String(input.file_path ?? ""); + return `Write ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Edit": { + const p = String(input.file_path ?? ""); + return `Edit ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Bash": + return `$ ${String(input.command ?? "").slice(0, 40)}`; + case "Grep": + return `Grep: ${String(input.pattern ?? "").slice(0, 30)}`; + case "Glob": + return `Glob: ${String(input.pattern ?? "").slice(0, 30)}`; + default: + return toolName; + } +} diff --git a/vscode-extension/src/chat-participant.ts b/vscode-extension/src/chat-participant.ts index 01647e1ad..6ba3e60e2 100644 --- a/vscode-extension/src/chat-participant.ts +++ b/vscode-extension/src/chat-participant.ts @@ -39,6 +39,21 @@ export function registerChatParticipant( message = `${fileContext}\n\n${message}`; } + // Auto-include editor selection if present and not already referenced + const selectionContext = getSelectionContext(); + if (selectionContext) { + message = `${selectionContext}\n\n${message}`; + } + + // Auto-include diagnostics for the active file if the prompt mentions "fix", "error", "problem", "warning" + const fixKeywords = /\b(fix|error|problem|warning|issue|bug|lint|diagnos)/i; + if (fixKeywords.test(message)) { + const diagContext = getActiveDiagnosticsContext(); + if (diagContext) { + message = `${message}\n\n${diagContext}`; + } + } + // Track streaming state let agentDone = false; let totalInputTokens = 0; @@ -281,3 +296,42 @@ function resolveFileUri(fp: string): vscode.Uri | null { return null; } } + +/** + * Get the current editor selection as context, if any text is selected. + */ +function getSelectionContext(): string | null { + const editor = vscode.window.activeTextEditor; + if (!editor || editor.selection.isEmpty) return null; + + const selection = editor.document.getText(editor.selection); + if (!selection.trim()) return null; + + const relativePath = vscode.workspace.asRelativePath(editor.document.uri); + const { start, end } = editor.selection; + return `Selected code in \`${relativePath}\` (lines ${start.line + 1}-${end.line + 1}):\n\`\`\`\n${selection}\n\`\`\``; +} + +/** + * Get diagnostics (errors/warnings) for the active editor file. + */ +function getActiveDiagnosticsContext(): string | null { + const editor = vscode.window.activeTextEditor; + if (!editor) return null; + + const diagnostics = vscode.languages.getDiagnostics(editor.document.uri); + const significant = diagnostics.filter( + (d) => d.severity === vscode.DiagnosticSeverity.Error || d.severity === vscode.DiagnosticSeverity.Warning, + ); + if (significant.length === 0) return null; + + const relativePath = vscode.workspace.asRelativePath(editor.document.uri); + const lines = [`Current diagnostics in \`${relativePath}\`:`]; + for (const d of significant) { + const sev = d.severity === vscode.DiagnosticSeverity.Error ? "Error" : "Warning"; + const line = d.range.start.line + 1; + const source = d.source ? ` [${d.source}]` : ""; + lines.push(`- ${sev} (line ${line}): ${d.message}${source}`); + } + return lines.join("\n"); +} diff --git a/vscode-extension/src/checkpoints.ts b/vscode-extension/src/checkpoints.ts new file mode 100644 index 000000000..584c9011c --- /dev/null +++ b/vscode-extension/src/checkpoints.ts @@ -0,0 +1,55 @@ +import * as vscode from "vscode"; +import type { GsdChangeTracker, Checkpoint } from "./change-tracker.js"; + +/** + * TreeDataProvider that shows agent checkpoints (one per agent turn). + * Each checkpoint can be restored to revert all file changes since that point. + */ +export class GsdCheckpointProvider implements vscode.TreeDataProvider, vscode.Disposable { + public static readonly viewId = "gsd-checkpoints"; + + private readonly _onDidChangeTreeData = new vscode.EventEmitter(); + readonly onDidChangeTreeData = this._onDidChangeTreeData.event; + + private disposables: vscode.Disposable[] = []; + + constructor(private readonly tracker: GsdChangeTracker) { + this.disposables.push( + this._onDidChangeTreeData, + tracker.onCheckpointChange(() => this._onDidChangeTreeData.fire()), + ); + } + + getTreeItem(checkpoint: Checkpoint): vscode.TreeItem { + const fileCount = checkpoint.snapshots.size; + const time = new Date(checkpoint.timestamp); + const timeStr = time.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }); + + const item = new vscode.TreeItem( + checkpoint.label, + vscode.TreeItemCollapsibleState.None, + ); + item.description = `${timeStr} (${fileCount} file${fileCount !== 1 ? "s" : ""})`; + item.iconPath = new vscode.ThemeIcon("history"); + item.tooltip = `Checkpoint: ${checkpoint.label}\nTime: ${time.toLocaleString()}\nFiles tracked: ${fileCount}\n\nClick to restore to this point`; + item.contextValue = "checkpoint"; + item.command = { + command: "gsd.restoreCheckpoint", + title: "Restore Checkpoint", + arguments: [checkpoint.id], + }; + + return item; + } + + getChildren(): Checkpoint[] { + // Show newest first + return [...this.tracker.checkpoints].reverse(); + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } +} diff --git a/vscode-extension/src/diagnostics.ts b/vscode-extension/src/diagnostics.ts new file mode 100644 index 000000000..cd25ccfee --- /dev/null +++ b/vscode-extension/src/diagnostics.ts @@ -0,0 +1,142 @@ +import * as vscode from "vscode"; +import type { GsdClient } from "./gsd-client.js"; + +/** + * Integrates with VS Code's diagnostic system: + * - Reads diagnostics (errors/warnings) from the Problems panel and sends them to the agent + * - Provides a DiagnosticCollection for the agent to surface its own findings + */ +export class GsdDiagnosticBridge implements vscode.Disposable { + private readonly collection: vscode.DiagnosticCollection; + private disposables: vscode.Disposable[] = []; + + constructor(private readonly client: GsdClient) { + this.collection = vscode.languages.createDiagnosticCollection("gsd"); + this.disposables.push(this.collection); + } + + /** + * Read all diagnostics for the active file and send them to the agent + * as a "fix these problems" prompt. + */ + async fixProblemsInFile(): Promise { + const editor = vscode.window.activeTextEditor; + if (!editor) { + vscode.window.showWarningMessage("No active file to fix."); + return; + } + + const uri = editor.document.uri; + const diagnostics = vscode.languages.getDiagnostics(uri); + + if (diagnostics.length === 0) { + vscode.window.showInformationMessage("No problems found in this file."); + return; + } + + const fileName = vscode.workspace.asRelativePath(uri); + const problemText = formatDiagnostics(fileName, diagnostics); + + const prompt = [ + `Fix the following problems in \`${fileName}\`:`, + "", + problemText, + "", + "Fix all of these issues. Show me the changes.", + ].join("\n"); + + await this.client.sendPrompt(prompt); + } + + /** + * Read all diagnostics across the workspace (errors only) and send + * them to the agent as a "fix all errors" prompt. + */ + async fixAllProblems(): Promise { + const allDiagnostics = vscode.languages.getDiagnostics(); + const errorFiles: { fileName: string; diagnostics: vscode.Diagnostic[] }[] = []; + + for (const [uri, diagnostics] of allDiagnostics) { + // Only include errors and warnings, skip hints/info + const significant = diagnostics.filter( + (d) => d.severity === vscode.DiagnosticSeverity.Error || d.severity === vscode.DiagnosticSeverity.Warning, + ); + if (significant.length > 0) { + errorFiles.push({ + fileName: vscode.workspace.asRelativePath(uri), + diagnostics: significant, + }); + } + } + + if (errorFiles.length === 0) { + vscode.window.showInformationMessage("No errors or warnings found in the workspace."); + return; + } + + // Cap at 20 files to avoid overwhelming the agent + const capped = errorFiles.slice(0, 20); + const totalProblems = capped.reduce((sum, f) => sum + f.diagnostics.length, 0); + + const sections = capped.map((f) => formatDiagnostics(f.fileName, f.diagnostics)); + + const prompt = [ + `Fix the following ${totalProblems} problems across ${capped.length} file${capped.length > 1 ? "s" : ""}:`, + "", + ...sections, + "", + "Fix all of these issues.", + ].join("\n"); + + await this.client.sendPrompt(prompt); + } + + /** + * Add a GSD diagnostic (agent finding) to a file. + * Can be used to surface agent review findings in the Problems panel. + */ + addFinding( + uri: vscode.Uri, + range: vscode.Range, + message: string, + severity: vscode.DiagnosticSeverity = vscode.DiagnosticSeverity.Warning, + ): void { + const existing = this.collection.get(uri) ?? []; + const diagnostic = new vscode.Diagnostic(range, message, severity); + diagnostic.source = "GSD Agent"; + this.collection.set(uri, [...existing, diagnostic]); + } + + /** Clear all GSD diagnostics */ + clearFindings(): void { + this.collection.clear(); + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } +} + +function formatDiagnostics(fileName: string, diagnostics: vscode.Diagnostic[]): string { + const lines = [`**${fileName}**`]; + for (const d of diagnostics) { + const severity = severityLabel(d.severity); + const line = d.range.start.line + 1; + const col = d.range.start.character + 1; + const source = d.source ? ` [${d.source}]` : ""; + lines.push(` - ${severity} (line ${line}:${col}): ${d.message}${source}`); + } + return lines.join("\n"); +} + +function severityLabel(severity: vscode.DiagnosticSeverity): string { + switch (severity) { + case vscode.DiagnosticSeverity.Error: return "Error"; + case vscode.DiagnosticSeverity.Warning: return "Warning"; + case vscode.DiagnosticSeverity.Information: return "Info"; + case vscode.DiagnosticSeverity.Hint: return "Hint"; + default: return "Unknown"; + } +} diff --git a/vscode-extension/src/extension.ts b/vscode-extension/src/extension.ts index d909c4e12..f5e494240 100644 --- a/vscode-extension/src/extension.ts +++ b/vscode-extension/src/extension.ts @@ -9,12 +9,24 @@ import { GsdConversationHistoryPanel } from "./conversation-history.js"; import { GsdSlashCompletionProvider } from "./slash-completion.js"; import { GsdCodeLensProvider } from "./code-lens.js"; import { GsdActivityFeedProvider } from "./activity-feed.js"; +import { GsdChangeTracker } from "./change-tracker.js"; +import { GsdScmProvider } from "./scm-provider.js"; +import { GsdDiagnosticBridge } from "./diagnostics.js"; +import { GsdLineDecorationManager } from "./line-decorations.js"; +import { GsdGitIntegration } from "./git-integration.js"; +import { GsdPermissionManager } from "./permissions.js"; let client: GsdClient | undefined; let sidebarProvider: GsdSidebarProvider | undefined; let fileDecorations: GsdFileDecorationProvider | undefined; let sessionTreeProvider: GsdSessionTreeProvider | undefined; let activityFeedProvider: GsdActivityFeedProvider | undefined; +let changeTracker: GsdChangeTracker | undefined; +let scmProvider: GsdScmProvider | undefined; +let diagnosticBridge: GsdDiagnosticBridge | undefined; +let lineDecorations: GsdLineDecorationManager | undefined; +let gitIntegration: GsdGitIntegration | undefined; +let permissionManager: GsdPermissionManager | undefined; function requireConnected(): boolean { if (!client?.isConnected) { @@ -128,6 +140,34 @@ export function activate(context: vscode.ExtensionContext): void { vscode.window.registerTreeDataProvider(GsdActivityFeedProvider.viewId, activityFeedProvider), ); + // -- Change tracker & SCM provider ------------------------------------- + + changeTracker = new GsdChangeTracker(client); + context.subscriptions.push(changeTracker); + + scmProvider = new GsdScmProvider(changeTracker, cwd); + context.subscriptions.push(scmProvider); + + // -- Diagnostics ------------------------------------------------------- + + diagnosticBridge = new GsdDiagnosticBridge(client); + context.subscriptions.push(diagnosticBridge); + + // -- Line-level decorations -------------------------------------------- + + lineDecorations = new GsdLineDecorationManager(changeTracker!); + context.subscriptions.push(lineDecorations); + + // -- Git integration --------------------------------------------------- + + gitIntegration = new GsdGitIntegration(changeTracker!, cwd); + context.subscriptions.push(gitIntegration); + + // -- Permissions ------------------------------------------------------- + + permissionManager = new GsdPermissionManager(client); + context.subscriptions.push(permissionManager); + // -- Progress notifications -------------------------------------------- let currentProgress: { resolve: () => void } | undefined; @@ -789,6 +829,135 @@ export function activate(context: vscode.ExtensionContext): void { }), ); + // -- SCM commands ------------------------------------------------------- + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.acceptAllChanges", () => { + changeTracker?.acceptAll(); + vscode.window.showInformationMessage("All agent changes accepted."); + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.discardAllChanges", async () => { + if (!changeTracker?.hasChanges) { + vscode.window.showInformationMessage("No agent changes to discard."); + return; + } + const confirm = await vscode.window.showWarningMessage( + `Discard all agent changes (${changeTracker.modifiedFiles.length} files)?`, + { modal: true }, + "Discard", + ); + if (confirm === "Discard") { + const count = await changeTracker.discardAll(); + vscode.window.showInformationMessage(`Reverted ${count} file${count !== 1 ? "s" : ""}.`); + } + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.discardFileChanges", async (resourceState: vscode.SourceControlResourceState) => { + if (!changeTracker || !resourceState?.resourceUri) return; + const filePath = resourceState.resourceUri.fsPath; + const success = await changeTracker.discardFile(filePath); + if (success) { + vscode.window.showInformationMessage(`Reverted ${vscode.workspace.asRelativePath(filePath)}`); + } + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.acceptFileChanges", (resourceState: vscode.SourceControlResourceState) => { + if (!changeTracker || !resourceState?.resourceUri) return; + changeTracker.acceptFile(resourceState.resourceUri.fsPath); + }), + ); + + // -- Checkpoint commands ------------------------------------------------ + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.restoreCheckpoint", async (checkpointId: number) => { + if (!changeTracker) return; + const checkpoint = changeTracker.checkpoints.find((c) => c.id === checkpointId); + if (!checkpoint) return; + + const confirm = await vscode.window.showWarningMessage( + `Restore to "${checkpoint.label}"? This will revert files to their state at ${new Date(checkpoint.timestamp).toLocaleTimeString()}.`, + { modal: true }, + "Restore", + ); + if (confirm === "Restore") { + const count = await changeTracker.restoreCheckpoint(checkpointId); + vscode.window.showInformationMessage(`Restored ${count} file${count !== 1 ? "s" : ""} to checkpoint.`); + } + }), + ); + + // -- Diagnostic commands ------------------------------------------------ + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.fixProblemsInFile", async () => { + if (!requireConnected()) return; + try { + await diagnosticBridge!.fixProblemsInFile(); + } catch (err) { + handleError(err, "Failed to fix problems"); + } + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.fixAllProblems", async () => { + if (!requireConnected()) return; + try { + await diagnosticBridge!.fixAllProblems(); + } catch (err) { + handleError(err, "Failed to fix problems"); + } + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.clearDiagnostics", () => { + diagnosticBridge?.clearFindings(); + }), + ); + + // -- Permission commands ------------------------------------------------ + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.cycleApprovalMode", () => { + permissionManager?.cycleMode(); + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.selectApprovalMode", () => { + permissionManager?.selectMode(); + }), + ); + + // -- Git commands ------------------------------------------------------- + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.commitAgentChanges", () => { + gitIntegration?.commitAgentChanges(); + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.createAgentBranch", () => { + gitIntegration?.createAgentBranch(); + }), + ); + + context.subscriptions.push( + vscode.commands.registerCommand("gsd.showAgentDiff", () => { + gitIntegration?.showAgentDiff(); + }), + ); + // -- Auto-start --------------------------------------------------------- if (config.get("autoStart", false)) { @@ -802,9 +971,21 @@ export function deactivate(): void { fileDecorations?.dispose(); sessionTreeProvider?.dispose(); activityFeedProvider?.dispose(); + changeTracker?.dispose(); + scmProvider?.dispose(); + diagnosticBridge?.dispose(); + lineDecorations?.dispose(); + gitIntegration?.dispose(); + permissionManager?.dispose(); client = undefined; sidebarProvider = undefined; fileDecorations = undefined; sessionTreeProvider = undefined; activityFeedProvider = undefined; + changeTracker = undefined; + scmProvider = undefined; + diagnosticBridge = undefined; + lineDecorations = undefined; + gitIntegration = undefined; + permissionManager = undefined; } diff --git a/vscode-extension/src/git-integration.ts b/vscode-extension/src/git-integration.ts new file mode 100644 index 000000000..82f727d51 --- /dev/null +++ b/vscode-extension/src/git-integration.ts @@ -0,0 +1,122 @@ +import * as vscode from "vscode"; +import { execFile } from "node:child_process"; +import type { GsdChangeTracker } from "./change-tracker.js"; + +/** + * Provides git integration for agent changes — commit, branch, and diff. + */ +export class GsdGitIntegration implements vscode.Disposable { + private disposables: vscode.Disposable[] = []; + + constructor( + private readonly tracker: GsdChangeTracker, + private readonly cwd: string, + ) {} + + /** + * Commit all files modified by the agent with a user-provided message. + */ + async commitAgentChanges(): Promise { + const files = this.tracker.modifiedFiles; + if (files.length === 0) { + vscode.window.showInformationMessage("No agent changes to commit."); + return; + } + + const defaultMsg = `feat: agent changes (${files.length} file${files.length !== 1 ? "s" : ""})`; + const message = await vscode.window.showInputBox({ + prompt: "Commit message for agent changes", + value: defaultMsg, + placeHolder: "feat: describe the changes", + }); + if (!message) return; + + try { + // Stage the modified files + await this.git(["add", ...files]); + // Commit + await this.git(["commit", "-m", message]); + + // Accept all changes (clear tracking since they're committed) + this.tracker.acceptAll(); + + vscode.window.showInformationMessage(`Committed ${files.length} file${files.length !== 1 ? "s" : ""}.`); + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + vscode.window.showErrorMessage(`Git commit failed: ${msg}`); + } + } + + /** + * Create a new branch for agent work and switch to it. + */ + async createAgentBranch(): Promise { + const branchName = await vscode.window.showInputBox({ + prompt: "Branch name for agent work", + placeHolder: "feat/agent-changes", + validateInput: (value) => { + if (!value.trim()) return "Branch name is required"; + if (/\s/.test(value)) return "Branch name cannot contain spaces"; + return null; + }, + }); + if (!branchName) return; + + try { + await this.git(["checkout", "-b", branchName]); + vscode.window.showInformationMessage(`Created and switched to branch: ${branchName}`); + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + vscode.window.showErrorMessage(`Failed to create branch: ${msg}`); + } + } + + /** + * Show a git diff of all agent-modified files. + */ + async showAgentDiff(): Promise { + const files = this.tracker.modifiedFiles; + if (files.length === 0) { + vscode.window.showInformationMessage("No agent changes to diff."); + return; + } + + try { + const diff = await this.git(["diff"]); + if (!diff.trim()) { + // Files may be untracked — show status instead + const status = await this.git(["status", "--short"]); + const channel = vscode.window.createOutputChannel("GSD Git Diff"); + channel.appendLine("# Agent-modified files (unstaged):"); + channel.appendLine(status); + channel.show(); + } else { + const channel = vscode.window.createOutputChannel("GSD Git Diff"); + channel.clear(); + channel.appendLine(diff); + channel.show(); + } + } catch (err) { + const msg = err instanceof Error ? err.message : String(err); + vscode.window.showErrorMessage(`Git diff failed: ${msg}`); + } + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } + + private git(args: string[]): Promise { + return new Promise((resolve, reject) => { + execFile("git", args, { cwd: this.cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => { + if (err) { + reject(new Error(stderr.trim() || err.message)); + } else { + resolve(stdout); + } + }); + }); + } +} diff --git a/vscode-extension/src/gsd-client.ts b/vscode-extension/src/gsd-client.ts index b8ae2bc35..ef6d65978 100644 --- a/vscode-extension/src/gsd-client.ts +++ b/vscode-extension/src/gsd-client.ts @@ -123,7 +123,7 @@ export class GsdClient implements vscode.Disposable { return; } - const proc = spawn(this.binaryPath, ["--mode", "rpc", "--no-session"], { + const proc = spawn(this.binaryPath, ["--mode", "rpc"], { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"], env: { ...process.env }, @@ -580,10 +580,104 @@ export class GsdClient implements vscode.Disposable { return; } + // Extension UI request — agent needs user input + if (data.type === "extension_ui_request" && typeof data.id === "string") { + void this.handleUIRequest(data); + return; + } + // Streaming event this._onEvent.fire(data as AgentEvent); } + private async handleUIRequest(request: Record): Promise { + const id = request.id as string; + const method = request.method as string; + + try { + switch (method) { + case "select": { + const options = (request.options as string[]) ?? []; + const title = String(request.title ?? "Select"); + const allowMultiple = request.allowMultiple === true; + + if (allowMultiple) { + const picked = await vscode.window.showQuickPick(options, { + title, + canPickMany: true, + }); + if (picked) { + this.sendRaw({ type: "extension_ui_response", id, values: picked }); + } else { + this.sendRaw({ type: "extension_ui_response", id, cancelled: true }); + } + } else { + const picked = await vscode.window.showQuickPick(options, { title }); + if (picked) { + this.sendRaw({ type: "extension_ui_response", id, value: picked }); + } else { + this.sendRaw({ type: "extension_ui_response", id, cancelled: true }); + } + } + break; + } + + case "confirm": { + const title = String(request.title ?? "Confirm"); + const message = String(request.message ?? ""); + const result = await vscode.window.showInformationMessage( + `${title}: ${message}`, + { modal: true }, + "Yes", + "No", + ); + this.sendRaw({ type: "extension_ui_response", id, confirmed: result === "Yes" }); + break; + } + + case "input": { + const title = String(request.title ?? "Input"); + const placeholder = String(request.placeholder ?? ""); + const value = await vscode.window.showInputBox({ title, placeHolder: placeholder }); + if (value !== undefined) { + this.sendRaw({ type: "extension_ui_response", id, value }); + } else { + this.sendRaw({ type: "extension_ui_response", id, cancelled: true }); + } + break; + } + + case "notify": { + const message = String(request.message ?? ""); + const notifyType = String(request.notifyType ?? "info"); + if (notifyType === "error") { + vscode.window.showErrorMessage(`GSD: ${message}`); + } else if (notifyType === "warning") { + vscode.window.showWarningMessage(`GSD: ${message}`); + } else { + vscode.window.showInformationMessage(`GSD: ${message}`); + } + // Notify doesn't need a response + break; + } + + default: + // Unknown method — cancel to unblock the agent + this.sendRaw({ type: "extension_ui_response", id, cancelled: true }); + break; + } + } catch { + // On error, cancel to unblock + this.sendRaw({ type: "extension_ui_response", id, cancelled: true }); + } + } + + private sendRaw(data: Record): void { + if (this.process?.stdin) { + this.process.stdin.write(JSON.stringify(data) + "\n"); + } + } + private send(command: Record): Promise { if (!this.process?.stdin) { return Promise.reject(new Error("GSD client not started")); diff --git a/vscode-extension/src/line-decorations.ts b/vscode-extension/src/line-decorations.ts new file mode 100644 index 000000000..387986f79 --- /dev/null +++ b/vscode-extension/src/line-decorations.ts @@ -0,0 +1,130 @@ +import * as vscode from "vscode"; +import type { GsdChangeTracker } from "./change-tracker.js"; + +/** + * Provides line-level editor decorations for files modified by the GSD agent. + * Shows subtle background highlights on changed lines and gutter icons. + */ +export class GsdLineDecorationManager implements vscode.Disposable { + private readonly addedDecoration: vscode.TextEditorDecorationType; + private readonly modifiedDecoration: vscode.TextEditorDecorationType; + private readonly gutterDecoration: vscode.TextEditorDecorationType; + private disposables: vscode.Disposable[] = []; + + constructor(private readonly tracker: GsdChangeTracker) { + this.addedDecoration = vscode.window.createTextEditorDecorationType({ + isWholeLine: true, + backgroundColor: "rgba(78, 201, 176, 0.07)", + overviewRulerColor: "rgba(78, 201, 176, 0.5)", + overviewRulerLane: vscode.OverviewRulerLane.Left, + }); + + this.modifiedDecoration = vscode.window.createTextEditorDecorationType({ + isWholeLine: true, + backgroundColor: "rgba(204, 167, 0, 0.07)", + overviewRulerColor: "rgba(204, 167, 0, 0.5)", + overviewRulerLane: vscode.OverviewRulerLane.Left, + }); + + this.gutterDecoration = vscode.window.createTextEditorDecorationType({ + gutterIconPath: new vscode.ThemeIcon("hubot").id, // fallback + gutterIconSize: "contain", + // Use a colored left border as a gutter indicator (more reliable than icons) + borderWidth: "0 0 0 3px", + borderStyle: "solid", + borderColor: "rgba(78, 201, 176, 0.4)", + }); + + this.disposables.push( + this.addedDecoration, + this.modifiedDecoration, + this.gutterDecoration, + ); + + // Refresh decorations when tracked files change + this.disposables.push( + tracker.onDidChange(() => this.refreshAll()), + vscode.window.onDidChangeActiveTextEditor(() => this.refreshAll()), + vscode.workspace.onDidChangeTextDocument((e) => { + const editor = vscode.window.activeTextEditor; + if (editor && e.document === editor.document) { + this.refreshEditor(editor); + } + }), + ); + } + + private refreshAll(): void { + for (const editor of vscode.window.visibleTextEditors) { + this.refreshEditor(editor); + } + } + + private refreshEditor(editor: vscode.TextEditor): void { + const filePath = editor.document.uri.fsPath; + const original = this.tracker.getOriginal(filePath); + + if (original === undefined) { + // No tracked changes for this file — clear decorations + editor.setDecorations(this.addedDecoration, []); + editor.setDecorations(this.modifiedDecoration, []); + editor.setDecorations(this.gutterDecoration, []); + return; + } + + const currentLines = editor.document.getText().split("\n"); + const originalLines = original.split("\n"); + const { added, modified } = diffLines(originalLines, currentLines); + + const addedRanges = added.map((line) => { + const range = new vscode.Range(line, 0, line, currentLines[line]?.length ?? 0); + return { range, hoverMessage: new vscode.MarkdownString("$(hubot) *Added by GSD Agent*") }; + }); + + const modifiedRanges = modified.map((line) => { + const range = new vscode.Range(line, 0, line, currentLines[line]?.length ?? 0); + return { range, hoverMessage: new vscode.MarkdownString("$(hubot) *Modified by GSD Agent*") }; + }); + + const gutterRanges = [...added, ...modified].map((line) => ({ + range: new vscode.Range(line, 0, line, 0), + })); + + editor.setDecorations(this.addedDecoration, addedRanges); + editor.setDecorations(this.modifiedDecoration, modifiedRanges); + editor.setDecorations(this.gutterDecoration, gutterRanges); + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } +} + +/** + * Simple line-level diff: compare original vs current line-by-line. + * Returns arrays of line numbers that were added or modified. + */ +function diffLines( + originalLines: string[], + currentLines: string[], +): { added: number[]; modified: number[] } { + const added: number[] = []; + const modified: number[] = []; + + const maxShared = Math.min(originalLines.length, currentLines.length); + + for (let i = 0; i < maxShared; i++) { + if (originalLines[i] !== currentLines[i]) { + modified.push(i); + } + } + + // Lines beyond original length are "added" + for (let i = originalLines.length; i < currentLines.length; i++) { + added.push(i); + } + + return { added, modified }; +} diff --git a/vscode-extension/src/permissions.ts b/vscode-extension/src/permissions.ts new file mode 100644 index 000000000..32bcc9511 --- /dev/null +++ b/vscode-extension/src/permissions.ts @@ -0,0 +1,143 @@ +import * as vscode from "vscode"; +import type { GsdClient, AgentEvent } from "./gsd-client.js"; + +type ApprovalMode = "ask" | "auto-approve" | "plan-only"; + +/** + * Permission/approval system for agent actions. + * Can be configured to prompt before file writes, command execution, etc. + */ +export class GsdPermissionManager implements vscode.Disposable { + private _mode: ApprovalMode = "auto-approve"; + private disposables: vscode.Disposable[] = []; + + private readonly _onModeChange = new vscode.EventEmitter(); + readonly onModeChange = this._onModeChange.event; + + constructor(private readonly client: GsdClient) { + // Load saved mode from configuration + this._mode = vscode.workspace.getConfiguration("gsd").get("approvalMode", "auto-approve"); + + this.disposables.push( + this._onModeChange, + vscode.workspace.onDidChangeConfiguration((e) => { + if (e.affectsConfiguration("gsd.approvalMode")) { + this._mode = vscode.workspace.getConfiguration("gsd").get("approvalMode", "auto-approve"); + this._onModeChange.fire(this._mode); + } + }), + ); + + // If mode is "ask", intercept tool executions for write operations + if (this._mode === "ask") { + this.disposables.push( + client.onEvent((evt) => this.handleEvent(evt)), + ); + } + } + + get mode(): ApprovalMode { + return this._mode; + } + + /** + * Cycle through approval modes: auto-approve -> ask -> plan-only -> auto-approve + */ + async cycleMode(): Promise { + const modes: ApprovalMode[] = ["auto-approve", "ask", "plan-only"]; + const currentIdx = modes.indexOf(this._mode); + this._mode = modes[(currentIdx + 1) % modes.length]; + + await vscode.workspace.getConfiguration("gsd").update("approvalMode", this._mode, vscode.ConfigurationTarget.Workspace); + this._onModeChange.fire(this._mode); + + const labels: Record = { + "auto-approve": "Auto-Approve (agent runs freely)", + "ask": "Ask (prompt before file changes)", + "plan-only": "Plan Only (read-only, no writes)", + }; + vscode.window.showInformationMessage(`Approval mode: ${labels[this._mode]}`); + } + + /** + * Show a QuickPick to select approval mode. + */ + async selectMode(): Promise { + const items: (vscode.QuickPickItem & { mode: ApprovalMode })[] = [ + { + label: "$(check) Auto-Approve", + description: "Agent runs freely without prompts", + detail: "Best for trusted workflows. The agent can read, write, and execute without asking.", + mode: "auto-approve", + }, + { + label: "$(shield) Ask", + description: "Prompt before file changes", + detail: "The agent will ask for approval before writing or editing files.", + mode: "ask", + }, + { + label: "$(eye) Plan Only", + description: "Read-only mode, no writes allowed", + detail: "The agent can read and analyze but cannot modify files or run commands.", + mode: "plan-only", + }, + ]; + + const selected = await vscode.window.showQuickPick(items, { + placeHolder: `Current mode: ${this._mode}`, + }); + + if (selected) { + this._mode = selected.mode; + await vscode.workspace.getConfiguration("gsd").update("approvalMode", this._mode, vscode.ConfigurationTarget.Workspace); + this._onModeChange.fire(this._mode); + } + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } + + private async handleEvent(evt: AgentEvent): Promise { + if (this._mode !== "ask") return; + if (evt.type !== "tool_execution_start") return; + + const toolName = String(evt.toolName ?? ""); + if (toolName !== "Write" && toolName !== "Edit" && toolName !== "Bash") return; + + const toolInput = (evt.toolInput ?? {}) as Record; + let description = ""; + + switch (toolName) { + case "Write": + case "Edit": { + const filePath = String(toolInput.file_path ?? ""); + const shortPath = filePath.split(/[\\/]/).slice(-3).join("/"); + description = `${toolName}: ${shortPath}`; + break; + } + case "Bash": { + const cmd = String(toolInput.command ?? "").slice(0, 80); + description = `Execute: ${cmd}`; + break; + } + } + + // Note: In practice, the RPC protocol doesn't support blocking tool execution + // for approval. This notification serves as awareness — the user sees what's + // happening and can abort if needed. True blocking approval would require + // protocol changes in the RPC server. + vscode.window.showInformationMessage( + `Agent: ${description}`, + "OK", + "Abort", + ).then((choice) => { + if (choice === "Abort") { + this.client.abort().catch(() => {}); + } + }); + } +} diff --git a/vscode-extension/src/plan-viewer.ts b/vscode-extension/src/plan-viewer.ts new file mode 100644 index 000000000..a45b20978 --- /dev/null +++ b/vscode-extension/src/plan-viewer.ts @@ -0,0 +1,190 @@ +import * as vscode from "vscode"; +import type { GsdClient, AgentEvent } from "./gsd-client.js"; + +interface PlanStep { + id: number; + tool: string; + description: string; + status: "pending" | "running" | "done" | "error"; + timestamp: number; + duration?: number; +} + +/** + * TreeDataProvider that shows a plan-like view of agent tool executions. + * Displays steps as they happen, showing what the agent is doing and + * what it has completed — a live execution plan. + */ +export class GsdPlanViewerProvider implements vscode.TreeDataProvider, vscode.Disposable { + public static readonly viewId = "gsd-plan"; + + private readonly _onDidChangeTreeData = new vscode.EventEmitter(); + readonly onDidChangeTreeData = this._onDidChangeTreeData.event; + + private steps: PlanStep[] = []; + private nextId = 0; + private runningTools = new Map(); // toolUseId -> step id + private disposables: vscode.Disposable[] = []; + + constructor(private readonly client: GsdClient) { + this.disposables.push( + this._onDidChangeTreeData, + client.onEvent((evt) => this.handleEvent(evt)), + client.onConnectionChange((connected) => { + if (!connected) { + this.steps = []; + this.runningTools.clear(); + this._onDidChangeTreeData.fire(); + } + }), + ); + } + + getTreeItem(step: PlanStep): vscode.TreeItem { + const icon = stepIcon(step.status); + const item = new vscode.TreeItem(step.description, vscode.TreeItemCollapsibleState.None); + item.iconPath = icon; + item.description = step.duration !== undefined ? `${step.duration}ms` : step.status === "running" ? "running..." : ""; + + const time = new Date(step.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" }); + item.tooltip = `${step.tool}: ${step.description}\nStatus: ${step.status}\nTime: ${time}`; + + return item; + } + + getChildren(): PlanStep[] { + return this.steps; + } + + clear(): void { + this.steps = []; + this.runningTools.clear(); + this._onDidChangeTreeData.fire(); + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } + + private handleEvent(evt: AgentEvent): void { + switch (evt.type) { + case "agent_start": { + // Don't clear — keep history visible. Add a separator. + if (this.steps.length > 0) { + this.steps.push({ + id: this.nextId++, + tool: "separator", + description: "--- New Turn ---", + status: "done", + timestamp: Date.now(), + }); + } + this.steps.push({ + id: this.nextId++, + tool: "agent", + description: "Agent started", + status: "running", + timestamp: Date.now(), + }); + this._onDidChangeTreeData.fire(); + break; + } + + case "agent_end": { + // Mark the agent step as done + const agentStep = [...this.steps].reverse().find((s) => s.tool === "agent" && s.status === "running"); + if (agentStep) { + agentStep.status = "done"; + agentStep.duration = Date.now() - agentStep.timestamp; + agentStep.description = "Agent finished"; + } + this._onDidChangeTreeData.fire(); + break; + } + + case "tool_execution_start": { + const toolName = String(evt.toolName ?? ""); + const toolInput = (evt.toolInput ?? {}) as Record; + const toolUseId = String(evt.toolUseId ?? ""); + const description = describeStep(toolName, toolInput); + + const id = this.nextId++; + this.steps.push({ + id, + tool: toolName, + description, + status: "running", + timestamp: Date.now(), + }); + + if (toolUseId) { + this.runningTools.set(toolUseId, id); + } + + // Cap at 200 steps + while (this.steps.length > 200) { + this.steps.shift(); + } + + this._onDidChangeTreeData.fire(); + break; + } + + case "tool_execution_end": { + const toolUseId = String(evt.toolUseId ?? ""); + const stepId = this.runningTools.get(toolUseId); + if (stepId !== undefined) { + this.runningTools.delete(toolUseId); + const step = this.steps.find((s) => s.id === stepId); + if (step) { + const isError = evt.error === true || evt.isError === true; + step.status = isError ? "error" : "done"; + step.duration = Date.now() - step.timestamp; + this._onDidChangeTreeData.fire(); + } + } + break; + } + } + } +} + +function stepIcon(status: string): vscode.ThemeIcon { + switch (status) { + case "running": + return new vscode.ThemeIcon("sync~spin", new vscode.ThemeColor("charts.yellow")); + case "done": + return new vscode.ThemeIcon("pass", new vscode.ThemeColor("testing.iconPassed")); + case "error": + return new vscode.ThemeIcon("error", new vscode.ThemeColor("testing.iconFailed")); + default: + return new vscode.ThemeIcon("circle-outline"); + } +} + +function describeStep(toolName: string, input: Record): string { + switch (toolName) { + case "Read": { + const p = String(input.file_path ?? input.path ?? ""); + return `Read ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Write": { + const p = String(input.file_path ?? ""); + return `Write ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Edit": { + const p = String(input.file_path ?? ""); + return `Edit ${p.split(/[\\/]/).pop() ?? p}`; + } + case "Bash": + return `$ ${String(input.command ?? "").slice(0, 50)}`; + case "Grep": + return `Grep: ${String(input.pattern ?? "").slice(0, 40)}`; + case "Glob": + return `Glob: ${String(input.pattern ?? "").slice(0, 40)}`; + default: + return toolName; + } +} diff --git a/vscode-extension/src/scm-provider.ts b/vscode-extension/src/scm-provider.ts new file mode 100644 index 000000000..2320ab6d5 --- /dev/null +++ b/vscode-extension/src/scm-provider.ts @@ -0,0 +1,124 @@ +import * as vscode from "vscode"; +import * as path from "node:path"; +import type { GsdChangeTracker } from "./change-tracker.js"; + +const GSD_ORIGINAL_SCHEME = "gsd-original"; + +/** + * Source Control provider that shows files modified by the GSD agent + * in a dedicated "GSD Agent" section of the Source Control panel. + * Supports QuickDiff to show before/after diffs, and accept/discard per-file. + */ +export class GsdScmProvider implements vscode.Disposable { + private readonly scm: vscode.SourceControl; + private readonly changesGroup: vscode.SourceControlResourceGroup; + private readonly contentProvider: GsdOriginalContentProvider; + private disposables: vscode.Disposable[] = []; + + constructor( + private readonly tracker: GsdChangeTracker, + private readonly workspaceRoot: string, + ) { + // Register content provider for original file contents + this.contentProvider = new GsdOriginalContentProvider(tracker); + this.disposables.push( + vscode.workspace.registerTextDocumentContentProvider( + GSD_ORIGINAL_SCHEME, + this.contentProvider, + ), + ); + + // Create source control instance + this.scm = vscode.scm.createSourceControl( + "gsd", + "GSD Agent", + vscode.Uri.file(workspaceRoot), + ); + this.scm.quickDiffProvider = { + provideOriginalResource: (uri: vscode.Uri): vscode.Uri | undefined => { + const filePath = uri.fsPath; + if (this.tracker.getOriginal(filePath) !== undefined) { + return uri.with({ scheme: GSD_ORIGINAL_SCHEME }); + } + return undefined; + }, + }; + this.scm.inputBox.placeholder = "Describe changes to accept..."; + this.scm.acceptInputCommand = { + command: "gsd.acceptAllChanges", + title: "Accept All", + }; + this.scm.count = 0; + this.disposables.push(this.scm); + + // Create resource group + this.changesGroup = this.scm.createResourceGroup("changes", "Agent Changes"); + this.changesGroup.hideWhenEmpty = true; + this.disposables.push(this.changesGroup); + + // Listen for change tracker updates + this.disposables.push( + tracker.onDidChange(() => this.refresh()), + ); + + this.refresh(); + } + + private refresh(): void { + const files = this.tracker.modifiedFiles; + this.changesGroup.resourceStates = files.map((filePath) => { + const uri = vscode.Uri.file(filePath); + const fileName = path.basename(filePath); + const relativePath = path.relative(this.workspaceRoot, filePath); + + const state: vscode.SourceControlResourceState = { + resourceUri: uri, + decorations: { + strikeThrough: false, + tooltip: `Modified by GSD Agent`, + light: { iconPath: new vscode.ThemeIcon("edit") }, + dark: { iconPath: new vscode.ThemeIcon("edit") }, + }, + command: { + command: "vscode.diff", + title: "Show Changes", + arguments: [ + uri.with({ scheme: GSD_ORIGINAL_SCHEME }), + uri, + `${fileName} (GSD Agent Changes)`, + ], + }, + }; + return state; + }); + this.scm.count = files.length; + } + + dispose(): void { + for (const d of this.disposables) { + d.dispose(); + } + } +} + +/** + * TextDocumentContentProvider that serves the original (pre-agent) content + * of files via the `gsd-original:` URI scheme. + */ +class GsdOriginalContentProvider implements vscode.TextDocumentContentProvider { + private readonly _onDidChange = new vscode.EventEmitter(); + readonly onDidChange = this._onDidChange.event; + + constructor(private readonly tracker: GsdChangeTracker) { + tracker.onDidChange((paths) => { + for (const p of paths) { + this._onDidChange.fire(vscode.Uri.file(p).with({ scheme: GSD_ORIGINAL_SCHEME })); + } + }); + } + + provideTextDocumentContent(uri: vscode.Uri): string { + const filePath = uri.with({ scheme: "file" }).fsPath; + return this.tracker.getOriginal(filePath) ?? ""; + } +} diff --git a/vscode-extension/src/session-tree.ts b/vscode-extension/src/session-tree.ts index e61898e0a..a38413be4 100644 --- a/vscode-extension/src/session-tree.ts +++ b/vscode-extension/src/session-tree.ts @@ -56,18 +56,35 @@ export class GsdSessionTreeProvider implements vscode.TreeDataProvider_.jsonl - const match = file.match(/^(\d+)_(.+)\.jsonl$/); - if (!match) { + const sessionFile = path.join(sessionDir, file); + + // Try two filename formats: + // 1. ISO timestamp: 2026-03-23T17-49-05-784Z_.jsonl + // 2. Unix timestamp: _.jsonl + const isoMatch = file.match(/^(\d{4}-\d{2}-\d{2}T[\d-]+Z)_(.+)\.jsonl$/); + const unixMatch = file.match(/^(\d{10,})_(.+)\.jsonl$/); + + let timestamp: Date; + let sessionId: string; + + if (isoMatch) { + // Convert ISO-like format (dashes instead of colons) back to parseable ISO + const isoStr = isoMatch[1].replace(/(\d{4}-\d{2}-\d{2}T\d{2})-(\d{2})-(\d{2})-(\d+)Z/, "$1:$2:$3.$4Z"); + timestamp = new Date(isoStr); + sessionId = isoMatch[2]; + } else if (unixMatch) { + timestamp = new Date(parseInt(unixMatch[1], 10)); + sessionId = unixMatch[2]; + } else { continue; } - const ts = parseInt(match[1], 10); - const sessionId = match[2]; - const sessionFile = path.join(sessionDir, file); + + if (isNaN(timestamp.getTime())) continue; + items.push({ - label: formatDate(new Date(ts)), + label: formatDate(timestamp), sessionFile, - timestamp: new Date(ts), + timestamp, sessionId, isCurrent: sessionFile === state.sessionFile, }); diff --git a/vscode-extension/src/sidebar.ts b/vscode-extension/src/sidebar.ts index 12c718633..b8bb2aee0 100644 --- a/vscode-extension/src/sidebar.ts +++ b/vscode-extension/src/sidebar.ts @@ -2,8 +2,17 @@ import * as vscode from "vscode"; import type { GsdClient, SessionStats, ThinkingLevel } from "./gsd-client.js"; /** - * WebviewViewProvider that renders a sidebar panel showing connection status, - * model info, thinking level, token usage, cost, and quick action controls. + * Send a message through VS Code's Chat panel so the user sees the response. + * Opens the Chat panel and pre-fills the @gsd participant with the message. + */ +async function sendViaChat(message: string): Promise { + await vscode.commands.executeCommand("workbench.action.chat.open", { query: message }); +} + +/** + * WebviewViewProvider that renders a compact, card-based sidebar panel. + * Designed for information density without clutter — collapsible sections, + * hidden empty data, and consolidated action buttons. */ export class GsdSidebarProvider implements vscode.WebviewViewProvider { public static readonly viewId = "gsd-sidebar"; @@ -106,22 +115,18 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { await vscode.commands.executeCommand("gsd.copyLastResponse"); break; case "autoMode": - if (this.client.isConnected) { - await this.client.sendPrompt("/gsd auto").catch(() => {}); - } + await sendViaChat("@gsd /gsd auto"); break; case "nextUnit": - if (this.client.isConnected) { - await this.client.sendPrompt("/gsd next").catch(() => {}); - } + await sendViaChat("@gsd /gsd next"); break; case "quickTask": { const quickInput = await vscode.window.showInputBox({ prompt: "Describe the quick task", placeHolder: "e.g. fix the typo in README", }); - if (quickInput && this.client.isConnected) { - await this.client.sendPrompt(`/gsd quick ${quickInput}`).catch(() => {}); + if (quickInput) { + await sendViaChat(`@gsd /gsd quick ${quickInput}`); } break; } @@ -130,15 +135,13 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { prompt: "Capture a thought", placeHolder: "e.g. we should also handle the edge case for...", }); - if (thought && this.client.isConnected) { - await this.client.sendPrompt(`/gsd capture ${thought}`).catch(() => {}); + if (thought) { + await sendViaChat(`@gsd /gsd capture ${thought}`); } break; } case "status": - if (this.client.isConnected) { - await this.client.sendPrompt("/gsd status").catch(() => {}); - } + await sendViaChat("@gsd /gsd status"); break; case "forkSession": await vscode.commands.executeCommand("gsd.forkSession"); @@ -149,6 +152,9 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { case "toggleFollowUpMode": await vscode.commands.executeCommand("gsd.toggleFollowUpMode"); break; + case "showHistory": + await vscode.commands.executeCommand("gsd.showHistory"); + break; } }); @@ -168,6 +174,7 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { } let modelName = "N/A"; + let modelShort = ""; let sessionId = "N/A"; let sessionName = ""; let messageCount = 0; @@ -189,6 +196,7 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { modelName = state.model ? `${state.model.provider}/${state.model.id}` : "Not set"; + modelShort = state.model?.id ?? ""; sessionId = state.sessionId; sessionName = state.sessionName ?? ""; messageCount = state.messageCount; @@ -216,6 +224,7 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { this.view.webview.html = this.getHtml({ connected, modelName, + modelShort, sessionId, sessionName, messageCount, @@ -244,6 +253,7 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { private getHtml(info: { connected: boolean; modelName: string; + modelShort: string; sessionId: string; sessionName: string; messageCount: number; @@ -259,57 +269,49 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { followUpMode: "all" | "one-at-a-time"; }): string { const statusColor = info.connected ? "#4ec9b0" : "#f44747"; - const statusText = info.connected - ? info.isStreaming - ? "Processing..." - : info.isCompacting - ? "Compacting..." - : "Connected" - : "Disconnected"; + const statusLabel = info.isStreaming ? "Working" : info.isCompacting ? "Compacting" : info.connected ? "Connected" : "Disconnected"; - const inputTokens = info.stats?.inputTokens?.toLocaleString() ?? "-"; - const outputTokens = info.stats?.outputTokens?.toLocaleString() ?? "-"; - const cacheRead = info.stats?.cacheReadTokens?.toLocaleString() ?? "-"; - const cacheWrite = info.stats?.cacheWriteTokens?.toLocaleString() ?? "-"; - const turnCount = info.stats?.turnCount?.toString() ?? "-"; - const duration = info.stats?.duration !== undefined - ? `${Math.round(info.stats.duration / 1000)}s` - : "-"; - const cost = info.stats?.totalCost !== undefined ? `$${info.stats.totalCost.toFixed(4)}` : "-"; + // Model short name for header + const modelDisplay = info.modelShort || "N/A"; - const thinkingBadge = info.thinkingLevel !== "off" - ? `${info.thinkingLevel}` - : `off`; + // Session display — name or truncated ID + const sessionDisplay = info.sessionName || (info.sessionId !== "N/A" ? info.sessionId.slice(0, 8) : "N/A"); - const autoCompBadge = info.autoCompaction - ? `on` - : `off`; - - const autoRetryBadge = info.autoRetry - ? `on` - : `off`; - - const streamingIndicator = info.isStreaming - ? `
Agent is working...
` + // Cost for header + const costDisplay = info.stats?.totalCost !== undefined && info.stats.totalCost > 0 + ? `$${info.stats.totalCost.toFixed(4)}` : ""; - // Context window usage + // Context window const totalTokens = (info.stats?.inputTokens ?? 0) + (info.stats?.outputTokens ?? 0); const contextPct = info.contextWindow > 0 ? Math.min(100, Math.round((totalTokens / info.contextWindow) * 100)) : 0; const contextColor = contextPct > 80 ? "#f44747" : contextPct > 50 ? "#cca700" : "#4ec9b0"; - const contextLabel = info.contextWindow > 0 - ? `${contextPct}% (${Math.round(totalTokens / 1000)}k / ${Math.round(info.contextWindow / 1000)}k)` - : "N/A"; - const steeringBadge = info.steeringMode === "one-at-a-time" - ? `1-at-a-time` - : `all`; - const followUpBadge = info.followUpMode === "one-at-a-time" - ? `1-at-a-time` - : `all`; + // Only show stats that have real data + const hasStats = info.stats && ( + (info.stats.inputTokens !== undefined && info.stats.inputTokens > 0) || + (info.stats.outputTokens !== undefined && info.stats.outputTokens > 0) + ); const nonce = getNonce(); + // Build stat rows only for non-zero values + let statRows = ""; + if (hasStats && info.stats) { + const pairs: [string, string][] = []; + if (info.stats.inputTokens) pairs.push(["In", formatNum(info.stats.inputTokens)]); + if (info.stats.outputTokens) pairs.push(["Out", formatNum(info.stats.outputTokens)]); + if (info.stats.cacheReadTokens) pairs.push(["Cache R", formatNum(info.stats.cacheReadTokens)]); + if (info.stats.cacheWriteTokens) pairs.push(["Cache W", formatNum(info.stats.cacheWriteTokens)]); + if (info.stats.turnCount) pairs.push(["Turns", String(info.stats.turnCount)]); + if (info.stats.duration) pairs.push(["Time", `${Math.round(info.stats.duration / 1000)}s`]); + if (info.stats.totalCost !== undefined && info.stats.totalCost > 0) pairs.push(["Cost", `$${info.stats.totalCost.toFixed(4)}`]); + + statRows = pairs.map(([k, v]) => + `${k}${v}` + ).join(""); + } + return /* html */ ` @@ -317,291 +319,329 @@ export class GsdSidebarProvider implements vscode.WebviewViewProvider { -
-
- ${statusText} -
- - ${streamingIndicator} - -
-
Session
- - - - - - - - - - - - - - - - - - - - - - - - - - - -
Model${escapeHtml(info.modelName)}
Session - ${escapeHtml(info.sessionName || info.sessionId)} - ${info.connected ? `✎` : ""} -
Messages${info.messageCount}${info.pendingMessageCount > 0 ? ` +${info.pendingMessageCount} pending` : ""}
Thinking${thinkingBadge}
Auto-compact${autoCompBadge}
Auto-retry${autoRetryBadge}
Steering${info.steeringMode === "one-at-a-time" ? "1-at-a-time" : "all"}
Follow-up${info.followUpMode === "one-at-a-time" ? "1-at-a-time" : "all"}
-
- - ${info.connected && info.stats ? ` -
-
Token Usage
-
- Input - ${inputTokens} - Output - ${outputTokens} - Cache read - ${cacheRead} - Cache write - ${cacheWrite} - Turns - ${turnCount} - Duration - ${duration} - Cost - ${cost} + ${info.connected ? this.getConnectedHtml(info, { + statusLabel, + modelDisplay, + sessionDisplay, + costDisplay, + contextPct, + contextColor, + hasStats: !!hasStats, + statRows, + nonce, + }) : ` +
+
+
+ Disconnected
- - ${info.contextWindow > 0 ? ` -
-
Context Window
-
-
-
-
${contextLabel}
+
+

Agent is not running

+
- ` : ""} - ` : ""} - - ${info.connected ? ` -
-
Workflow
-
-
- - -
-
- - -
-
- - -
-
-
- ` : ""} - -
-
Controls
-
- ${info.connected - ? ` -
- - -
-
- - -
-
- - -
` - : `` - } -
-
- - ${info.connected ? ` -
-
Actions
-
-
- - -
-
- - -
-
-
- ` : ""} + `}