ai-spector 0.8.40 → 0.8.42

package/dist/cli.js

@@ -6,6 +6,8 @@ import { writeJson, readJson } from "./core/util/fs.js";
 import { resolveProjectPaths } from "./core/util/paths.js";
 import { buildSectionRegistry } from "./core/registry/build.js";
 import { bootstrapFromRegistry } from "./core/operations/bootstrap.js";
+import { applyPrimaryLanguageOutputs } from "./core/graph/translation.js";
+import { loadDocflowConfig } from "./core/config/load.js";
 import { validateGraph, formatIssues } from "./core/operations/validate.js";
 import { runInit } from "./core/operations/init.js";
 import { runLangAdd, runLangSetClient } from "./core/operations/lang.js";
@@ -13,6 +15,14 @@ import { runLangQueueFailed, runLangQueueFail, runLangQueuePending, runLangQueue
 import { formatPendingTable, formatResolvedTable, formatFailedTable } from "./core/lang/queue.js";
 import { runHooksInstall, runHooksPreCommit, formatPreCommitReport } from "./core/operations/hooks.js";
 import { runSetup, runSetupCheck } from "./core/operations/setup.js";
+import { runCheck } from "./core/operations/check.js";
+import { formatCheck } from "./interfaces/cli/format/check.js";
+import { runContextList, runContextRecord, runContextResolve, } from "./core/operations/context.js";
+import { formatContextList, formatContextRecord, formatContextResolve, } from "./interfaces/cli/format/context.js";
+import { runSpecList, runSpecApprove, runSpecReject, } from "./core/operations/extracted.js";
+import { formatSpecList, formatSpecApprove, formatSpecReject, } from "./interfaces/cli/format/extracted.js";
+import { runTaskAbandon, runTaskApprovePlan, runTaskComplete, runTaskCreate, runTaskGet, runTaskList, runTaskPause, runTaskResume, runTaskUpdate, recordGenerateWaveProgress, } from "./core/operations/task.js";
+import { formatTaskCreate, formatTaskGet, formatTaskList, formatTaskSimple, formatTaskUpdate, } from "./interfaces/cli/format/task.js";
 import { runSyncCursor } from "./core/operations/sync-cursor.js";
 import { runGraphQuery } from "./core/operations/graph-query.js";
 import { runGraphImpact } from "./core/operations/graph-impact.js";
@@ -113,6 +123,361 @@ program
         console.log(formatSetupAudit(audit, true));
     }
 });
