@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/codebase-to-spec/cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cache directory layout and path helpers for codebase-to-spec.
+ *
+ * All pipeline artifacts live under `.dotrequirements-cache/` in the project
+ * root. Wrappers and downstream stages read cached inputs by these paths;
+ * resumability (CTS-RESUME-1..4) is driven by the presence/absence of these
+ * files.
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: pack stage paths (overview.txt, source.txt)
+ * - CTS-RESUME-1..4: per-stage cache detection
+ */
+export declare const CACHE_DIR_NAME = ".dotrequirements-cache";
+export interface CachePaths {
+    /** Root cache directory (relative to project root). */
+    root: string;
+    /** Compressed pack — input for the planner and reviewers. */
+    overview: string;
+    /** Uncompressed pack — source for specifier slices. */
+    source: string;
+    /** Approved outline (after planning + review-loop convergence). */
+    outlineFinal: string;
+    /** Per-turn outline files: outline-1.json, outline-2.json, ... */
+    outlineTurn(n: number): string;
+    /** Per-turn outline reviewer JSON output. */
+    outlineReviewTurn(n: number): string;
+    /** Partials directory. */
+    partialsDir: string;
+    /** Partial file for a given sanitized area name. */
+    partial(sanitizedAreaName: string): string;
+    /** Composed spec, post-compose, pre-edit. */
+    composedSpec: string;
+    /** Per-turn edited spec files: spec-v1.md, spec-v2.md, ... */
+    specVersion(n: number): string;
+    /** Per-turn spec reviewer JSON output. */
+    specReviewTurn(n: number): string;
+    /** Final spec at a stable path, post-edit-loop. The present stage reads from here. */
+    specFinal: string;
+    /** Final pipeline summary JSON, surfaced by present and consumed by wrappers. */
+    pipelineSummary: string;
+}
+export declare function cachePaths(projectRoot: string): CachePaths;
+export declare function ensureCacheDir(projectRoot: string): CachePaths;
+/**
+ * Remove all cached artifacts. Used by `--fresh`.
+ * Requirement: CTS-RESUME-4
+ */
+export declare function clearCache(projectRoot: string): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/codebase-to-spec/cache.js

