@popoverai/dotrequirements 0.23.0 → 0.24.1

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

@@ -0,0 +1,20 @@
+/**
+ * `dotrequirements codebase-to-spec skill-install` subcommand.
+ *
+ * Installs the codebase-to-spec SKILL.md into the host's skill directory.
+ * Defaults to the project's `.claude/skills/` (Claude Code convention);
+ * `--global` installs into `~/.claude/skills/`; `--target-dir <dir>` writes
+ * to a custom location for other hosts.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular subcommand
+ * - CTS-SKILL-1, CTS-SKILL-5: install the skill artifact in a host-agnostic way
+ */
+export interface SkillInstallCmdOptions {
+    global?: boolean;
+    targetDir?: string;
+    overwrite?: boolean;
+    projectRoot?: string;
+}
+export declare function skillInstallCommand(options?: SkillInstallCmdOptions): Promise<void>;
+//# sourceMappingURL=skill-install.d.ts.map

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

@@ -0,0 +1,51 @@
+/**
+ * `dotrequirements codebase-to-spec skill-install` subcommand.
+ *
+ * Installs the codebase-to-spec SKILL.md into the host's skill directory.
+ * Defaults to the project's `.claude/skills/` (Claude Code convention);
+ * `--global` installs into `~/.claude/skills/`; `--target-dir <dir>` writes
+ * to a custom location for other hosts.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular subcommand
+ * - CTS-SKILL-1, CTS-SKILL-5: install the skill artifact in a host-agnostic way
+ */
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { installSkill, } from "../../codebase-to-spec/skill-install.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function skillInstallCommand(options = {}) {
+    if (options.global && options.targetDir) {
+        process.stderr.write("--global and --target-dir cannot be combined. Pick one.\n");
+        process.exitCode = ExitCode.InvalidFlags;
+        return;
+    }
+    const scope = options.targetDir
+        ? "custom"
+        : options.global
+            ? "global"
+            : "project";
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    try {
+        const result = installSkill({
+            scope,
+            targetDir: options.targetDir,
+            projectRoot,
+            overwrite: options.overwrite,
+        });
+        if (result.installed && result.overwrote) {
+            process.stdout.write(`Replaced SKILL.md at ${result.installedPath}\n`);
+        }
+        else if (result.installed) {
+            process.stdout.write(`Installed SKILL.md at ${result.installedPath}\n`);
+        }
+        else {
+            process.stdout.write(`SKILL.md already up to date at ${result.installedPath}\n`);
+        }
+        process.stdout.write("Skill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language).\n");
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.StageFailed;
+    }
+}
+//# sourceMappingURL=skill-install.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * `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

@@ -0,0 +1,82 @@
+/**
+ * `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

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

@@ -0,0 +1,15 @@
+/**
+ * `dotrequirements codebase-to-spec style-check <path>` subcommand.
+ *
+ * Invoked by specifier workers via Bash to get severity-categorized feedback
+ * on their own partial drafts. Stateless — fresh claude -p call.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: local style-check tool runs offline without cloud credentials
+ * - CTS-CLI-2: granular subcommand
+ */
+export interface StyleCheckCmdOptions {
+    model?: string;
+}
+export declare function styleCheckCommand(partialPath: string, options?: StyleCheckCmdOptions): Promise<void>;
+//# sourceMappingURL=style-check.d.ts.map

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