+program
+    .command("check")
+    .description("Validate workspace structure & config (warns on drift; non-zero exit on errors)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--fix", "Auto-create missing directories where possible")
+    .option("-p, --path <paths...>", "Validate specific doc output path(s) after writing (repeatable)")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const root = resolve(opts.cwd ?? process.cwd());
+    const paths = opts.path;
+    const result = await runCheck({ root, fix: opts.fix, paths });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatCheck(result));
+    if (!result.ok)
+        process.exitCode = 1;
+});
+const context = program
+    .command("context")
+    .description("Clarification context store (questions answered before generation)");
+context
+    .command("list")
+    .description("List context entries, optionally filtered by doc type / status")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("-t, --doc-type <type>", "Doc type store (e.g. srs)")
+    .option("-s, --status <status>", "Filter: open | answered | stale")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const result = await runContextList({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType: opts.docType,
+        status: opts.status,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatContextList(result));
+});
+context
+    .command("record <docType> <question>")
+    .description("Record a clarifying question (pass --answer to record it answered)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("-a, --answer <answer>", "Answer (records entry as answered)")
+    .option("--scope <scope>", "DAG node / section this informs (e.g. srs.use-cases)")
+    .option("--source <source>", "user | inferred | data-source", "user")
+    .option("--refs <paths>", "Comma-separated source files that make this stale on change")
+    .option("--by <name>", "Who answered")
+    .option("--json", "JSON output")
+    .action(async (docType, question, opts) => {
+    const result = await runContextRecord({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType,
+        question,
+        answer: opts.answer,
+        scope: opts.scope,
+        source: opts.source,
+        sourceRefs: opts.refs
+            ? opts.refs.split(",").map((s) => s.trim()).filter(Boolean)
+            : undefined,
+        answeredBy: opts.by,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatContextRecord(result));
+});
+context
+    .command("resolve <docType> <id> <answer>")
+    .description("Answer an open/stale entry by id (e.g. Q-001)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--by <name>", "Who answered")
+    .option("--json", "JSON output")
+    .action(async (docType, id, answer, opts) => {
+    const result = await runContextResolve({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType,
+        id,
+        answer,
+        answeredBy: opts.by,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatContextResolve(result));
+});
+const spec = program
+    .command("spec")
+    .description("Extracted-spec review queue (specs pulled from generated docs, approved before graph merge)");
+spec
+    .command("list")
+    .description("List extracted specs, optionally filtered by doc type / status")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("-t, --doc-type <type>", "Doc type queue (e.g. srs)")
+    .option("-s, --status <status>", "Filter: pending | approved | rejected")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const result = await runSpecList({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType: opts.docType,
+        status: opts.status,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatSpecList(result));
+});
+spec
+    .command("approve <docType> <id>")
+    .description("Approve a pending spec; merges its graph patch (if any) into the graph")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--by <name>", "Reviewer name")
+    .option("--note <note>", "Review note")
+    .option("--skip-merge", "Approve without merging the graph patch")
+    .option("--json", "JSON output")
+    .action(async (docType, id, opts) => {
+    const result = await runSpecApprove({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType,
+        id,
+        by: opts.by,
+        note: opts.note,
+        skipMerge: opts.skipMerge,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatSpecApprove(result));
+});
+spec
+    .command("reject <docType> <id>")
+    .description("Reject a pending spec (kept for audit, never merged)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--by <name>", "Reviewer name")
+    .option("--note <note>", "Why the spec was rejected")
+    .option("--json", "JSON output")
+    .action(async (docType, id, opts) => {
+    const result = await runSpecReject({
+        root: resolve(opts.cwd ?? process.cwd()),
+        docType,
+        id,
+        by: opts.by,
+        note: opts.note,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatSpecReject(result));
+});
+const task = program
+    .command("task")
+    .description("Workflow task state (persist plan/progress across sessions)");
+task
+    .command("create")
+    .description("Create a new workflow task")
+    .requiredOption("-k, --kind <kind>", "generate | resolve")
+    .requiredOption("-w, --workflow <workflow>", "generate-srs | generate-basic-design | resolve")
+    .requiredOption("-t, --trigger <text>", "User intent that started this task")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--doc-type <type>", "Doc type for generate workflows (e.g. srs)")
+    .option("--force", "Replace existing active task in the same slot")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const result = await runTaskCreate({
+        root: resolve(opts.cwd ?? process.cwd()),
+        kind: opts.kind,
+        workflow: opts.workflow,
+        trigger: opts.trigger,
+        docType: opts.docType,
+        force: opts.force,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskCreate(result));
+});
+task
+    .command("list")
+    .description("List tasks")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("-s, --status <status>", "Filter by status (comma-separated)")
+    .option("-k, --kind <kind>", "generate | resolve")
+    .option("-w, --workflow <workflow>", "Workflow id filter")
+    .option("--recent", "Only tasks in index.recent")
+    .option("--json", "JSON output")
+    .action(async (opts) => {
+    const status = opts.status
+        ? opts.status.split(",").map((s) => s.trim())
+        : undefined;
+    const result = await runTaskList({
+        root: resolve(opts.cwd ?? process.cwd()),
+        status: status?.length === 1 ? status[0] : status,
+        kind: opts.kind,
+        workflow: opts.workflow,
+        recentOnly: opts.recent,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskList(result));
+});
+task
+    .command("get <taskId>")
+    .description("Get full task state")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskGet({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskGet(result));
+});
+task
+    .command("update <taskId>")
+    .description("Patch task state (pass --patch as JSON)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--patch <json>", "JSON patch object (TaskUpdatePatch)")
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    if (!opts.patch) {
+        throw new Error("--patch is required (JSON object)");
+    }
+    const patch = JSON.parse(opts.patch);
+    const result = await runTaskUpdate({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+        patch,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskUpdate(result));
+});
+task
+    .command("approve <taskId>")
+    .description("Approve the task plan and advance to the next step")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--plan <json>", "Plan JSON (StoredPlan) if not already set on task")
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskApprovePlan({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+        plan: opts.plan ? JSON.parse(opts.plan) : undefined,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskSimple("Approved plan for", result));
+});
+task
+    .command("pause <taskId>")
+    .description("Pause a task")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskPause({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskSimple("Paused", result));
+});
+task
+    .command("resume <taskId>")
+    .description("Resume a paused task (validates workspace and drift)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskResume({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        const lines = [
+            `Resume ${result.task.id} — canContinue: ${result.canContinue}`,
+            `  workspace: ${result.workspaceOk ? "ok" : "errors"}`,
+            `  drift:     ${result.drift.length} file(s)`,
+            `  stale:     ${result.staleContextIds.join(", ") || "none"}`,
+            `  next:      ${result.suggestedNext}`,
+        ];
+        if (result.drift.length > 0) {
+            for (const d of result.drift) {
+                lines.push(`    ${d.kind}: ${d.path}`);
+            }
+        }
+        console.log(lines.join("\n"));
+    }
+});
+task
+    .command("complete <taskId>")
+    .description("Mark a task complete")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--summary <text>", "Completion summary")
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskComplete({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+        summary: opts.summary,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskSimple("Completed", result));
+});
+task
+    .command("record-wave <taskId> <waveId>")
+    .description("Record generate wave progress (e.g. wave-1 done with artifacts)")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("-s, --status <status>", "done | in-progress | blocked", "done")
+    .option("--artifacts <paths>", "Comma-separated doc paths written this wave")
+    .option("--blocker <text>", "Blocker message when status is blocked")
+    .option("--json", "JSON output")
+    .action(async (taskId, waveId, opts) => {
+    const result = await recordGenerateWaveProgress({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+        waveId,
+        status: opts.status,
+        artifacts: opts.artifacts
+            ? opts.artifacts.split(",").map((p) => p.trim()).filter(Boolean)
+            : undefined,
+        blocker: opts.blocker ?? null,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskUpdate(result));
+});
+task
+    .command("abandon <taskId>")
+    .description("Abandon a task")
+    .option("-C, --cwd <path>", "Project root", process.cwd())
+    .option("--reason <text>", "Why the task was abandoned")
+    .option("--json", "JSON output")
+    .action(async (taskId, opts) => {
+    const result = await runTaskAbandon({
+        root: resolve(opts.cwd ?? process.cwd()),
+        taskId,
+        reason: opts.reason,
+    });
+    if (opts.json)
+        console.log(JSON.stringify(result, null, 2));
+    else
+        console.log(formatTaskSimple("Abandoned", result));
+});
 const lang = program.command("lang").description("Manage project languages");
 lang
     .command("add <code>")
@@ -287,6 +652,16 @@ graph
     const graphPath = opts.output ?? paths.graph;
     const registry = await readJson(registryPath);
     const graph = bootstrapFromRegistry(registry);
+    try {
+        const { config } = await loadDocflowConfig(paths.root);
+        const primary = config.languages[0];
+        if (primary) {
+            applyPrimaryLanguageOutputs(graph, primary.code, config.languages.map((l) => l.code));
+        }
+    }
+    catch {
+        // uninitialized project — keep manifest paths as-is
+    }
     await writeJson(graphPath, graph.toTraceabilityGraph());
     console.log(`Wrote ${graphPath} (${graph.nodesById.size} nodes, ${graph.toTraceabilityGraph().edges.length} edges)`);
 });
