@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/codebase-to-spec/skill-install.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Skill installation logic for the codebase-to-spec skill.
+ *
+ * The skill is a thin conversational wrapper around `dotrequirements cts run`.
+ * It ships as a SKILL.md template bundled in the CLI package, and this module
+ * copies it into the host's skill directory (default: `.claude/skills/` for
+ * Claude Code).
+ *
+ * Host portability (CTS-SKILL-5): the install logic supports any host that
+ * follows the Agent Skills format. The default target is Claude Code's
+ * convention; `--target-dir` lets users place the skill anywhere.
+ *
+ * Requirements covered:
+ * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
+ * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
+ *   Agent Skills format support
+ */
+export type SkillInstallScope = "project" | "global" | "custom";
+export interface SkillInstallOptions {
+    /**
+     * Where to install:
+     * - `project` (default): `<projectRoot>/.claude/skills/codebase-to-spec/`
+     * - `global`: `~/.claude/skills/codebase-to-spec/`
+     * - `custom`: requires `targetDir`
+     */
+    scope?: SkillInstallScope;
+    /** Required when `scope === 'custom'`. The skill directory will be created here. */
+    targetDir?: string;
+    /** Project root (used when scope === 'project'). Defaults to cwd. */
+    projectRoot?: string;
+    /** Overwrite existing SKILL.md if present. Default false. */
+    overwrite?: boolean;
+}
+export interface SkillInstallResult {
+    /** Final on-disk path to SKILL.md. */
+    installedPath: string;
+    /** True if a new file was written; false if it was already in place (no overwrite). */
+    installed: boolean;
+    /** True if an existing file was replaced. */
+    overwrote: boolean;
+}
+/**
+ * Resolve the directory in which the skill should live, given the user's
+ * scope choice. The directory itself is the `codebase-to-spec/` skill dir;
+ * `SKILL.md` is written inside it.
+ */
+export declare function resolveSkillDir(options: SkillInstallOptions): string;
+/**
+ * Load the bundled SKILL.md template from the package.
+ */
+export declare function loadSkillTemplate(): string;
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
+ * resolved location.
+ */
+export declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
+//# sourceMappingURL=skill-install.d.ts.map

package/dist/codebase-to-spec/skill-install.js