@@ -0,0 +1,42 @@
+/**
+ * `dotrequirements codebase-to-spec style-check <path>` subcommand.
+ *
+ * Invoked by specifier workers via Bash to get severity-categorized feedback
+ * on their own partial drafts. Stateless — fresh claude -p call.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: local style-check tool runs offline without cloud credentials
+ * - CTS-CLI-2: granular subcommand
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { runStyleCheck } from "../../codebase-to-spec/style-check.js";
+export async function styleCheckCommand(partialPath, options = {}) {
+    const absPath = resolve(partialPath);
+    if (!existsSync(absPath)) {
+        process.stderr.write(`File not found: ${partialPath}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    try {
+        const result = await runStyleCheck({
+            partialPath: absPath,
+            model: options.model,
+        });
+        if (result.exitCode !== 0) {
+            process.stderr.write(`style-check failed (exit ${result.exitCode})\n`);
+            process.exitCode = ExitCode.StageFailed;
+            return;
+        }
+        process.stdout.write(result.feedback);
+        if (!result.feedback.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+    }
+    catch (err) {
+        process.stderr.write(`style-check error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.StageFailed;
+    }
+}
+//# sourceMappingURL=style-check.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * `dotrequirements codebase-to-spec validate <partial-path>` subcommand.
+ *
+ * Invoked by specifier workers via Bash to get a deterministic syntax check
+ * on their own partial drafts before they run the AI-driven style-check.
+ * Mirrors the validate-then-style-check ordering documented in CLAUDE.md.
+ *
+ * Exit code is non-zero on validation failure so the specifier can detect
+ * the failure programmatically if it wants to; the formatted feedback is
+ * always written to stdout so the agent can read it via Bash output.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier runs a local schema validator on its draft,
+ *   applying any reported errors as MUST FIX before style-check.
+ * - CTS-CLI-2: granular subcommand
+ */
+export declare function validateCommand(partialPath: string): Promise<void>;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * `dotrequirements codebase-to-spec validate <partial-path>` subcommand.
+ *
+ * Invoked by specifier workers via Bash to get a deterministic syntax check
+ * on their own partial drafts before they run the AI-driven style-check.
+ * Mirrors the validate-then-style-check ordering documented in CLAUDE.md.
+ *
+ * Exit code is non-zero on validation failure so the specifier can detect
+ * the failure programmatically if it wants to; the formatted feedback is
+ * always written to stdout so the agent can read it via Bash output.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier runs a local schema validator on its draft,
+ *   applying any reported errors as MUST FIX before style-check.
+ * - CTS-CLI-2: granular subcommand
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { formatValidateFeedback, runValidate, } from "../../codebase-to-spec/validate.js";
+export async function validateCommand(partialPath) {
+    const absPath = resolve(partialPath);
+    if (!existsSync(absPath)) {
+        process.stderr.write(`File not found: ${partialPath}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const result = runValidate({ partialPath: absPath });
+    const feedback = formatValidateFeedback(result);
+    process.stdout.write(feedback);
+    if (!feedback.endsWith("\n")) {
+        process.stdout.write("\n");
+    }
+    if (!result.ok) {
+        process.exitCode = ExitCode.StageFailed;
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/create-requirement-document.d.ts

@@ -0,0 +1,2 @@
+export declare function createRequirementDocumentCommand(filePath: string | undefined): Promise<void>;
+//# sourceMappingURL=create-requirement-document.d.ts.map

package/dist/commands/create-requirement-document.js

@@ -0,0 +1,41 @@
+import { getProjectContext } from "../requirements/cloud-ai.js";
+import { loadAllRequirements } from "../requirements/index.js";
+import { generateStyleGuide, readLocalStyleGuide, } from "../requirements/style-guide.js";
+import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
+const CONVEX_URL = "https://data.dotrequirements.io";
+export async function createRequirementDocumentCommand(filePath) {
+    const workspaceRoot = process.cwd();
+    // CLI-CREATE-DOC-1.1 / .2: discover existing patterns from the workspace.
+    // Best-effort — if the workspace has no requirements yet, we just have
+    // an empty pattern set.
+    let requirements = [];
+    try {
+        const result = await loadAllRequirements(workspaceRoot);
+        requirements = result.flattened;
+    }
+    catch {
+        // No requirements found — generateStyleGuide handles empty input
+    }
+    // CLI-CREATE-DOC-1.4 / .5: optional cloud-side custom style guidance.
+    // Silently skipped if the project isn't linked or the cloud is unavailable.
+    let customStyleGuidance = null;
+    const projectRoot = findProjectRoot(workspaceRoot);
+    if (projectRoot) {
+        try {
+            const { projectId, projectSecret } = getProjectCredentials(workspaceRoot);
+            const contextData = await getProjectContext(projectId, projectSecret, CONVEX_URL);
+            customStyleGuidance = contextData?.requirementsStyleContext ?? null;
+        }
+        catch {
+            // Not linked or cloud unavailable — fall through with defaults
+        }
+    }
+    const localStyleGuide = readLocalStyleGuide(workspaceRoot);
+    console.log(generateStyleGuide({
+        requirements,
+        customStyleGuidance,
+        filePath,
+        localStyleGuide,
+    }));
+}
+//# sourceMappingURL=create-requirement-document.js.map

package/dist/commands/finalize.js

@@ -1,8 +1,8 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { finalize } from '../harness/finalize.js';
-import { findRequirementsDir, isCacheStale } from '../harness/cache.js';
-import { findProjectRoot } from '../utils/project-settings.js';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findRequirementsDir, isCacheStale } from "../harness/cache.js";
+import { finalize } from "../harness/finalize.js";
+import { findProjectRoot } from "../utils/project-settings.js";
 export async function finalizeCommand(options) {
     // Warn if cache is stale before finalizing
     if (!options.quiet) {
@@ -10,11 +10,11 @@ export async function finalizeCommand(options) {
         if (projectRoot) {
             const requirementsDir = findRequirementsDir(projectRoot);
             if (requirementsDir) {
-                const lookupPath = path.join(requirementsDir, '.cache', 'lookup.json');
+                const lookupPath = path.join(requirementsDir, ".cache", "lookup.json");
                 try {
                     const cacheStat = fs.statSync(lookupPath);
                     if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
-                        console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements prepare" to rebuild.\n');
+                        console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements harness prepare" to rebuild.\n');
                     }
                 }
                 catch {

package/dist/commands/get.d.ts

@@ -0,0 +1,2 @@
+export declare function getCommand(id: string): Promise<void>;
+//# sourceMappingURL=get.d.ts.map

package/dist/commands/get.js

@@ -0,0 +1,55 @@
+import { glob } from "glob";
+import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
+import { findFilesWithRequirement, findTestCodeForRequirement, } from "../requirements/testCodeExtractor.js";
+export async function getCommand(id) {
+    const workspaceRoot = process.cwd();
+    const { flattened } = await loadAllRequirements(workspaceRoot);
+    const tree = getRequirementTree(flattened, id);
+    // CLI-FIND-GET-1.2: missing ID → error + non-zero exit
+    if (tree.length === 0) {
+        throw new Error(`Requirement "${id}" not found`);
+    }
+    const root = tree[0];
+    // CLI-FIND-GET-1.0 / 1.1: print the tree (root or subtree)
+    console.log(`${id}`);
+    console.log(`  Document: ${root.documentTitle}`);
+    console.log(`  Source: ${root.sourceFile}`);
+    console.log();
+    console.log(formatRequirementTree(tree));
+    console.log();
+    // CLI-FIND-GET-1.3 / 1.4: print test references + code snippets
+    const testFiles = await glob("**/*.{test,spec}.{js,jsx,ts,tsx}", {
+        cwd: workspaceRoot,
+        absolute: true,
+        ignore: ["**/node_modules/**", "**/dist/**", "**/build/**"],
+    });
+    const matchingFiles = findFilesWithRequirement(testFiles, id);
+    const testCodeSections = [];
+    for (const file of matchingFiles) {
+        const testRefs = findTestCodeForRequirement(file, id);
+        // Deduplicate nested blocks — keep only outermost
+        const deduplicated = testRefs.filter((ref, i) => {
+            const isNested = testRefs.some((other, j) => {
+                if (i === j)
+                    return false;
+                return (other.startLine <= ref.startLine &&
+                    other.endLine >= ref.endLine &&
+                    (other.startLine < ref.startLine || other.endLine > ref.endLine));
+            });
+            return !isNested;
+        });
+        testCodeSections.push(...deduplicated);
+    }
+    // CLI-FIND-GET-1.5: explicit "no tests" message
+    if (testCodeSections.length === 0) {
+        console.log("Test Coverage: No tests found referencing this requirement.");
+        return;
+    }
+    console.log(`Test Coverage (${testCodeSections.length} reference(s)):\n`);
+    for (const ref of testCodeSections) {
+        console.log(`${ref.requirementId} — ${ref.file}:${ref.startLine}-${ref.endLine}`);
+        console.log(ref.code);
+        console.log();
+    }
+}
+//# sourceMappingURL=get.js.map