@@ -301,6 +676,7 @@ graph
     const paths = await getPaths(cmd);
     const result = await runGraphQuery({
         graphPath: paths.graph,
+        projectRoot: paths.root,
         seedId: id,
         direction: opts.direction,
         depth: Number(opts.depth),
@@ -876,9 +1252,10 @@ cocoindex
 });
 // ── resolve-task ──────────────────────────────────────────────────────────────
 program
-    .command("resolve-task <planJson>")
-    .description("Execute a resolve-task plan from a JSON file. The file must contain { intent, goalSpec, plan }.")
+    .command("resolve-task [planJson]")
+    .description("Execute a resolve-task plan from a JSON file or --task-id (approved task in .ai-spector/.docflow/tasks/).")
     .option("--root <path>", "Project root (default: cwd)")
+    .option("--task-id <id>", "Load approved plan from task file")
     .option("--dry-run", "Validate plan without writing any changes")
     .option("--json", "JSON output")
     .action(async (planJson, opts) => {
@@ -889,8 +1266,28 @@ program
     const { runGraphReport } = await import("./core/operations/graph-report.js");
     const { runGraphImpact } = await import("./core/operations/graph-impact.js");
     const { resolveProjectPaths } = await import("./core/util/paths.js");
-    const raw = await readJson(resolve(planJson));
+    const { loadResolveExecutionContext, recordResolveStepProgress, } = await import("./core/operations/task.js");
     const paths = await resolveProjectPaths(opts.root);
+    let intent;
+    let goalSpec;
+    let plan;
+    const taskId = opts.taskId;
+    if (taskId) {
+        const ctx = await loadResolveExecutionContext({ root: paths.root, taskId });
+        intent = ctx.intent;
+        goalSpec = ctx.goalSpec;
+        plan = ctx.plan;
+    }
+    else {
+        if (!planJson) {
+            throw new Error("Provide planJson path or --task-id");
+        }
+        const raw = await readJson(resolve(planJson));
+        goalSpec = createGoalSpec(raw.goalSpec.trigger, raw.goalSpec.domain, raw.goalSpec.scope, raw.goalSpec.criteria, raw.goalSpec.notes);
+        plan = createPlan(goalSpec, raw.plan.steps, goalSpec.scope.map((nodeId) => ({ nodeId, directCallers: 0, riskLevel: "low" })));
+        plan.approvedAt = new Date().toISOString();
+        intent = raw.intent;
+    }
     const executors = {
         index: async (_args, root) => {
             await runIndex({ root, graphOnly: false, docsOnly: false });
@@ -916,11 +1313,21 @@ program
             return { artifacts: [] };
         },
     };
-    const goalSpec = createGoalSpec(raw.goalSpec.trigger, raw.goalSpec.domain, raw.goalSpec.scope, raw.goalSpec.criteria, raw.goalSpec.notes);
-    const plan = createPlan(goalSpec, raw.plan.steps, goalSpec.scope.map((nodeId) => ({ nodeId, directCallers: 0, riskLevel: "low" })));
-    plan.approvedAt = new Date().toISOString();
+    const onStepComplete = taskId
+        ? async (event) => {
+            await recordResolveStepProgress({
+                root: paths.root,
+                taskId,
+                plan: event.plan,
+                stepId: event.stepId,
+                stepStatus: event.status,
+                artifacts: event.artifacts,
+                blocker: event.issue ?? null,
+            });
+        }
+        : undefined;
     const result = await runResolveTask({
-        intent: raw.intent,
+        intent,
         goalSpec,
         plan,
         projectRoot: paths.root,
@@ -928,6 +1335,7 @@ program
         rulesPath: paths.rulesImpact,
         executors,
         dryRun: opts.dryRun,
+        onStepComplete,
     });
     if (opts.json)
         console.log(JSON.stringify(result, null, 2));