@@ -0,0 +1,79 @@
+/**
+ * Skill installation logic for the codebase-to-spec skill.
+ *
+ * The skill is a thin conversational wrapper around `dotrequirements cts run`.
+ * It ships as a SKILL.md template bundled in the CLI package, and this module
+ * copies it into the host's skill directory (default: `.claude/skills/` for
+ * Claude Code).
+ *
+ * Host portability (CTS-SKILL-5): the install logic supports any host that
+ * follows the Agent Skills format. The default target is Claude Code's
+ * convention; `--target-dir` lets users place the skill anywhere.
+ *
+ * Requirements covered:
+ * - CTS-SKILL-1: skill artifact exists and points users at `dotrequirements cts run`
+ * - CTS-SKILL-5: install logic is host-agnostic and works on any host with
+ *   Agent Skills format support
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { loadTemplate } from "../utils/templates.js";
+/**
+ * Resolve the directory in which the skill should live, given the user's
+ * scope choice. The directory itself is the `codebase-to-spec/` skill dir;
+ * `SKILL.md` is written inside it.
+ */
+export function resolveSkillDir(options) {
+    const scope = options.scope ?? "project";
+    switch (scope) {
+        case "project": {
+            const root = options.projectRoot ?? process.cwd();
+            return join(root, ".claude", "skills", "codebase-to-spec");
+        }
+        case "global":
+            return join(homedir(), ".claude", "skills", "codebase-to-spec");
+        case "custom":
+            if (!options.targetDir) {
+                throw new Error('targetDir is required when scope === "custom"');
+            }
+            // Treat targetDir as the parent skills/ directory; create the
+            // skill subdir under it.
+            return join(resolve(options.targetDir), "codebase-to-spec");
+    }
+}
+/**
+ * Load the bundled SKILL.md template from the package.
+ */
+export function loadSkillTemplate() {
+    return loadTemplate("skills/codebase-to-spec/SKILL.md");
+}
+/**
+ * Install (or refuse to overwrite) the codebase-to-spec SKILL.md at the
+ * resolved location.
+ */
+export function installSkill(options = {}) {
+    const skillDir = resolveSkillDir(options);
+    const skillPath = join(skillDir, "SKILL.md");
+    const template = loadSkillTemplate();
+    const exists = existsSync(skillPath);
+    if (exists && !options.overwrite) {
+        // Idempotent no-op: if the on-disk content already matches the template,
+        // there's nothing to do and we shouldn't surface that as a conflict.
+        const onDisk = readFileSync(skillPath, "utf-8");
+        if (onDisk === template) {
+            return { installedPath: skillPath, installed: false, overwrote: false };
+        }
+        // Stale or hand-edited copy: refuse without --overwrite so we don't
+        // silently clobber user changes.
+        throw new Error(`SKILL.md already exists at ${skillPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
+    }
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, template, "utf-8");
+    return {
+        installedPath: skillPath,
+        installed: true,
+        overwrote: exists,
+    };
+}
+//# sourceMappingURL=skill-install.js.map

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

@@ -0,0 +1,49 @@
+/**
+ * Slice extraction: given a Repomix pack and a list of file paths (or
+ * directory-prefix paths), produce a smaller pack containing only the matching
+ * files.
+ *
+ * Pack format (from Repomix --style plain):
+ *
+ *   ================
+ *   File: path/to/file
+ *   ================
+ *   <file contents>
+ *
+ *   ================
+ *   File: next/file
+ *   ================
+ *   ...
+ *
+ * We preserve the pack header (everything before the first File: section) and
+ * the matching sections.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: CLI fans out one specifier worker per area; each worker
+ *   receives a slice extracted from the uncompressed pack
+ */
+/**
+ * Return true when `path` matches one of the entries in `wanted`.
+ *
+ * Each entry can be:
+ * - An exact file path (e.g., `src/foo.ts`) — matches that exact path.
+ * - A directory prefix ending in `/` (e.g., `src/services/browser/`) — matches
+ *   any file under that directory tree.
+ */
+export declare function pathMatchesWanted(path: string, wanted: Iterable<string>): boolean;
+export interface SliceExtractionResult {
+    /** Number of file sections matched (and written to the output). */
+    matched: number;
+    /** Total number of file sections in the input pack. */
+    total: number;
+}
+/**
+ * Extract sections matching `wanted` from the pack at `inputPath` and write
+ * them to `outputPath`. Preserves the pack header (Repomix metadata).
+ */
+export declare function extractSlice(inputPath: string, outputPath: string, wanted: Iterable<string>): SliceExtractionResult;
+/**
+ * Pure variant operating on already-loaded text. Useful for tests.
+ */
+export declare function extractSliceFromText(text: string, outputPath: string, wanted: Iterable<string>): SliceExtractionResult;
+//# sourceMappingURL=slice.d.ts.map

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

@@ -0,0 +1,111 @@
+/**
+ * Slice extraction: given a Repomix pack and a list of file paths (or
+ * directory-prefix paths), produce a smaller pack containing only the matching
+ * files.
+ *
+ * Pack format (from Repomix --style plain):
+ *
+ *   ================
+ *   File: path/to/file
+ *   ================
+ *   <file contents>
+ *
+ *   ================
+ *   File: next/file
+ *   ================
+ *   ...
+ *
+ * We preserve the pack header (everything before the first File: section) and
+ * the matching sections.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: CLI fans out one specifier worker per area; each worker
+ *   receives a slice extracted from the uncompressed pack
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+const SEPARATOR = "================";
+const FILE_PREFIX = "File: ";
+/**
+ * Return true when `path` matches one of the entries in `wanted`.
+ *
+ * Each entry can be:
+ * - An exact file path (e.g., `src/foo.ts`) — matches that exact path.
+ * - A directory prefix ending in `/` (e.g., `src/services/browser/`) — matches
+ *   any file under that directory tree.
+ */
+export function pathMatchesWanted(path, wanted) {
+    for (const w of wanted) {
+        if (w === path)
+            return true;
+        if (w.endsWith("/") && path.startsWith(w))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract sections matching `wanted` from the pack at `inputPath` and write
+ * them to `outputPath`. Preserves the pack header (Repomix metadata).
+ */
+export function extractSlice(inputPath, outputPath, wanted) {
+    const wantedSet = new Set(wanted);
+    const text = readFileSync(inputPath, "utf-8");
+    return extractSliceFromText(text, outputPath, wantedSet);
+}
+/**
+ * Pure variant operating on already-loaded text. Useful for tests.
+ */
+export function extractSliceFromText(text, outputPath, wanted) {
+    const wantedSet = wanted instanceof Set ? wanted : new Set(wanted);
+    const lines = text.split("\n");
+    const out = [];
+    // Find the start of the first File: section.
+    let firstFileIdx = -1;
+    for (let i = 0; i + 1 < lines.length; i++) {
+        if (lines[i].trim() === SEPARATOR && lines[i + 1].startsWith(FILE_PREFIX)) {
+            firstFileIdx = i;
+            break;
+        }
+    }
+    if (firstFileIdx === -1) {
+        throw new Error("Input pack has no File: sections");
+    }
+    // Preserve the pack header (lines 0..firstFileIdx-1).
+    for (let i = 0; i < firstFileIdx; i++) {
+        out.push(lines[i]);
+    }
+    let matched = 0;
+    let total = 0;
+    let i = firstFileIdx;
+    while (i < lines.length) {
+        if (lines[i].trim() === SEPARATOR &&
+            i + 1 < lines.length &&
+            lines[i + 1].startsWith(FILE_PREFIX)) {
+            const path = lines[i + 1].slice(FILE_PREFIX.length).trim();
+            total++;
+            // Find the end of this section (next ====/File: pair or EOF).
+            let j = i + 3; // past the closing separator
+            while (j < lines.length) {
+                if (lines[j].trim() === SEPARATOR &&
+                    j + 1 < lines.length &&
+                    lines[j + 1].startsWith(FILE_PREFIX)) {
+                    break;
+                }
+                j++;
+            }
+            const contentEnd = j; // exclusive
+            if (pathMatchesWanted(path, wantedSet)) {
+                matched++;
+                for (let k = i; k < contentEnd; k++) {
+                    out.push(lines[k]);
+                }
+            }
+            i = j;
+        }
+        else {
+            i++;
+        }
+    }
+    writeFileSync(outputPath, out.join("\n"), "utf-8");
+    return { matched, total };
+}
+//# sourceMappingURL=slice.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * Specifier worker: run a single specifier for one area.
+ *
+ * The specifier is given its slice + the outline + a target partial path, and
+ * it orchestrates its own work via tools (Read, Write, Edit, Grep, Glob, Bash).
+ * Self-style-check happens via `Bash dotrequirements cts style-check <path>`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: per-area worker invocation
+ * - CTS-SPEC-2: write partial to known path via Write tool
+ * - CTS-SPEC-3: self-style-check via Bash
+ * - CTS-SPEC-4: access to the full pack for cross-area context
+ * - CTS-SPEC-5: failure detection and retry orchestrated by fan-out (this file
+ *   produces a single attempt; fan-out wraps it with retry policy)
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { Area, Outline } from "./schemas.js";
+export interface SpecifierContext {
+    outline: Outline;
+    area: Area;
+    /** Path to the area's slice (extracted from the uncompressed pack). */
+    slicePath: string;
+    /** Path to the full uncompressed pack (for cross-area discovery). */
+    fullPackPath: string;
+    /** Where the specifier should write its partial. */
+    partialPath: string;
+    /**
+     * The command the specifier should run to invoke schema validation on its
+     * own partial — typically `dotrequirements cts validate`. Run BEFORE
+     * style-check.
+     */
+    validateCommand: string;
+    /**
+     * The command the specifier should run to invoke style-check on its own
+     * partial — typically `dotrequirements cts style-check`. Run AFTER
+     * validate.
+     */
+    styleCheckCommand: string;
+    /** Directories the agent should have read+write access to. */
+    addDirs: string[];
+    runner?: ClaudeRunner;
+    model?: string;
+}
+export interface SpecifierResult {
+    /** True if the agent wrote a non-empty partial file at the expected path. */
+    wrotePartial: boolean;
+    /** Size of the partial in bytes, or 0 if missing. */
+    partialBytes: number;
+    /** Process exit code. */
+    exitCode: number;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+}
+/**
+ * Run a single specifier. Returns details about whether it succeeded.
+ */
+export declare function runSpecifier(ctx: SpecifierContext): Promise<SpecifierResult>;
+//# sourceMappingURL=specifier.d.ts.map

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

@@ -0,0 +1,79 @@
+/**
+ * Specifier worker: run a single specifier for one area.
+ *
+ * The specifier is given its slice + the outline + a target partial path, and
+ * it orchestrates its own work via tools (Read, Write, Edit, Grep, Glob, Bash).
+ * Self-style-check happens via `Bash dotrequirements cts style-check <path>`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: per-area worker invocation
+ * - CTS-SPEC-2: write partial to known path via Write tool
+ * - CTS-SPEC-3: self-style-check via Bash
+ * - CTS-SPEC-4: access to the full pack for cross-area context
+ * - CTS-SPEC-5: failure detection and retry orchestrated by fan-out (this file
+ *   produces a single attempt; fan-out wraps it with retry policy)
+ */
+import { existsSync, statSync } from "node:fs";
+import { runClaude } from "./claude.js";
+import { SPECIFIER_PROMPT } from "./prompts/specifier.js";
+function buildUserMessage(ctx) {
+    return [
+        `You are specifying ONE area of the system.`,
+        ``,
+        `Area name: ${ctx.area.name}`,
+        `Area description: ${ctx.area.description}`,
+        `Document defaultPrefix: ${ctx.outline.defaultPrefix}`,
+        `Area prefix: ${ctx.area.prefix}`,
+        `Use full requirement IDs of the form: ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-1, ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-2, etc. (sequential, 1-indexed, no zero-padding).`,
+        ``,
+        `## Paths`,
+        `- Slice (your area's files): ${ctx.slicePath}`,
+        `- Full uncompressed pack (for discovering behaviors in tests/recipes/docs): ${ctx.fullPackPath}`,
+        `- Where to write your partial: ${ctx.partialPath}`,
+        `- Validate command (run FIRST after writing your draft — deterministic syntax check):`,
+        `    Bash: ${ctx.validateCommand} ${ctx.partialPath}`,
+        `- Style-check command (run SECOND, only after validate passes — AI clarity feedback):`,
+        `    Bash: ${ctx.styleCheckCommand} ${ctx.partialPath}`,
+        ``,
+        `## Full system outline (so you know what is in scope vs. not)`,
+        `\`\`\`json`,
+        JSON.stringify(ctx.outline, null, 2),
+        `\`\`\``,
+        ``,
+        `Follow the three-phase workflow in your system prompt: draft (Phase A) → validate (Phase B) → style-check (Phase C) → confirm.`,
+    ].join("\n");
+}
+/**
+ * Run a single specifier. Returns details about whether it succeeded.
+ */
+export async function runSpecifier(ctx) {
+    const runner = ctx.runner ?? runClaude;
+    const result = await runner({
+        systemPrompt: SPECIFIER_PROMPT,
+        userMessage: buildUserMessage(ctx),
+        model: ctx.model,
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        addDirs: ctx.addDirs,
+    });
+    // Inspect the partial file to determine whether the specifier wrote
+    // something usable.
+    let wrotePartial = false;
+    let partialBytes = 0;
+    if (existsSync(ctx.partialPath)) {
+        try {
+            partialBytes = statSync(ctx.partialPath).size;
+            wrotePartial = partialBytes > 0;
+        }
+        catch {
+            // ignore; treat as not written
+        }
+    }
+    return {
+        wrotePartial,
+        partialBytes,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+//# sourceMappingURL=specifier.js.map

package/dist/codebase-to-spec/style-check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Local style-check function — produces severity-categorized feedback on a
+ * partial-spec file using a fresh, stateless claude -p call.
+ *
+ * Mirrors the existing cloud `mcp__dotrequirements__style_check` pattern but
+ * runs entirely offline (no cloud credentials, no account required), since
+ * the codebase-to-spec target audience does not yet have a dotrequirements
+ * account.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+import { type ClaudeRunner } from "./claude.js";
+export interface StyleCheckOptions {
+    partialPath: string;
+    runner?: ClaudeRunner;
+    model?: string;
+}
+export interface StyleCheckResult {
+    /** The categorized feedback (Markdown). */
+    feedback: string;
+    /** Process exit code from the claude -p subprocess. */
+    exitCode: number;
+}
+/**
+ * Run a style check on a partial-spec file and return the feedback as Markdown.
+ */
+export declare function runStyleCheck(options: StyleCheckOptions): Promise<StyleCheckResult>;
+//# sourceMappingURL=style-check.d.ts.map

package/dist/codebase-to-spec/style-check.js

@@ -0,0 +1,33 @@
+/**
+ * Local style-check function — produces severity-categorized feedback on a
+ * partial-spec file using a fresh, stateless claude -p call.
+ *
+ * Mirrors the existing cloud `mcp__dotrequirements__style_check` pattern but
+ * runs entirely offline (no cloud credentials, no account required), since
+ * the codebase-to-spec target audience does not yet have a dotrequirements
+ * account.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+import { dirname } from "node:path";
+import { runClaude } from "./claude.js";
+import { STYLE_CHECK_PROMPT } from "./prompts/style-check.js";
+/**
+ * Run a style check on a partial-spec file and return the feedback as Markdown.
+ */
+export async function runStyleCheck(options) {
+    const runner = options.runner ?? runClaude;
+    const result = await runner({
+        systemPrompt: STYLE_CHECK_PROMPT,
+        userMessage: `Run a style check on the partial spec at ${options.partialPath}. Read the file via the Read tool and produce categorized Markdown feedback per your system prompt.`,
+        model: options.model,
+        tools: ["Read"],
+        addDirs: [dirname(options.partialPath)],
+    });
+    return {
+        feedback: result.stdout,
+        exitCode: result.exitCode,
+    };
+}
+//# sourceMappingURL=style-check.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * Pipeline summary generation.
+ *
+ * Reads cached artifacts to assemble a structured summary of what the
+ * pipeline produced. Surfaced both as JSON (parseable by wrappers like the
+ * skill) and as a short human-readable block.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-4: Final pipeline summary is surfaced
+ * - CTS-OBSERVE-2 (partial): structured failure information available
+ */
+import type { CachePaths } from "./cache.js";
+import { type Outline } from "./schemas.js";
+export interface PipelineSummary {
+    totalAreas: number;
+    totalRequirements: number;
+    outline: {
+        turnsUsed: number;
+        finalVerdict: string | null;
+        residualNotes: string[];
+    };
+    specifiers: {
+        completed: number;
+        missing: number;
+        /** Area names that have no usable partial. */
+        missingAreas: string[];
+    };
+    specReview: {
+        turnsUsed: number;
+        finalVerdict: string | null;
+        residualNotes: string[];
+    };
+    outputs: {
+        /** Paths under .requirements/ that were written. */
+        paths: string[];
+    };
+}
+export interface BuildSummaryInput {
+    outline: Outline;
+    paths: CachePaths;
+    /** Paths the present stage wrote (under .requirements/). */
+    outputPaths: string[];
+}
+export declare function buildPipelineSummary(input: BuildSummaryInput): PipelineSummary;
+/**
+ * Render a short human-readable block for the summary. Designed to fit on a
+ * small number of lines (CTS-PRESENT-4.2). Wrappers that want richer
+ * presentation can read the JSON form instead.
+ */
+export declare function renderSummaryText(summary: PipelineSummary): string;
+//# sourceMappingURL=summary.d.ts.map