@popoverai/dotrequirements 0.24.3 → 0.26.0

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

@@ -1,13 +1,13 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * Ships as a bundle: SKILL.md + cts-worker agent definition + persona-
- * injection hook script + hook registration in `.claude/settings.local.json`.
- * The skill body (the conversational orchestrator) DEPENDS on the companion
- * files — installing just the skill without them would leave Task dispatches
- * unable to resolve their persona. For `project` scope, all four pieces are
- * installed in one shot. For `global` and `custom` scopes, only the skill
- * body is installed; the companions are project-scoped by CC convention.
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + the `codebase-to-spec`
+ * dynamic-workflow script. The skill body (the conversational orchestrator)
+ * launches the workflow, which dispatches cts-worker agents; both companions
+ * must be present for the skill to run. For `project` and `global` scope, all
+ * three pieces are installed in one shot (under the project's `.claude/` or the
+ * user's `~/.claude/`). Only a `custom` target dir is skill-only, because
+ * assistants do not auto-discover agents or workflows from arbitrary paths.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
@@ -15,25 +15,28 @@
  *
  * Requirements covered:
  * - CTS-SKILL-1, CTS-SKILL-5
- * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
+ * - CTSO-INSTALL-1 (bundles the skill, the cts-worker agent, and the workflow)
  */
 export type SkillInstallScope = "project" | "global" | "custom";
 export interface SkillInstallOptions {
     /**
-     * Where to install:
-     * - `project` (default): `<projectRoot>/.claude/skills/codebase-to-spec/`
-     *   (plus companions under `<projectRoot>/.claude/agents/` and
-     *   `<projectRoot>/.claude/hooks/`, and hook registration in
-     *   `<projectRoot>/.claude/settings.local.json`)
-     * - `global`: `~/.claude/skills/codebase-to-spec/` (skill body only)
-     * - `custom`: requires `targetDir` (skill body only)
+     * Where to install. `project` and `global` install the full bundle (skill +
+     * cts-worker agent + specify-codebase workflow) under the corresponding
+     * `.claude/` base, so the skill can launch the workflow; `custom` installs
+     * the skill body only.
+     * - `project` (default): `<projectRoot>/.claude/{skills,agents,workflows}/`
+     * - `global`: `<globalRoot>/.claude/{skills,agents,workflows}/`
+     * - `custom`: `<targetDir>/codebase-to-spec/SKILL.md` only — Claude Code does
+     *   not auto-discover agents or workflows from an arbitrary directory
      */
     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 / agent / hook if present. Default false. */
+    /** Home root for `global` scope (the parent of `.claude`). Defaults to homedir(); tests inject a temp dir. */
+    globalRoot?: string;
+    /** Overwrite existing SKILL.md / agent / workflow if present. Default false. */
     overwrite?: boolean;
 }
 export interface SkillInstallResult {
@@ -43,12 +46,10 @@ export interface SkillInstallResult {
     installed: boolean;
     /** True if an existing file was replaced. */
     overwrote: boolean;
-    /** Companion files installed alongside the skill (project scope only). */
+    /** Companion files installed alongside the skill (project + global scope). */
     companions?: {
         agentPath: string;
-        hookScriptPath: string;
-        settingsPath: string;
-        hookRegistered: boolean;
+        workflowPath: string;
     };
 }
 /**
@@ -58,24 +59,36 @@ export interface SkillInstallResult {
  */
 export declare function resolveSkillDir(options: SkillInstallOptions): string;
 /**
- * Load the bundled SKILL.md template from the package.
+ * Resolve the CLI invocation stamped into the installed artifacts
+ * (CTSO-INSTALL-5): a version-pinned `npx` invocation of this very package,
+ * so the installed bundle runs without `dotrequirements` on PATH and always
+ * shells out to the same CLI version that performed the install.
  */
-export declare function loadSkillTemplate(): string;
+export declare function resolveCliInvocation(): string;
 /**
- * Load the bundled cts-worker agent definition template.
+ * Load the bundled SKILL.md template, rendering `{{DOTREQ_CLI}}` to the given
+ * CLI invocation (defaults to the version-pinned npx form).
  */
-export declare function loadAgentTemplate(): string;
+export declare function loadSkillTemplate(cliInvocation?: string): string;
 /**
- * Load the bundled persona-injection hook script template.
+ * Load the bundled cts-worker agent definition template, rendering
+ * `{{DOTREQ_CLI}}` to the given CLI invocation.
  */
-export declare function loadHookTemplate(): string;
+export declare function loadAgentTemplate(cliInvocation?: string): string;
+/**
+ * Load the bundled specify-codebase dynamic-workflow script template,
+ * rendering `{{DOTREQ_CLI}}` to the given CLI invocation.
+ */
+export declare function loadWorkflowTemplate(cliInvocation?: string): string;
 /**
  * Install (or refuse to overwrite) the codebase-to-spec skill bundle.
  *
- * For `project` scope: installs skill body, cts-worker agent, persona hook
- * script, and registers the hook in settings.local.json.
+ * For `project` and `global` scope: installs the full bundle — the skill body,
+ * the cts-worker agent, and the specify-codebase workflow — under the matching
+ * `.claude/` base (the project's, or the user's `~/.claude/`).
  *
- * For `global` and `custom` scopes: installs only the skill body.
+ * For `custom` scope: installs only the skill body, because Claude Code does
+ * not auto-discover agents or workflows from an arbitrary directory.
  */
 export declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
 //# sourceMappingURL=skill-install.d.ts.map

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

@@ -1,13 +1,13 @@
 /**
  * Skill installation logic for the codebase-to-spec skill.
  *
- * Ships as a bundle: SKILL.md + cts-worker agent definition + persona-
- * injection hook script + hook registration in `.claude/settings.local.json`.
- * The skill body (the conversational orchestrator) DEPENDS on the companion
- * files — installing just the skill without them would leave Task dispatches
- * unable to resolve their persona. For `project` scope, all four pieces are
- * installed in one shot. For `global` and `custom` scopes, only the skill
- * body is installed; the companions are project-scoped by CC convention.
+ * Ships as a bundle: SKILL.md + cts-worker agent definition + the `codebase-to-spec`
+ * dynamic-workflow script. The skill body (the conversational orchestrator)
+ * launches the workflow, which dispatches cts-worker agents; both companions
+ * must be present for the skill to run. For `project` and `global` scope, all
+ * three pieces are installed in one shot (under the project's `.claude/` or the
+ * user's `~/.claude/`). Only a `custom` target dir is skill-only, because
+ * assistants do not auto-discover agents or workflows from arbitrary paths.
  *
  * Host portability (CTS-SKILL-5): the install logic supports any host that
  * follows the Agent Skills format. The default target is Claude Code's
@@ -15,11 +15,13 @@
  *
  * Requirements covered:
  * - CTS-SKILL-1, CTS-SKILL-5
- * - CTSO-CLI-1 (bundles the agent + hook that PreToolUse-injects persona bodies)
+ * - CTSO-INSTALL-1 (bundles the skill, the cts-worker agent, and the workflow)
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { getOwnPackage } from "../utils/own-package.js";
 import { loadTemplate } from "../utils/templates.js";
 /**
  * Resolve the directory in which the skill should live, given the user's
@@ -34,7 +36,7 @@ export function resolveSkillDir(options) {
             return join(root, ".claude", "skills", "codebase-to-spec");
         }
         case "global":
-            return join(homedir(), ".claude", "skills", "codebase-to-spec");
+            return join(options.globalRoot ?? homedir(), ".claude", "skills", "codebase-to-spec");
         case "custom":
             if (!options.targetDir) {
                 throw new Error('targetDir is required when scope === "custom"');
@@ -45,136 +47,144 @@ export function resolveSkillDir(options) {
     }
 }
 /**
- * Load the bundled SKILL.md template from the package.
+ * Resolve the CLI invocation stamped into the installed artifacts
+ * (CTSO-INSTALL-5): a version-pinned `npx` invocation of this very package,
+ * so the installed bundle runs without `dotrequirements` on PATH and always
+ * shells out to the same CLI version that performed the install.
  */
-export function loadSkillTemplate() {
-    return loadTemplate("skills/codebase-to-spec/SKILL.md");
+export function resolveCliInvocation() {
+    const pkg = getOwnPackage();
+    return `npx -y ${pkg.name}@${pkg.version}`;
 }
 /**
- * Load the bundled cts-worker agent definition template.
+ * Load the bundled SKILL.md template, rendering `{{DOTREQ_CLI}}` to the given
+ * CLI invocation (defaults to the version-pinned npx form).
  */
-export function loadAgentTemplate() {
-    return loadTemplate("agents/cts-worker.md");
+export function loadSkillTemplate(cliInvocation = resolveCliInvocation()) {
+    return loadTemplate("skills/codebase-to-spec/SKILL.md", {
+        DOTREQ_CLI: cliInvocation,
+    });
 }
 /**
- * Load the bundled persona-injection hook script template.
+ * Load the bundled cts-worker agent definition template, rendering
+ * `{{DOTREQ_CLI}}` to the given CLI invocation.
  */
-export function loadHookTemplate() {
-    return loadTemplate("hooks/cts-worker-persona.sh");
+export function loadAgentTemplate(cliInvocation = resolveCliInvocation()) {
+    return loadTemplate("agents/cts-worker.md", { DOTREQ_CLI: cliInvocation });
 }
 /**
- * Install (or refuse to overwrite) one template file at a target path.
- * Returns true if a write happened.
+ * Load the bundled specify-codebase dynamic-workflow script template,
+ * rendering `{{DOTREQ_CLI}}` to the given CLI invocation.
  */
-function installTemplateFile(templateContent, targetPath, overwrite, description) {
-    const exists = existsSync(targetPath);
-    if (exists && !overwrite) {
-        const onDisk = readFileSync(targetPath, "utf-8");
-        if (onDisk === templateContent) {
-            return { installed: false, overwrote: false };
-        }
-        throw new Error(`${description} already exists at ${targetPath} and differs from the bundled template. Pass --overwrite to replace it, or delete the file first.`);
-    }
-    mkdirSync(dirname(targetPath), { recursive: true });
-    writeFileSync(targetPath, templateContent, "utf-8");
-    return { installed: true, overwrote: exists };
+export function loadWorkflowTemplate(cliInvocation = resolveCliInvocation()) {
+    return loadTemplate("workflows/specify-codebase.js", {
+        DOTREQ_CLI: cliInvocation,
+    });
 }
 /**
- * Register the cts-worker-persona PreToolUse hook in the project's
- * `.claude/settings.local.json`, preserving any existing keys.
- *
- * Returns true if the hook registration was added or updated.
+ * Manifest written next to the installed SKILL.md, recording the content hash
+ * of every file the install wrote. On a later re-run, an on-disk file whose
+ * hash still matches its manifest entry is a *stock* install (possibly from an
+ * older CLI version) and is safe to refresh without --overwrite; a mismatch
+ * means the user hand-edited it (CTSO-INSTALL-6).
  */
-function registerHookInSettings(projectRoot, hookScriptPath) {
-    const settingsPath = join(projectRoot, ".claude", "settings.local.json");
-    const hookEntry = {
-        matcher: "Task",
-        hooks: [{ type: "command", command: hookScriptPath }],
-    };
-    // Read existing settings if present.
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            const content = readFileSync(settingsPath, "utf-8");
-            if (content.trim()) {
-                settings = JSON.parse(content);
-            }
-        }
-        catch {
-            // Invalid JSON — refuse to clobber. Tell caller to fix manually.
-            throw new Error(`Existing ${settingsPath} contains invalid JSON. Fix it or delete it before installing the orchestrator hook.`);
-        }
+const MANIFEST_FILENAME = ".install-manifest.json";
+function sha256(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function readManifest(skillDir) {
+    const manifestPath = join(skillDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf-8"));
     }
-    // Initialize the hooks tree if missing.
-    // biome-ignore lint/suspicious/noExplicitAny: settings.local.json is user-owned; we narrow ad-hoc.
-    const hooks = (settings.hooks ?? {});
-    const preToolUse = (hooks.PreToolUse ?? []);
-    // Check if an entry already references our hook script (idempotent).
-    const alreadyRegistered = preToolUse.some((entry) => {
-        if (entry.matcher !== "Task")
-            return false;
-        const innerHooks = entry.hooks;
-        if (!Array.isArray(innerHooks))
-            return false;
-        return innerHooks.some((h) => h.command === hookScriptPath);
-    });
-    if (alreadyRegistered) {
-        return { settingsPath, registered: false };
+    catch {
+        // An unreadable manifest gives no provenance; fall back to treating
+        // differing files as hand-edited (the safe direction).
+        return undefined;
+    }
+}
+function classifyPiece(key, description, targetPath, content, manifest) {
+    if (!existsSync(targetPath)) {
+        return { key, description, targetPath, content, state: "missing" };
+    }
+    const onDisk = readFileSync(targetPath, "utf-8");
+    if (onDisk === content) {
+        return { key, description, targetPath, content, state: "current" };
+    }
+    if (manifest?.files[key] === sha256(onDisk)) {
+        return { key, description, targetPath, content, state: "stock" };
     }
-    preToolUse.push(hookEntry);
-    hooks.PreToolUse = preToolUse;
-    settings.hooks = hooks;
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
-    return { settingsPath, registered: true };
+    return { key, description, targetPath, content, state: "modified" };
 }
 /**
  * Install (or refuse to overwrite) the codebase-to-spec skill bundle.
  *
- * For `project` scope: installs skill body, cts-worker agent, persona hook
- * script, and registers the hook in settings.local.json.
+ * For `project` and `global` scope: installs the full bundle — the skill body,
+ * the cts-worker agent, and the specify-codebase workflow — under the matching
+ * `.claude/` base (the project's, or the user's `~/.claude/`).
  *
- * For `global` and `custom` scopes: installs only the skill body.
+ * For `custom` scope: installs only the skill body, because Claude Code does
+ * not auto-discover agents or workflows from an arbitrary directory.
  */
 export function installSkill(options = {}) {
     const skillDir = resolveSkillDir(options);
     const skillPath = join(skillDir, "SKILL.md");
-    const skillTemplate = loadSkillTemplate();
-    const skillResult = installTemplateFile(skillTemplate, skillPath, options.overwrite === true, "SKILL.md");
-    // Skill body only for global/custom scopes — CC reads agents and hooks
-    // per-project, so the companions don't make sense outside a project.
     const scope = options.scope ?? "project";
-    if (scope !== "project") {
-        return {
-            installedPath: skillPath,
-            installed: skillResult.installed,
-            overwrote: skillResult.overwrote,
-        };
+    const cliInvocation = resolveCliInvocation();
+    const manifest = readManifest(skillDir);
+    // Classify every piece before writing anything, so a hand-edit refusal
+    // never leaves a partially refreshed bundle (CTSO-INSTALL-6).
+    const pieces = [
+        classifyPiece("skill", "SKILL.md", skillPath, loadSkillTemplate(cliInvocation), manifest),
+    ];
+    // A custom target dir is an arbitrary location CC won't read agents or
+    // workflows from, so it gets the skill body only. Project and global both
+    // install the full bundle under their `.claude/` base.
+    let companions;
+    if (scope !== "custom") {
+        const claudeBase = scope === "global"
+            ? join(options.globalRoot ?? homedir(), ".claude")
+            : join(options.projectRoot ?? process.cwd(), ".claude");
+        const agentPath = join(claudeBase, "agents", "cts-worker.md");
+        const workflowPath = join(claudeBase, "workflows", "specify-codebase.js");
+        pieces.push(classifyPiece("agent", "cts-worker agent definition", agentPath, loadAgentTemplate(cliInvocation), manifest), 
+        // The workflow script is discovered by name from .claude/workflows/;
+        // no settings registration needed, unlike a hook.
+        classifyPiece("workflow", "specify-codebase workflow script", workflowPath, loadWorkflowTemplate(cliInvocation), manifest));
+        companions = { agentPath, workflowPath };
     }
-    const projectRoot = options.projectRoot ?? process.cwd();
-    const agentPath = join(projectRoot, ".claude", "agents", "cts-worker.md");
-    const hookScriptPath = join(projectRoot, ".claude", "hooks", "cts-worker-persona.sh");
-    // Install the cts-worker agent definition.
-    installTemplateFile(loadAgentTemplate(), agentPath, options.overwrite === true, "cts-worker agent definition");
-    // Install the persona-injection hook script (executable bit set separately).
-    installTemplateFile(loadHookTemplate(), hookScriptPath, options.overwrite === true, "cts-worker-persona hook script");
-    // chmod the hook script to be executable so Claude Code's PreToolUse
-    // hook can invoke it. (Imported statically — the CLI package is ESM, so
-    // `require("node:fs")` here would throw ReferenceError and silently
-    // leave the script at 0644, breaking the hook on every install.)
-    chmodSync(hookScriptPath, 0o755);
-    // Register the hook in settings.local.json.
-    const { settingsPath, registered } = registerHookInSettings(projectRoot, hookScriptPath);
+    // Hand-edited files block the whole refresh (named individually) unless
+    // --overwrite; unmodified-stock files from any prior version refresh freely.
+    if (options.overwrite !== true) {
+        const modified = pieces.filter((p) => p.state === "modified");
+        if (modified.length > 0) {
+            const lines = modified.map((p) => `  ${p.description}: ${p.targetPath}`);
+            throw new Error(`Refusing to replace file(s) modified since install (or installed without manifest tracking):\n${lines.join("\n")}\nPass --overwrite to replace, or delete the file(s) first.`);
+        }
+    }
+    const skillPiece = pieces[0];
+    for (const piece of pieces) {
+        if (piece.state === "current")
+            continue;
+        mkdirSync(dirname(piece.targetPath), { recursive: true });
+        writeFileSync(piece.targetPath, piece.content, "utf-8");
+    }
+    // Record what this install wrote (or confirmed current) so the next re-run
+    // can tell stock content from hand-edits. Also adopts manifest-less installs
+    // whose content matches the current templates.
+    const manifestOut = {
+        version: getOwnPackage().version,
+        files: Object.fromEntries(pieces.map((p) => [p.key, sha256(p.content)])),
+    };
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, MANIFEST_FILENAME), `${JSON.stringify(manifestOut, null, 2)}\n`, "utf-8");
     return {
         installedPath: skillPath,
-        installed: skillResult.installed,
-        overwrote: skillResult.overwrote,
-        companions: {
-            agentPath,
-            hookScriptPath,
-            settingsPath,
-            hookRegistered: registered,
-        },
+        installed: skillPiece.state !== "current",
+        overwrote: skillPiece.state === "stock" || skillPiece.state === "modified",
+        companions,
     };
 }
 //# sourceMappingURL=skill-install.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * Fail-soft check for a newer published CLI version (CTS-PACK-4).
+ *
+ * The skill bundle pins the CLI version it was installed with
+ * (CTSO-INSTALL-5), so a long-lived install would otherwise run stale
+ * forever without noticing. Pack — the first deterministic step of every
+ * run — surfaces staleness so the skill can offer a refresh (CTSO-CONV-7).
+ *
+ * Any failure (offline, slow or unreachable registry, malformed response)
+ * yields `undefined`: the check must never fail or delay the pack beyond a
+ * short timeout.
+ */
+export interface VersionCheckResult {
+    current: string;
+    latest: string;
+    stale: boolean;
+}
+export declare const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 2000;
+/**
+ * True when `latest` is a strictly newer release than `current`, comparing
+ * numeric segments. Prerelease suffixes are ignored; when the numeric
+ * segments tie, the versions are treated as equal (not stale).
+ */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+export interface VersionCheckOptions {
+    timeoutMs?: number;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+}
+export declare function checkForNewerVersion(options?: VersionCheckOptions): Promise<VersionCheckResult | undefined>;
+//# sourceMappingURL=version-check.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Fail-soft check for a newer published CLI version (CTS-PACK-4).
+ *
+ * The skill bundle pins the CLI version it was installed with
+ * (CTSO-INSTALL-5), so a long-lived install would otherwise run stale
+ * forever without noticing. Pack — the first deterministic step of every
+ * run — surfaces staleness so the skill can offer a refresh (CTSO-CONV-7).
+ *
+ * Any failure (offline, slow or unreachable registry, malformed response)
+ * yields `undefined`: the check must never fail or delay the pack beyond a
+ * short timeout.
+ */
+import { getOwnPackage } from "../utils/own-package.js";
+export const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 2_000;
+/**
+ * True when `latest` is a strictly newer release than `current`, comparing
+ * numeric segments. Prerelease suffixes are ignored; when the numeric
+ * segments tie, the versions are treated as equal (not stale).
+ */
+export function isNewerVersion(latest, current) {
+    const parse = (v) => v
+        .split("-")[0]
+        .split(".")
+        .map((seg) => Number.parseInt(seg, 10) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return false;
+}
+export async function checkForNewerVersion(options = {}) {
+    try {
+        const { name, version } = getOwnPackage();
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const response = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`, {
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = (await response.json());
+        if (typeof body.version !== "string")
+            return undefined;
+        return {
+            current: version,
+            latest: body.version,
+            stale: isNewerVersion(body.version, version),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=version-check.js.map

package/dist/commands/ai-setup.d.ts

@@ -1,5 +1,16 @@
+/**
+ * Assistant identifiers accepted by the non-interactive --assistant flag
+ * (AISETUP-1). "other" is interactive-only: it prompts for a custom path.
+ */
+export declare const SUPPORTED_ASSISTANTS: readonly ["claude-code", "claude-desktop", "cursor", "antigravity", "codex", "github-copilot"];
+export interface AiSetupOptions {
+    assistant?: string;
+}
 /**
  * AI setup command - configures the MCP server for AI assistants
+ *
+ * AISETUP-1: with --assistant <id>, setup runs without any interactive prompt
+ * (an AI assistant configuring itself knows which assistant it is).
  */
-export declare function aiSetupCommand(): Promise<void>;
+export declare function aiSetupCommand(options?: AiSetupOptions): Promise<void>;
 //# sourceMappingURL=ai-setup.d.ts.map