@@ -0,0 +1,54 @@
+/**
+ * Cache directory layout and path helpers for codebase-to-spec.
+ *
+ * All pipeline artifacts live under `.dotrequirements-cache/` in the project
+ * root. Wrappers and downstream stages read cached inputs by these paths;
+ * resumability (CTS-RESUME-1..4) is driven by the presence/absence of these
+ * files.
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: pack stage paths (overview.txt, source.txt)
+ * - CTS-RESUME-1..4: per-stage cache detection
+ */
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+export const CACHE_DIR_NAME = ".dotrequirements-cache";
+export function cachePaths(projectRoot) {
+    const root = join(projectRoot, CACHE_DIR_NAME);
+    return {
+        root,
+        overview: join(root, "overview.txt"),
+        source: join(root, "source.txt"),
+        outlineFinal: join(root, "outline-final.json"),
+        outlineTurn: (n) => join(root, `outline-${n}.json`),
+        outlineReviewTurn: (n) => join(root, `outline-review-${n}.json`),
+        partialsDir: join(root, "partials"),
+        partial: (name) => join(root, "partials", `${name}.partial.md`),
+        composedSpec: join(root, "spec-composed.md"),
+        specVersion: (n) => join(root, `spec-v${n}.md`),
+        specReviewTurn: (n) => join(root, `spec-review-${n}.json`),
+        specFinal: join(root, "spec-final.md"),
+        pipelineSummary: join(root, "pipeline-summary.json"),
+    };
+}
+export function ensureCacheDir(projectRoot) {
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.root)) {
+        mkdirSync(paths.root, { recursive: true });
+    }
+    if (!existsSync(paths.partialsDir)) {
+        mkdirSync(paths.partialsDir, { recursive: true });
+    }
+    return paths;
+}
+/**
+ * Remove all cached artifacts. Used by `--fresh`.
+ * Requirement: CTS-RESUME-4
+ */
+export function clearCache(projectRoot) {
+    const root = join(projectRoot, CACHE_DIR_NAME);
+    if (existsSync(root)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/codebase-to-spec/claude.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `claude -p` subprocess wrapper for codebase-to-spec.
+ *
+ * Provides a small typed surface for invoking the user's Claude Code agent in
+ * non-interactive (print) mode, with optional stateful session continuation
+ * and JSON-schema output validation.
+ *
+ * Why this lives here:
+ * - The pipeline spawns the user's claude binary, inheriting the user's
+ *   environment so whatever auth mode they've configured (API key, OAuth via
+ *   Claude Code subscription, etc.) is what gets used.
+ * - Each invocation is a separate context window. Stateful loops use
+ *   --session-id and --resume to maintain conversation state across turns.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
+ * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ */
+export interface ClaudeRunOptions {
+    /** System prompt content (passed via --system-prompt). */
+    systemPrompt: string;
+    /** User message (passed as final positional arg). */
+    userMessage: string;
+    /** Model alias (e.g., 'sonnet') or full name. Defaults to 'sonnet'. */
+    model?: string;
+    /** Tools the agent may use. Defaults to ['Read']. */
+    tools?: string[];
+    /** Directories to grant filesystem access to (via --add-dir). */
+    addDirs?: string[];
+    /** Optional JSON schema for structured output validation. */
+    jsonSchema?: object;
+    /**
+     * Stateful session control:
+     * - `{ kind: 'fresh', sessionId: '<uuid>' }` — create a new session with this id
+     * - `{ kind: 'resume', sessionId: '<uuid>' }` — continue an existing session
+     * - omitted / undefined — stateless, no persistence
+     */
+    session?: {
+        kind: "fresh";
+        sessionId: string;
+    } | {
+        kind: "resume";
+        sessionId: string;
+    };
+    /** Override the working directory. Defaults to system temp dir. */
+    cwd?: string;
+    /** Override permission mode. Defaults to 'bypassPermissions'. */
+    permissionMode?: "bypassPermissions" | "auto" | "default" | "acceptEdits";
+    /** Path to the claude binary. Defaults to 'claude' (found in PATH). */
+    claudeBinary?: string;
+}
+export interface ClaudeRunResult {
+    /** Process exit code. */
+    exitCode: number;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+}
+/**
+ * Default runner — spawns the `claude` binary as a subprocess.
+ */
+export declare function runClaude(options: ClaudeRunOptions): Promise<ClaudeRunResult>;
+/**
+ * Pluggable runner interface so tests can swap in a mock without spawning
+ * a real subprocess. Production code uses `runClaude`; tests pass a fake.
+ */
+export type ClaudeRunner = (options: ClaudeRunOptions) => Promise<ClaudeRunResult>;
+//# sourceMappingURL=claude.d.ts.map

package/dist/codebase-to-spec/claude.js

@@ -0,0 +1,126 @@
+/**
+ * `claude -p` subprocess wrapper for codebase-to-spec.
+ *
+ * Provides a small typed surface for invoking the user's Claude Code agent in
+ * non-interactive (print) mode, with optional stateful session continuation
+ * and JSON-schema output validation.
+ *
+ * Why this lives here:
+ * - The pipeline spawns the user's claude binary, inheriting the user's
+ *   environment so whatever auth mode they've configured (API key, OAuth via
+ *   Claude Code subscription, etc.) is what gets used.
+ * - Each invocation is a separate context window. Stateful loops use
+ *   --session-id and --resume to maintain conversation state across turns.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
+ * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ */
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+/**
+ * Default runner — spawns the `claude` binary as a subprocess.
+ */
+export async function runClaude(options) {
+    const { systemPrompt, userMessage, model = "sonnet", tools = ["Read"], addDirs = [], jsonSchema, session, cwd = tmpdir(), permissionMode = "bypassPermissions", claudeBinary = "claude", } = options;
+    const args = ["-p"];
+    args.push("--model", model);
+    args.push("--permission-mode", permissionMode);
+    // `--output-format text` does NOT enforce `--json-schema` (we verified this
+    // empirically). When we want schema-enforced JSON we need
+    // `--output-format json`, which wraps the response in a metadata envelope
+    // whose `structured_output` field contains the validated JSON.
+    args.push("--output-format", jsonSchema ? "json" : "text");
+    if (tools.length > 0) {
+        args.push("--tools", tools.join(","));
+    }
+    for (const dir of addDirs) {
+        args.push("--add-dir", dir);
+    }
+    if (jsonSchema) {
+        args.push("--json-schema", JSON.stringify(jsonSchema));
+    }
+    if (session) {
+        if (session.kind === "fresh") {
+            args.push("--session-id", session.sessionId);
+        }
+        else {
+            args.push("--resume", session.sessionId);
+            // On resume we still need to re-pass permission mode and add-dirs;
+            // resume doesn't preserve them by default.
+        }
+    }
+    else {
+        args.push("--no-session-persistence");
+    }
+    // System prompt — only on initial calls. On resume, the system prompt is
+    // already baked into the session and re-passing it can confuse the agent.
+    if (!session || session.kind === "fresh") {
+        args.push("--append-system-prompt", systemPrompt);
+    }
+    // The user message is always the final positional arg.
+    args.push(userMessage);
+    return new Promise((resolve, reject) => {
+        const child = spawn(claudeBinary, args, {
+            cwd,
+            // Inherit the parent environment so `claude -p` uses whatever auth
+            // mode the user has configured (API key if set, OAuth otherwise).
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        // Close stdin immediately — we pass user message via argv, not stdin.
+        child.stdin.end();
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const exitCode = code ?? 0;
+            // If we asked for schema-validated JSON, claude -p returns a metadata
+            // envelope. Extract the agent's actual output from `structured_output`
+            // (preferred) or `result` (fallback). Callers expect `stdout` to
+            // contain only the agent's output, not the envelope.
+            if (jsonSchema && exitCode === 0 && stdout.trim().length > 0) {
+                try {
+                    const envelope = JSON.parse(stdout);
+                    if (envelope && typeof envelope === "object") {
+                        if (envelope.is_error) {
+                            // Surface the API error message on stderr so callers can see it.
+                            const apiErrSnippet = typeof envelope.result === "string"
+                                ? envelope.result
+                                : JSON.stringify(envelope);
+                            resolve({
+                                exitCode: exitCode || 1,
+                                stdout: "",
+                                stderr: `${stderr}\nclaude -p reported is_error: ${apiErrSnippet}`,
+                            });
+                            return;
+                        }
+                        if ("structured_output" in envelope) {
+                            resolve({
+                                exitCode,
+                                stdout: JSON.stringify(envelope.structured_output),
+                                stderr,
+                            });
+                            return;
+                        }
+                        if (typeof envelope.result === "string") {
+                            resolve({ exitCode, stdout: envelope.result, stderr });
+                            return;
+                        }
+                    }
+                }
+                catch {
+                    // Fall through to raw stdout. Caller's parser will surface the
+                    // schema-validation failure.
+                }
+            }
+            resolve({ exitCode, stdout, stderr });
+        });
+    });
+}
+//# sourceMappingURL=claude.js.map

package/dist/codebase-to-spec/compose.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Compose stage: assemble per-area partials into a single composed spec.
+ *
+ * The composed document has YAML frontmatter (title, defaultPrefix), an H1
+ * title, a summary paragraph from the outline, and one H2 section per area.
+ * Each area section contains the partial's content.
+ *
+ * After assembly, schema validation runs over the document. Mechanical errors
+ * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
+ * errors surface to the caller.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
+ * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ */
+import type { Outline } from "./schemas.js";
+export interface ComposeOptions {
+    outline: Outline;
+    /** Resolves an area's sanitized name to its partial file path. */
+    partialPathFor: (sanitizedAreaName: string) => string;
+    /** Where to write the composed spec. */
+    composedPath: string;
+}
+export interface ComposeResult {
+    /** Path the composed spec was written to. */
+    composedPath: string;
+    /** Number of partials that contributed content. */
+    partialsIncluded: number;
+    /** Number of areas whose partial was missing or marked as missing. */
+    partialsMissing: number;
+    /** Validation outcome — undefined when validation passes. */
+    validationError?: string;
+}
+/**
+ * Assemble the composed Markdown document.
+ *
+ * Public so tests can call without disk side effects (composedPath isn't used
+ * here; the caller writes the returned string).
+ */
+export declare function assembleComposedDocument(outline: Outline, partialPathFor: (sanitized: string) => string): {
+    content: string;
+    partialsIncluded: number;
+    partialsMissing: number;
+};
+/**
+ * Compose the spec and write it to disk. Validates the result.
+ */
+export declare function runCompose(options: ComposeOptions): ComposeResult;
+//# sourceMappingURL=compose.d.ts.map

package/dist/codebase-to-spec/compose.js

@@ -0,0 +1,124 @@
+/**
+ * Compose stage: assemble per-area partials into a single composed spec.
+ *
+ * The composed document has YAML frontmatter (title, defaultPrefix), an H1
+ * title, a summary paragraph from the outline, and one H2 section per area.
+ * Each area section contains the partial's content.
+ *
+ * After assembly, schema validation runs over the document. Mechanical errors
+ * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
+ * errors surface to the caller.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
+ * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseRequirementsFile } from "../schema/parser.js";
+import { sanitizeAreaName } from "./fan-out.js";
+/**
+ * Read a partial file. If missing or marked as a missing-partial placeholder,
+ * return null (caller will emit a stub section).
+ */
+function readPartial(path) {
+    if (!existsSync(path))
+        return null;
+    const content = readFileSync(path, "utf-8");
+    const trimmed = content.trim();
+    if (!trimmed)
+        return null;
+    // Common placeholders for missing partials produced by fan-out on failure
+    // or by zero-files-assigned areas.
+    if (trimmed.startsWith("_(missing partial") ||
+        trimmed.startsWith("_(no files assigned")) {
+        return null;
+    }
+    return content;
+}
+/**
+ * Assemble the composed Markdown document.
+ *
+ * Public so tests can call without disk side effects (composedPath isn't used
+ * here; the caller writes the returned string).
+ */
+export function assembleComposedDocument(outline, partialPathFor) {
+    const parts = [];
+    parts.push("---");
+    parts.push("document:");
+    parts.push(`  title: "${escapeYamlString(outline.title)}"`);
+    parts.push(`  defaultPrefix: ${outline.defaultPrefix}`);
+    parts.push("---");
+    parts.push("");
+    parts.push(`# ${outline.title}`);
+    parts.push("");
+    parts.push(outline.summary.trim());
+    parts.push("");
+    let partialsIncluded = 0;
+    let partialsMissing = 0;
+    for (const area of outline.areas) {
+        const sanitized = sanitizeAreaName(area.name);
+        const partialPath = partialPathFor(sanitized);
+        parts.push("---");
+        parts.push("");
+        parts.push(`## ${area.name}`);
+        parts.push("");
+        const partial = readPartial(partialPath);
+        if (partial) {
+            parts.push(partial.trim());
+            partialsIncluded++;
+        }
+        else {
+            parts.push(`_(partial for ${area.name} is missing or empty — surface this to the user when presenting the spec)_`);
+            partialsMissing++;
+        }
+        parts.push("");
+    }
+    return {
+        content: parts.join("\n"),
+        partialsIncluded,
+        partialsMissing,
+    };
+}
+/** Escape a string for safe YAML scalar use. */
+function escapeYamlString(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Attempt to fix mechanical errors in a composed document.
+ *
+ * For v0, the simplest mechanical fix is duplicate IDs within an area —
+ * we detect and renumber them sequentially. Position-path and Gherkin syntax
+ * errors surface to the validator's caller; we don't auto-fix those because
+ * the editor loop is better suited to it.
+ */
+function fixMechanicalErrors(content) {
+    // Detect duplicate IDs (lines like "PREFIX-AREA-001: ...") within each area.
+    // For v0 we punt — the schema validator will catch them and the caller will
+    // surface to the user. Returning content unchanged keeps the contract: the
+    // function is a no-op for inputs without fixable errors.
+    return content;
+}
+/**
+ * Compose the spec and write it to disk. Validates the result.
+ */
+export function runCompose(options) {
+    const { outline, partialPathFor, composedPath } = options;
+    const { content, partialsIncluded, partialsMissing } = assembleComposedDocument(outline, partialPathFor);
+    const finalContent = fixMechanicalErrors(content);
+    writeFileSync(composedPath, finalContent, "utf-8");
+    // Validate
+    let validationError;
+    try {
+        parseRequirementsFile(finalContent);
+    }
+    catch (err) {
+        validationError = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        composedPath,
+        partialsIncluded,
+        partialsMissing,
+        validationError,
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/codebase-to-spec/edit-loop.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Spec review + editor loop.
+ *
+ * Same structure as the outline review loop, scaled up for document-level
+ * revision: stateful spec reviewer + stateless editor. The reviewer
+ * persists across turns so it can compare prior spec versions to the latest.
+ *
+ * Requirements covered:
+ * - CTS-EDIT-1: stateful spec reviewer
+ * - CTS-EDIT-2: approved → proceed
+ * - CTS-EDIT-3: approved-with-revisions → one mechanical edit pass
+ * - CTS-EDIT-4: requires-another-review → revise & resubmit
+ * - CTS-EDIT-5: editor operates on cohesive document
+ * - CTS-EDIT-6: max-turns + convergence nudge
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { ProgressEmitter } from "./progress.js";
+import { type SpecReview } from "./schemas.js";
+export declare const DEFAULT_EDIT_LOOP_MAX_TURNS = 6;
+export interface EditLoopOptions {
+    /** Path to the composed spec (input). */
+    composedSpecPath: string;
+    /**
+     * Resolver: given a turn number (1-indexed), return the path the editor's
+     * output for that turn should land at. Loop persists each version.
+     */
+    specVersionFor: (turn: number) => string;
+    /** Path to the codebase pack. */
+    fullPackPath: string;
+    /** Directories for filesystem access. */
+    addDirs: string[];
+    maxTurns?: number;
+    runner?: ClaudeRunner;
+    model?: string;
+    progress?: ProgressEmitter;
+    /** Override session id (for tests / reproducibility). */
+    sessionId?: string;
+}
+export interface EditLoopResult {
+    /** Path to the final spec (post-edit if applicable). */
+    finalSpecPath: string;
+    /** Per-turn spec paths (turn 1 is the composed-spec copy, then each revision). */
+    specPathsByTurn: string[];
+    /** Per-turn reviewer results. */
+    reviewsByTurn: SpecReview[];
+    /** The final reviewer verdict. */
+    finalVerdict: SpecReview["verdict"];
+    /** Number of review turns used. */
+    turnsUsed: number;
+    /** True if the loop hit max-turns without converging. */
+    hitMaxTurns: boolean;
+}
+export declare function runEditLoop(options: EditLoopOptions): Promise<EditLoopResult>;
+//# sourceMappingURL=edit-loop.d.ts.map