cool-workflow 0.1.85 → 0.1.86

package/dist/capability-core.js

@@ -179,8 +179,8 @@ function compactOperatorStatus(status) {
 // functions so `cw <cmd> --json` is byte-identical to `cw_<tool>`. Each accepts
 // the raw CLI options OR the raw MCP arguments and normalizes them identically,
 // then calls the single RunRegistry method. The registry is constructed from the
-// same resolved cwd on both surfaces (CLI: --cwd|process.cwd(); MCP chdir'd to
-// args.cwd), so repo/home roots line up.
+// same resolved cwd on both surfaces (CLI: --cwd|process.cwd(); MCP passes a
+// resolved cwd and scopes the runner), so repo/home roots line up.
 function runRegistryFor(args, planner) {
     return new run_registry_1.RunRegistry(String(args.cwd || process.cwd()), planner);
 }
@@ -545,6 +545,8 @@ exports.QUICKSTART_DEFAULT_APP = "architecture-review";
 function quickstart(runner, args) {
     const appId = String(args.appId || args.app || args.workflowId || exports.QUICKSTART_DEFAULT_APP);
     const agentConfigured = Boolean((0, agent_config_1.resolveAgentConfig)(args).command || (0, agent_config_1.resolveAgentConfig)(args).endpoint);
+    if (isTrue(args.check))
+        return quickstartCheck(runner, appId, args, agentConfigured);
     // `--resume`: a discoverability flag over the existing continuation. With no
     // `--run`, advance exactly ONE step (reuse the `--once` path) and print a
     // copy-pasteable continue line; with `--run <id>`, continue that run to
@@ -623,7 +625,7 @@ function quickstart(runner, args) {
     }
     else if (result.status === "in-progress") {
         hint = resume
-            ? `one step advanced — continue: cw quickstart ${appId} --run ${result.runId} --resume`
+            ? `one step advanced — continue: cw quickstart ${appId} --run ${result.runId} --resume${wantsBundle ? " --bundle" : ""}`
             : `one step advanced (--once) — continue: cw quickstart ${appId} --run ${result.runId} --once`;
     }
     // --bundle on a run that didn't complete is a NO-OP, not silence: tell the operator
@@ -655,6 +657,132 @@ function quickstart(runner, args) {
         ...(bundle ? { bundle } : {})
     };
 }
+function quickstartCheck(runner, appId, args, agentConfigured) {
+    const base = invocationCwd(args);
+    const repoArg = optionalString(args.repo) || base;
+    const repo = node_path_1.default.resolve(base, repoArg);
+    const checks = [];
+    try {
+        runner.showApp(appId);
+        checks.push({ name: "app", status: "ok", detail: `Workflow app ${appId} is available.` });
+    }
+    catch (error) {
+        checks.push({
+            name: "app",
+            status: "blocked",
+            detail: `Workflow app ${appId} is not available.`,
+            fix: "Run `cw app list` and choose one of the listed app ids."
+        });
+    }
+    let repoReadable = false;
+    let repoStateWritable = false;
+    try {
+        const stat = node_fs_1.default.statSync(repo);
+        repoReadable = stat.isDirectory();
+        if (!repoReadable)
+            throw new Error("not a directory");
+        node_fs_1.default.accessSync(repo, node_fs_1.default.constants.R_OK);
+        checks.push({ name: "repo", status: "ok", detail: `Repository path is readable (${repo}).` });
+    }
+    catch (error) {
+        checks.push({
+            name: "repo",
+            status: "blocked",
+            detail: `Repository path is not readable (${repo}).`,
+            fix: "Pass --repo PATH for a readable repository directory."
+        });
+    }
+    try {
+        const cwDir = node_path_1.default.join(repo, ".cw");
+        node_fs_1.default.accessSync(node_fs_1.default.existsSync(cwDir) ? cwDir : repo, node_fs_1.default.constants.W_OK);
+        repoStateWritable = repoReadable;
+        checks.push({ name: "repo-state", status: "ok", detail: "Run state location is writable." });
+    }
+    catch (error) {
+        checks.push({
+            name: "repo-state",
+            status: "blocked",
+            detail: "Run state location is not writable.",
+            fix: "Use a writable repo, fix directory permissions, or pass --repo to a writable checkout."
+        });
+    }
+    if (optionalString(args.question)) {
+        checks.push({ name: "question", status: "ok", detail: "Question is set." });
+    }
+    else {
+        checks.push({
+            name: "question",
+            status: "blocked",
+            detail: "Question is missing.",
+            fix: "Pass --question TEXT."
+        });
+    }
+    if (agentConfigured) {
+        checks.push({ name: "agent", status: "ok", detail: "Agent backend is configured." });
+    }
+    else {
+        checks.push({
+            name: "agent",
+            status: "blocked",
+            detail: "No agent backend is configured.",
+            fix: "Pass --agent-command \"claude -p\", set $CW_AGENT_COMMAND, or use --agent-command builtin:claude."
+        });
+    }
+    if (flag(args.bundle) === true) {
+        const trustKey = optionalString(args["with-trust-key"] || args.withTrustKey || args.trustKey || args.pubkey) || process.env.CW_AGENT_ATTEST_PUBKEY;
+        if (trustKey) {
+            checks.push({ name: "bundle-trust-key", status: "ok", detail: "Bundle trust public key is configured." });
+        }
+        else if (Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs)) {
+            checks.push({
+                name: "bundle-trust-key",
+                status: "blocked",
+                detail: "Strict signature verification needs a public trust key.",
+                fix: "Pass --with-trust-key PATH or set $CW_AGENT_ATTEST_PUBKEY."
+            });
+        }
+        else {
+            checks.push({
+                name: "bundle-trust-key",
+                status: "warn",
+                detail: "No public trust key is configured; unsigned or unkeyed bundles may verify with reduced signature proof.",
+                fix: "Pass --with-trust-key PATH to embed the public key."
+            });
+        }
+    }
+    const ok = checks.every((check) => check.status !== "blocked") && repoStateWritable;
+    return {
+        schemaVersion: 1,
+        mode: "check",
+        ok,
+        appId,
+        repo,
+        checks,
+        nextCommand: quickstartNextCommand(appId, repo, args)
+    };
+}
+function quickstartNextCommand(appId, repo, args) {
+    const parts = ["cw", "quickstart", shellWord(appId), "--repo", shellWord(repo)];
+    const question = optionalString(args.question);
+    if (question)
+        parts.push("--question", shellWord(question));
+    const command = optionalString(args.agentCommand || args["agent-command"]);
+    if (command)
+        parts.push("--agent-command", shellWord(command));
+    if (flag(args.bundle) === true)
+        parts.push("--bundle");
+    const trustKey = optionalString(args["with-trust-key"] || args.withTrustKey || args.trustKey);
+    if (trustKey)
+        parts.push("--with-trust-key", shellWord(trustKey));
+    if (Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs))
+        parts.push("--strict-signatures");
+    return parts.join(" ");
+}
+function shellWord(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
 /** Read-only, deterministic projection of the effective agent config (secret-stripped). */
 function backendAgentConfigShow(args) {
     return (0, agent_config_1.agentConfigShow)(args);

package/dist/capability-registry.js

@@ -31,11 +31,13 @@ exports.mcpCapabilityForId = mcpCapabilityForId;
 exports.mcpRequiredArgsForTool = mcpRequiredArgsForTool;
 exports.mcpToolDefinition = mcpToolDefinition;
 exports.declaredCliTokens = declaredCliTokens;
+exports.declaredCliHelpTokens = declaredCliHelpTokens;
 exports.requiresReason = requiresReason;
 exports.isPayloadProbeOptOut = isPayloadProbeOptOut;
 exports.payloadIdenticalCapabilities = payloadIdenticalCapabilities;
 exports.payloadProbeTargets = payloadProbeTargets;
 exports.deferredPayloadProbeCapabilities = deferredPayloadProbeCapabilities;
+exports.buildPayloadProbePlan = buildPayloadProbePlan;
 exports.payloadProbePlan = payloadProbePlan;
 exports.buildParityReport = buildParityReport;
 // ---------------------------------------------------------------------------
@@ -351,7 +353,7 @@ const BUILTIN_CAPABILITIES = [
     { capability: "run.drive.step", summary: "Drive a run by delegating each worker to the agent backend (plan->dispatch->fulfill->accept->commit; --once for one step).", entry: "runDrive", surface: "both", cli: { path: ["run", "drive"], caseTokens: ["run", "drive"], jsonMode: "default" }, mcp: { tool: "cw_run_drive_step" }, payloadIdentical: false, reason: "Mutating: advances the run by spawning the external agent per worker and recording attested output — not a read probe. CLI (--drive/--step) and MCP route through the same drive() core." },
     {
         capability: "quickstart",
-        summary: "ONE-COMMAND quickstart: plan(app, default architecture-review) -> run --drive -> report in a single invocation (--preview for a read-only dry run; --bundle [--with-trust-key K] seals a completed run into a self-verified portable bundle).",
+        summary: "ONE-COMMAND quickstart: --check preflights without writes; otherwise plan(app, default architecture-review) -> run --drive -> report in a single invocation (--preview for a read-only dry run; --bundle [--with-trust-key K] seals a completed run into a self-verified portable bundle).",
         entry: "quickstart",
         surface: "cli-only",
         cli: { path: ["quickstart"], caseTokens: ["quickstart", "audit-run"], jsonMode: "default" },
@@ -458,34 +460,63 @@ const RUN_PAYLOAD_PROBE_CAPABILITIES = [
     "gc.plan",
     "gc.verify"
 ];
+const SCENARIO_PAYLOAD_PROBE_CAPABILITIES = [
+    "plan",
+    "app.show",
+    "app.validate",
+    "app.package",
+    "topology.show",
+    "topology.validate",
+    "topology.apply",
+    "topology.summary",
+    "topology.graph",
+    "summary.refresh",
+    "summary.show",
+    "sandbox.show",
+    "sandbox.validate",
+    "sandbox.choose",
+    "sandbox.resolve",
+    "approve",
+    "reject",
+    "comment.add",
+    "handoff",
+    "review.policy",
+    "worker.list",
+    "worker.show",
+    "worker.manifest",
+    "worker.output",
+    "worker.fail",
+    "worker.validate",
+    "candidate.list",
+    "candidate.show",
+    "candidate.register",
+    "candidate.score",
+    "candidate.rank",
+    "candidate.select",
+    "candidate.reject",
+    "feedback.list",
+    "feedback.show",
+    "feedback.collect",
+    "feedback.task",
+    "feedback.resolve",
+    "node.show",
+    "node.snapshot",
+    "node.diff",
+    "node.replay",
+    "node.replay.verify"
+];
 const PAYLOAD_PROBE_DEFERRED_GROUPS = [
     {
         reason: "Not safe for the deterministic bootstrap parity probe yet: this capability needs extra target ids/files, mutates durable state, depends on external state, or needs a dedicated fixture beyond cwd/runId.",
         capabilities: [
             "init",
-            "plan",
             "dispatch",
             "result",
-            "app.show",
-            "app.validate",
             "app.init",
-            "app.package",
             "app.run",
-            "node.show",
-            "node.snapshot",
-            "node.diff",
-            "node.replay",
-            "node.replay.verify",
             "migration.list",
             "migration.check",
             "migration.prove",
-            "topology.show",
-            "topology.validate",
-            "topology.apply",
-            "topology.summary",
-            "topology.graph",
-            "summary.refresh",
-            "summary.show",
             "multi-agent.run",
             "multi-agent.status",
             "multi-agent.step",
@@ -542,30 +573,8 @@ const PAYLOAD_PROBE_DEFERRED_GROUPS = [
             "audit.judge",
             "audit.attest",
             "audit.decision",
-            "sandbox.show",
-            "sandbox.validate",
-            "sandbox.choose",
-            "sandbox.resolve",
             "backend.show",
             "backend.probe",
-            "worker.list",
-            "worker.show",
-            "worker.manifest",
-            "worker.output",
-            "worker.fail",
-            "worker.validate",
-            "candidate.list",
-            "candidate.show",
-            "candidate.register",
-            "candidate.score",
-            "candidate.rank",
-            "candidate.select",
-            "candidate.reject",
-            "feedback.list",
-            "feedback.show",
-            "feedback.collect",
-            "feedback.task",
-            "feedback.resolve",
             "schedule.create",
             "schedule.list",
             "schedule.delete",
@@ -607,12 +616,7 @@ const PAYLOAD_PROBE_DEFERRED_GROUPS = [
             "sched.policy.show",
             "sched.policy.set",
             "telemetry.verify",
-            "history",
-            "approve",
-            "reject",
-            "comment.add",
-            "handoff",
-            "review.policy"
+            "history"
         ]
     }
 ];
@@ -665,6 +669,24 @@ function declaredCliTokens() {
     }
     return [...tokens].sort();
 }
+/** The top-level CLI commands that should be visible in `cw help`. Subcommands
+ *  are intentionally collapsed to their first token; aliases such as audit-run
+ *  stay visible. */
+function declaredCliHelpTokens() {
+    const tokens = new Set();
+    for (const cap of exports.CAPABILITY_REGISTRY) {
+        if (!cap.cli)
+            continue;
+        const subcommandTokens = new Set(cap.cli.path.slice(1));
+        tokens.add(cap.cli.path[0]);
+        for (const token of cap.cli.caseTokens || []) {
+            if (!subcommandTokens.has(token))
+                tokens.add(token);
+        }
+    }
+    tokens.delete("help");
+    return [...tokens].sort();
+}
 /** Whether a descriptor MUST carry a reason (surface-specific or divergent). */
 function requiresReason(cap) {
     if (cap.surface !== "both")
@@ -699,27 +721,31 @@ function payloadIdenticalCapabilities() {
 function payloadProbeTargets() {
     return [
         ...GLOBAL_PAYLOAD_PROBE_CAPABILITIES.map((capability) => ({ capability, kind: "global" })),
-        ...RUN_PAYLOAD_PROBE_CAPABILITIES.map((capability) => ({ capability, kind: "run" }))
+        ...RUN_PAYLOAD_PROBE_CAPABILITIES.map((capability) => ({ capability, kind: "run" })),
+        ...SCENARIO_PAYLOAD_PROBE_CAPABILITIES.map((capability) => ({ capability, kind: "scenario" }))
     ];
 }
 function deferredPayloadProbeCapabilities() {
     return PAYLOAD_PROBE_DEFERRED_GROUPS.flatMap((group) => group.capabilities.map((capability) => ({ capability, reason: group.reason })));
 }
-function payloadProbePlan() {
+function buildPayloadProbePlan(targets, deferred) {
     const candidateIds = new Set(payloadIdenticalCapabilities().map((cap) => cap.capability));
     const counts = new Map();
-    const classified = [...payloadProbeTargets().map((entry) => entry.capability), ...deferredPayloadProbeCapabilities().map((entry) => entry.capability)];
+    const classified = [...targets.map((entry) => entry.capability), ...deferred.map((entry) => entry.capability)];
     for (const capability of classified)
         counts.set(capability, (counts.get(capability) || 0) + 1);
     const classifiedIds = new Set(classified);
     return {
-        targets: payloadProbeTargets(),
-        deferred: deferredPayloadProbeCapabilities(),
+        targets,
+        deferred,
         unclassified: [...candidateIds].filter((capability) => !classifiedIds.has(capability)).sort(),
         duplicateClassifications: [...counts.entries()].filter(([, count]) => count > 1).map(([capability]) => capability).sort(),
         invalidClassifications: [...classifiedIds].filter((capability) => !candidateIds.has(capability)).sort()
     };
 }
+function payloadProbePlan() {
+    return buildPayloadProbePlan(payloadProbeTargets(), deferredPayloadProbeCapabilities());
+}
 function lintRegistry() {
     const issues = [];
     const seenCaps = new Set();
@@ -755,10 +781,14 @@ function buildParityReport(input) {
     const actualTools = new Set(input.mcpTools);
     const declaredTokens = new Set(declaredCliTokens());
     const actualTokens = new Set(input.cliTokens);
+    const declaredHelpTokens = new Set(declaredCliHelpTokens());
+    const actualHelpTokens = new Set(input.helpTokens || []);
     const missingMcpTools = [...declaredTools].filter((tool) => !actualTools.has(tool)).sort();
     const undeclaredMcpTools = [...actualTools].filter((tool) => !declaredTools.has(tool)).sort();
     const missingCliTokens = [...declaredTokens].filter((token) => !actualTokens.has(token)).sort();
     const undeclaredCliTokens = [...actualTokens].filter((token) => !declaredTokens.has(token)).sort();
+    const helpMissingCliTokens = input.helpTokens ? [...declaredHelpTokens].filter((token) => !actualHelpTokens.has(token)).sort() : [];
+    const helpUndeclaredCliTokens = input.helpTokens ? [...actualHelpTokens].filter((token) => !declaredHelpTokens.has(token)).sort() : [];
     const reasonlessExceptions = exports.CAPABILITY_REGISTRY.filter((cap) => requiresReason(cap) && !(cap.reason && cap.reason.trim()))
         .map((cap) => cap.capability)
         .sort();
@@ -768,6 +798,8 @@ function buildParityReport(input) {
         undeclaredMcpTools.length === 0 &&
         missingCliTokens.length === 0 &&
         undeclaredCliTokens.length === 0 &&
+        helpMissingCliTokens.length === 0 &&
+        helpUndeclaredCliTokens.length === 0 &&
         reasonlessExceptions.length === 0 &&
         payloadPlan.unclassified.length === 0 &&
         payloadPlan.duplicateClassifications.length === 0 &&
@@ -780,6 +812,8 @@ function buildParityReport(input) {
         undeclaredMcpTools,
         missingCliTokens,
         undeclaredCliTokens,
+        helpMissingCliTokens,
+        helpUndeclaredCliTokens,
         reasonlessExceptions,
         payloadProbeUnclassified: payloadPlan.unclassified,
         payloadProbeDuplicateClassifications: payloadPlan.duplicateClassifications,

package/dist/cli/command-surface.js

@@ -93,6 +93,9 @@ async function runCli(argv = process.argv.slice(2)) {
             const runId = optionalArg(args.options.run) || optionalArg(args.options.runId);
             const qs = (0, capability_core_1.quickstart)(runner, { ...args.options, ...(appId ? { appId } : {}), ...(runId ? { runId } : {}) });
             printJson(qs);
+            if (qs.mode === "check" && qs.ok === false) {
+                process.exitCode = 1;
+            }
             // Fail closed: if --bundle produced an artifact that does not self-verify, exit
             // non-zero so `cw quickstart ... --bundle && send-to-client` cannot ship a report
             // whose bundle a client could not verify. Mirrors `report bundle`.

package/dist/doctor.js

@@ -25,6 +25,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const agent_config_1 = require("./agent-config");
+const onramp_1 = require("./onramp");
 /** Resolve a bare binary name against $PATH (or accept an explicit path). Returns
  *  the resolved path, or undefined when not found. No spawning. */
 function whichBinary(bin, env) {
@@ -136,7 +137,15 @@ function runDoctor(args = {}, env = process.env, cwd = process.cwd()) {
             ? "ready — all checks passed"
             : `ready, with ${warns} warning${warns === 1 ? "" : "s"}`
         : `${fails} blocking problem${fails === 1 ? "" : "s"} found`;
-    return { schemaVersion: 1, ok, checks, summary };
+    return {
+        schemaVersion: 1,
+        ok,
+        checks,
+        summary,
+        ...((0, onramp_1.optionEnabled)(args.onramp)
+            ? { onramp: (0, onramp_1.buildDoctorOnramp)({ cwd, env, changedFrom: typeof args["changed-from"] === "string" ? args["changed-from"] : undefined }) }
+            : {})
+    };
 }
 /** Human rendering (TTY/default). `--json` callers use the report object directly. */
 function formatDoctorReport(report) {
@@ -149,5 +158,32 @@ function formatDoctorReport(report) {
     }
     lines.push("");
     lines.push(`${report.ok ? "✓" : "✗"} ${report.summary}`);
+    if (report.onramp) {
+        lines.push("");
+        lines.push("Onramp");
+        lines.push(`  ${report.onramp.summary}`);
+        if (report.onramp.recommendedChecks) {
+            lines.push("");
+            lines.push("  Recommended Checks");
+            for (const command of report.onramp.recommendedChecks.commands)
+                lines.push(`    - ${command}`);
+        }
+        if (report.onramp.contract && !report.onramp.contract.ok) {
+            lines.push("");
+            lines.push("  Contract Issues");
+            for (const issue of report.onramp.contract.issues) {
+                lines.push(`    - ${issue.code}: ${issue.detail}`);
+                lines.push(`      fix: ${issue.fix}`);
+            }
+        }
+        for (const section of report.onramp.sections) {
+            lines.push("");
+            lines.push(`  ${section.title}: ${section.summary}`);
+            for (const action of section.actions) {
+                lines.push(`    - ${action.command}`);
+                lines.push(`      ${action.reason}`);
+            }
+        }
+    }
     return lines.join("\n");
 }