@popoverai/dotrequirements 0.25.0 → 0.26.1

package/dist/commands/codebase-to-spec/plan-loop.js

@@ -1,105 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec plan-loop` subcommand.
- *
- * Reads the compressed pack from the cache and runs the outline review loop
- * (planner → reviewer → revise → ... → approved). Writes per-turn artifacts
- * and the final outline.
- *
- * Requirements covered:
- * - CTS-CLI-2: `dotrequirements cts plan-loop` runs only the outline review loop and exits
- * - CTS-PLAN-1..6: end-to-end loop behavior
- * - CTS-RESUME-1.1: skip loop if outline-final.json exists
- * - CTS-OBSERVE-1, CTS-OBSERVE-2: progress + failure observability
- */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { cachePaths } from "../../codebase-to-spec/cache.js";
-import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
-import { DEFAULT_OUTLINE_LOOP_MAX_TURNS, runOutlineReviewLoop, } from "../../codebase-to-spec/outline-review-loop.js";
-import { StdoutProgress } from "../../codebase-to-spec/progress.js";
-import { findProjectRoot } from "../../utils/project-settings.js";
-export async function planLoopCommand(rawOptions = {}) {
-    const progress = rawOptions.progress ?? new StdoutProgress();
-    const projectRoot = rawOptions.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
-    const paths = cachePaths(projectRoot);
-    const maxTurns = rawOptions.maxTurns ?? DEFAULT_OUTLINE_LOOP_MAX_TURNS;
-    // Resume — if outline-final.json already exists, skip the loop entirely.
-    if (existsSync(paths.outlineFinal)) {
-        progress.emit({
-            stage: "plan",
-            step: "resume-skip",
-            message: `outline-final.json exists at ${paths.outlineFinal}; skipping plan loop`,
-        });
-        return;
-    }
-    // Require the compressed pack from the prior stage.
-    if (!existsSync(paths.overview)) {
-        process.stderr.write(`Missing compressed pack at ${paths.overview}. Run \`dotrequirements cts pack\` first.\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    progress.emit({
-        stage: "plan",
-        step: "start",
-        message: `Starting plan + outline review loop (max-turns=${maxTurns})`,
-    });
-    let result;
-    try {
-        result = await runOutlineReviewLoop({
-            overviewPath: paths.overview,
-            addDirs: [paths.root],
-            maxTurns,
-            model: rawOptions.model,
-            progress,
-        });
-    }
-    catch (err) {
-        process.stderr.write(`\nPlan loop failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        process.exitCode = ExitCode.StageFailed;
-        return;
-    }
-    // Persist per-turn artifacts (one outline per turn, one review per turn) so
-    // we have full evidence and resumability.
-    result.outlinesByTurn.forEach((outline, idx) => {
-        const path = paths.outlineTurn(idx + 1);
-        writeFileSync(path, `${JSON.stringify(outline, null, 2)}\n`, "utf-8");
-    });
-    result.reviewsByTurn.forEach((review, idx) => {
-        const path = paths.outlineReviewTurn(idx + 1);
-        writeFileSync(path, `${JSON.stringify(review, null, 2)}\n`, "utf-8");
-    });
-    // Write the final outline.
-    writeFileSync(paths.outlineFinal, `${JSON.stringify(result.outline, null, 2)}\n`, "utf-8");
-    if (result.hitMaxTurns) {
-        progress.emit({
-            stage: "plan",
-            step: "max-turns-hit",
-            message: `Loop hit max-turns (${maxTurns}) without converging. Using latest outline anyway.`,
-            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
-        });
-        process.exitCode = ExitCode.MaxTurnsHit;
-    }
-    else {
-        progress.emit({
-            stage: "plan",
-            step: "done",
-            message: `Plan loop converged at turn ${result.turnsUsed} with verdict: ${result.finalVerdict}`,
-            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
-        });
-    }
-    progress.emit({
-        stage: "plan",
-        step: "outline-written",
-        message: `Final outline → ${paths.outlineFinal} (${result.outline.areas.length} areas)`,
-    });
-}
-/**
- * Helper used by `cts run` and tests to consume the outline that plan-loop wrote.
- */
-export function readFinalOutline(projectRoot) {
-    const paths = cachePaths(projectRoot);
-    if (!existsSync(paths.outlineFinal)) {
-        throw new Error(`Missing ${paths.outlineFinal}. Run \`cts plan-loop\` first.`);
-    }
-    return JSON.parse(readFileSync(paths.outlineFinal, "utf-8"));
-}
-//# sourceMappingURL=plan-loop.js.map

package/dist/commands/codebase-to-spec/present.d.ts

@@ -1,26 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec present` subcommand.
- *
- * Writes the final spec to `.requirements/` and emits a pipeline summary.
- *
- * Requirements covered:
- * - CTS-CLI-2: granular `present` subcommand
- * - CTS-CLI-4: TTY-driven interactive/non-interactive selection
- * - CTS-PRESENT-1..4
- */
-export interface PresentCmdOptions {
-    /** Force --interactive or --non-interactive (overrides TTY detection). */
-    forceMode?: "interactive" | "non-interactive";
-    /** Replace existing .requirements/ files without prompting (non-interactive). */
-    overwrite?: boolean;
-    /** Skip writing files that would conflict (non-interactive). */
-    skipExisting?: boolean;
-    /**
-     * When true, write output under `.requirements/cts/` instead of
-     * `.requirements/`. See CTS-PRESENT-5.
-     */
-    ignoreRequirements?: boolean;
-    projectRoot?: string;
-}
-export declare function presentCommand(rawOptions?: PresentCmdOptions): Promise<void>;
-//# sourceMappingURL=present.d.ts.map

package/dist/commands/codebase-to-spec/present.js

@@ -1,97 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec present` subcommand.
- *
- * Writes the final spec to `.requirements/` and emits a pipeline summary.
- *
- * Requirements covered:
- * - CTS-CLI-2: granular `present` subcommand
- * - CTS-CLI-4: TTY-driven interactive/non-interactive selection
- * - CTS-PRESENT-1..4
- */
-import { existsSync, writeFileSync } from "node:fs";
-import { cachePaths } from "../../codebase-to-spec/cache.js";
-import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
-import { detectMode } from "../../codebase-to-spec/interactive.js";
-import { runPresent, } from "../../codebase-to-spec/present.js";
-import { StdoutProgress } from "../../codebase-to-spec/progress.js";
-import { buildPipelineSummary, renderSummaryText, } from "../../codebase-to-spec/summary.js";
-import { findProjectRoot } from "../../utils/project-settings.js";
-import { readFinalOutline } from "./plan-loop.js";
-function resolveOverwritePolicy(isInteractive, options) {
-    if (options.overwrite && options.skipExisting) {
-        return { error: "--overwrite and --skip-existing are mutually exclusive." };
-    }
-    if (options.overwrite)
-        return "overwrite";
-    if (options.skipExisting)
-        return "skip-existing";
-    if (isInteractive)
-        return "prompt";
-    return "fail-fast";
-}
-export async function presentCommand(rawOptions = {}) {
-    const progress = new StdoutProgress();
-    const projectRoot = rawOptions.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
-    const paths = cachePaths(projectRoot);
-    if (!existsSync(paths.outlineFinal)) {
-        process.stderr.write(`Missing outline at ${paths.outlineFinal}. Run \`dotrequirements cts plan-loop\` first.\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    if (!existsSync(paths.specFinal)) {
-        process.stderr.write(`Missing final spec at ${paths.specFinal}. Run \`dotrequirements cts edit-loop\` first.\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    const outline = readFinalOutline(projectRoot);
-    const { isInteractive } = detectMode(rawOptions.forceMode);
-    const policy = resolveOverwritePolicy(isInteractive, rawOptions);
-    if (typeof policy === "object") {
-        process.stderr.write(`${policy.error}\n`);
-        process.exitCode = ExitCode.InvalidFlags;
-        return;
-    }
-    const outputSubdir = rawOptions.ignoreRequirements ? "cts" : undefined;
-    const outputDirLabel = outputSubdir
-        ? `.requirements/${outputSubdir}/`
-        : ".requirements/";
-    progress.emit({
-        stage: "present",
-        step: "start",
-        message: `Writing final spec to ${outputDirLabel} (mode: ${isInteractive ? "interactive" : "non-interactive"}, policy: ${policy})`,
-    });
-    const result = await runPresent({
-        outline,
-        finalSpecPath: paths.specFinal,
-        projectRoot,
-        overwritePolicy: policy,
-        outputSubdir,
-    });
-    // Per-file outcome announcements.
-    for (const action of result.actions) {
-        progress.emit({
-            stage: "present",
-            step: action.action,
-            message: `${action.action}: ${action.path}`,
-        });
-    }
-    if (!result.allWritten) {
-        if (result.conflictPath) {
-            // fail-fast bailed before any write.
-            process.stderr.write(`Refusing to overwrite ${result.conflictPath}. Re-run with --overwrite or --skip-existing, or run in interactive mode.\n`);
-            process.exitCode = ExitCode.OverwriteRefused;
-            return;
-        }
-        // Other partial failures (validation, merge conflict, etc.).
-        process.exitCode = ExitCode.StageFailed;
-    }
-    // Emit the pipeline summary.
-    const summary = buildPipelineSummary({
-        outline,
-        paths,
-        outputPaths: result.outputPaths,
-    });
-    writeFileSync(paths.pipelineSummary, `${JSON.stringify(summary, null, 2)}\n`, "utf-8");
-    process.stdout.write(`\n${renderSummaryText(summary)}\n`);
-}
-//# sourceMappingURL=present.js.map

package/dist/commands/codebase-to-spec/run.d.ts

@@ -1,20 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec run` subcommand.
- *
- * Chains the pipeline stages. Currently: pack → plan-loop. Subsequent
- * increments will chain specify → compose → edit → present.
- *
- * Requirements covered (incrementally):
- * - CTS-CLI-1: User can run the pipeline end-to-end with a single command
- */
-import { type PackOptions } from "./pack.js";
-export interface RunOptions extends PackOptions {
-    maxTurns?: number;
-    model?: string;
-    concurrency?: number;
-    forceMode?: "interactive" | "non-interactive";
-    overwrite?: boolean;
-    skipExisting?: boolean;
-}
-export declare function runCommand(options?: RunOptions): Promise<void>;
-//# sourceMappingURL=run.d.ts.map

package/dist/commands/codebase-to-spec/run.js

@@ -1,86 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec run` subcommand.
- *
- * Chains the pipeline stages. Currently: pack → plan-loop. Subsequent
- * increments will chain specify → compose → edit → present.
- *
- * Requirements covered (incrementally):
- * - CTS-CLI-1: User can run the pipeline end-to-end with a single command
- */
-import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
-import { composeCommand } from "./compose.js";
-import { editLoopCommand } from "./edit-loop.js";
-import { fanOutCommand } from "./fan-out.js";
-import { packCommand } from "./pack.js";
-import { planLoopCommand } from "./plan-loop.js";
-import { presentCommand } from "./present.js";
-export async function runCommand(options = {}) {
-    // Stage 1 — Pack
-    await packCommand(options);
-    if (process.exitCode && process.exitCode !== 0) {
-        return;
-    }
-    // Stage 2 — Plan + outline review loop
-    await planLoopCommand({
-        maxTurns: options.maxTurns,
-        model: options.model,
-        progress: options.progress,
-        projectRoot: options.projectRoot,
-    });
-    if (process.exitCode &&
-        process.exitCode !== 0 &&
-        process.exitCode !== ExitCode.MaxTurnsHit) {
-        return;
-    }
-    // Reset exit code from MaxTurnsHit so downstream stages can still proceed
-    // (we use the latest outline anyway per CTS-PLAN-6).
-    if (process.exitCode === ExitCode.MaxTurnsHit) {
-        process.exitCode = 0;
-    }
-    // Stage 3 — Specifier fan-out
-    await fanOutCommand({
-        concurrency: options.concurrency,
-        model: options.model,
-        projectRoot: options.projectRoot,
-    });
-    if (process.exitCode &&
-        process.exitCode !== 0 &&
-        process.exitCode !== ExitCode.StageFailed) {
-        return;
-    }
-    // StageFailed from fan-out means some specifiers failed; per CTS-SPEC-5 the
-    // pipeline continues. Other areas still produced partials.
-    if (process.exitCode === ExitCode.StageFailed) {
-        process.exitCode = 0;
-    }
-    // Stage 4 — Compose
-    await composeCommand({ projectRoot: options.projectRoot });
-    if (process.exitCode && process.exitCode !== 0) {
-        return;
-    }
-    // Stage 5 — Spec review + edit loop
-    await editLoopCommand({
-        maxTurns: options.maxTurns,
-        model: options.model,
-        projectRoot: options.projectRoot,
-    });
-    if (process.exitCode &&
-        process.exitCode !== 0 &&
-        process.exitCode !== ExitCode.MaxTurnsHit) {
-        return;
-    }
-    if (process.exitCode === ExitCode.MaxTurnsHit) {
-        process.exitCode = 0;
-    }
-    // Stage 6 — Present (write final spec to .requirements/ + emit summary)
-    await presentCommand({
-        forceMode: options.forceMode,
-        overwrite: options.overwrite,
-        skipExisting: options.skipExisting,
-        ignoreRequirements: options.ignoreRequirements,
-        projectRoot: options.projectRoot,
-    });
-    // Present sets a non-zero exit code on overwrite refusal or validation
-    // failure; let it propagate.
-}
-//# sourceMappingURL=run.js.map

package/dist/commands/codebase-to-spec/specify-area.d.ts

@@ -1,18 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec specify-area <name>` subcommand.
- *
- * Runs a single specifier for one named area from the cached outline. Useful
- * for retrying a single failed area, or for scripting.
- *
- * Requirements covered:
- * - CTS-CLI-2: granular `specify-area` subcommand
- * - CTS-SPEC-1..4: per-area specifier behavior
- */
-export interface SpecifyAreaOptions {
-    model?: string;
-    /** Path to the CLI binary (defaults to `dotrequirements`). */
-    cliBinary?: string;
-    projectRoot?: string;
-}
-export declare function specifyAreaCommand(areaName: string, options?: SpecifyAreaOptions): Promise<void>;
-//# sourceMappingURL=specify-area.d.ts.map

package/dist/commands/codebase-to-spec/specify-area.js

@@ -1,82 +0,0 @@
-/**
- * `dotrequirements codebase-to-spec specify-area <name>` subcommand.
- *
- * Runs a single specifier for one named area from the cached outline. Useful
- * for retrying a single failed area, or for scripting.
- *
- * Requirements covered:
- * - CTS-CLI-2: granular `specify-area` subcommand
- * - CTS-SPEC-1..4: per-area specifier behavior
- */
-import { existsSync } from "node:fs";
-import { cachePaths } from "../../codebase-to-spec/cache.js";
-import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
-import { sanitizeAreaName } from "../../codebase-to-spec/fan-out.js";
-import { StdoutProgress } from "../../codebase-to-spec/progress.js";
-import { extractSlice } from "../../codebase-to-spec/slice.js";
-import { runSpecifier } from "../../codebase-to-spec/specifier.js";
-import { findProjectRoot } from "../../utils/project-settings.js";
-import { readFinalOutline } from "./plan-loop.js";
-export async function specifyAreaCommand(areaName, options = {}) {
-    const progress = new StdoutProgress();
-    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
-    const paths = cachePaths(projectRoot);
-    const cliBinary = options.cliBinary ?? "dotrequirements";
-    if (!existsSync(paths.outlineFinal)) {
-        process.stderr.write(`Missing outline at ${paths.outlineFinal}. Run \`dotrequirements cts plan-loop\` first.\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    if (!existsSync(paths.source)) {
-        process.stderr.write(`Missing uncompressed pack at ${paths.source}. Run \`dotrequirements cts pack\` first.\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    const outline = readFinalOutline(projectRoot);
-    const area = outline.areas.find((a) => a.name === areaName ||
-        a.prefix === areaName ||
-        sanitizeAreaName(a.name) === sanitizeAreaName(areaName));
-    if (!area) {
-        process.stderr.write(`No area named "${areaName}" in outline. Available areas:\n${outline.areas
-            .map((a) => `  - ${a.name} (prefix: ${a.prefix})`)
-            .join("\n")}\n`);
-        process.exitCode = ExitCode.MissingInput;
-        return;
-    }
-    const sanitized = sanitizeAreaName(area.name);
-    const slicePath = `${paths.partialsDir}/slice-${sanitized}.txt`;
-    const partialPath = paths.partial(sanitized);
-    progress.emit({
-        stage: "specify",
-        step: area.prefix,
-        message: `Extracting slice for ${area.name}`,
-    });
-    extractSlice(paths.source, slicePath, area.files);
-    progress.emit({
-        stage: "specify",
-        step: area.prefix,
-        message: `Running specifier for ${area.name}`,
-    });
-    const result = await runSpecifier({
-        outline,
-        area,
-        slicePath,
-        fullPackPath: paths.source,
-        partialPath,
-        validateCommand: `${cliBinary} cts validate`,
-        styleCheckCommand: `${cliBinary} cts style-check`,
-        addDirs: [paths.root],
-        model: options.model,
-    });
-    if (!result.wrotePartial) {
-        process.stderr.write(`Specifier for ${area.name} produced no partial (exit ${result.exitCode}).\n${result.stderr}\n`);
-        process.exitCode = ExitCode.StageFailed;
-        return;
-    }
-    progress.emit({
-        stage: "specify",
-        step: area.prefix,
-        message: `Done. Partial saved to ${partialPath} (${result.partialBytes} bytes)`,
-    });
-}
-//# sourceMappingURL=specify-area.js.map