cool-workflow 0.2.3 → 0.2.5

package/dist/shell/workflow-app-loader.js

@@ -141,14 +141,37 @@ function candidateWorkflowsRoots() {
     roots.push(path.join(process.cwd(), "workflows"));
     return roots;
 }
+/** Whether `candidate` resolves to `root` itself or a real descendant of it
+ *  (not an ancestor, sibling, or anywhere reached only via `..` segments). */
+function isWithinRoot(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
 function findAppDir(appId) {
     for (const root of candidateAppsRoots()) {
         const dir = path.join(root, appId);
+        // appId is caller-controlled (MCP app.run, `cw plan`/`run --drive`, a
+        // sub-workflow's spec.appId). Without this check a traversal id like
+        // "../../../tmp/evil-app" walks path.join right out of every trusted
+        // root and loadWorkflowApp below require()s whatever app.json it finds
+        // there with NO manifest/entrypoint validation — the fast path this
+        // function feeds skips validateWorkflowApp entirely (see loadWorkflowApp).
+        if (!isWithinRoot(root, dir))
+            continue;
         if (fs.existsSync(path.join(dir, "app.json")))
             return dir;
     }
     return undefined;
 }
+/** Every root candidateAppsRoots()/candidateWorkflowsRoots() would search:
+ *  bundled apps/workflows, an installed package's apps/workflows, an
+ *  operator-set CW_APPS_DIR/CW_WORKFLOWS_DIR, and the caller's cwd/apps +
+ *  cwd/workflows (the "cw app init" default — must stay unwarned, it is
+ *  the normal flow for a user's own local apps). */
+function isTrustedAppSourcePath(resolvedPath) {
+    const roots = [...candidateAppsRoots(), ...candidateWorkflowsRoots()];
+    return roots.some((root) => isWithinRoot(path.resolve(root), resolvedPath));
+}
 function validationContext() {
     return { bundledSandboxProfileIds: (0, sandbox_profile_1.bundledSandboxProfileIds)(), currentCoolWorkflowVersion: version_1.CURRENT_COOL_WORKFLOW_VERSION };
 }
@@ -451,6 +474,31 @@ function loadWorkflowAppRecordTarget(target) {
         throw new Error("Missing workflow app path or id");
     const resolved = path.resolve(target);
     if (fs.existsSync(resolved)) {
+        // `validate`/`show` on a real path is the one loader entrypoint whose
+        // whole point is to let a caller inspect an app BEFORE deciding to
+        // trust it — but inspecting it means require()-ing its workflow.js
+        // (validateWorkflowApp needs the returned WorkflowDefinition, which
+        // only exists after the factory runs). A path outside every root CW
+        // already trusts (bundled apps, an installed package, CW_APPS_DIR, or
+        // the caller's own cwd/apps from `cw app init`) gets arbitrary code
+        // executed by "validate", with no OS-level containment — a warning
+        // printed after that require() call would be too late to matter, so
+        // this fails closed instead: refuse by default, and only proceed
+        // (still with a visible warning) when the caller explicitly opts in.
+        // Mirrors the existing --allow-unattested precedent in
+        // worker-isolation.ts: unsafe-but-explicit, never silent.
+        if (!isTrustedAppSourcePath(resolved)) {
+            if (!process.env.CW_ALLOW_EXTERNAL_APP_CODE) {
+                throw new app_schema_1.WorkflowAppValidationError("Untrusted workflow app source", [
+                    {
+                        code: "workflow-app-untrusted-source",
+                        message: `Refusing to load workflow app code outside CW's trusted app roots: ${resolved}. Its workflow.js would run as ordinary Node.js code with full host privileges — CW does not sandbox app code, only delegated agent workers. Set CW_ALLOW_EXTERNAL_APP_CODE=1 to load and execute it anyway.`,
+                        path: resolved,
+                    },
+                ]);
+            }
+            process.stderr.write(`cw: loading external workflow app code from ${resolved} — its workflow.js runs as ordinary Node.js code with full host privileges, not sandboxed.\n`);
+        }
         const stat = fs.statSync(resolved);
         if (stat.isDirectory())
             return loadWorkflowAppFromManifest(path.join(resolved, "app.json"));
@@ -593,6 +641,24 @@ function renderManifestTemplate(id, title) {
 function renderEntrypointTemplate(id, title) {
     return `module.exports = ({ workflow, phase, agent, artifact, input }) => {\n  const inputs = [\n    input("question", { type: "string", required: true, description: "Question or task this workflow should answer." })\n  ];\n\n  return workflow({\n    id: ${JSON.stringify(id)},\n    title: ${JSON.stringify(title)},\n    summary: "Describe what this workflow app does.",\n    limits: {\n      maxAgents: 8,\n      maxConcurrentAgents: 4\n    },\n    inputs,\n    sandboxProfiles: ["readonly"],\n    phases: [\n      phase("Map", [\n        agent("map:context", "Map the task context, constraints, and evidence needed for {{question}}.", { sandboxProfileId: "readonly" })\n      ]),\n      phase("Assess", [\n        agent("assess:risks", "Assess risks, tradeoffs, and unknowns for {{question}}.", { sandboxProfileId: "readonly" })\n      ]),\n      phase("Synthesize", [\n        artifact("synthesis:report", "Synthesize the final answer for {{question}}.", { requiresEvidence: true, sandboxProfileId: "readonly" })\n      ])\n    ]\n  });\n};\n`;
 }
+/** Validates a manifest CW itself just wrote to disk (from `initWorkflowApp`
+ *  below) — deliberately bypasses `loadWorkflowAppRecordTarget`'s
+ *  untrusted-source gate. That gate exists for `cw app validate <path>`,
+ *  where the caller is inspecting code someone else wrote before deciding
+ *  whether to trust it; `app init --directory <anywhere>` is the opposite
+ *  case (the caller is authoring new code, from CW's own template, in a
+ *  location they chose on purpose) and must keep working regardless of
+ *  where `--directory` points. */
+function validateGeneratedManifest(manifestPath) {
+    try {
+        const record = loadWorkflowAppFromManifest(manifestPath);
+        const result = (0, app_schema_1.validateWorkflowApp)(record.app, validationContext(), { appPath: sourcePathOf(record) });
+        return { ...result, summary: summarizeWorkflowAppRecord(record) };
+    }
+    catch (error) {
+        return { valid: false, appId: manifestPath, appPath: path.resolve(manifestPath), issues: (0, app_schema_1.validationIssuesFromError)(error) };
+    }
+}
 /** `cw app init <id>` / `cw_app_init`. Writes `app.json` + `workflow.js`
  *  from the templates, refusing system directories and (without
  *  `--force`) an existing app. Ported from `initApp`. */
@@ -614,7 +680,7 @@ function initWorkflowApp(appId, options = {}) {
     fs.mkdirSync(destinationDir, { recursive: true });
     fs.writeFileSync(manifestPath, renderManifestTemplate(id, title), "utf8");
     fs.writeFileSync(entrypointPath, renderEntrypointTemplate(id, title), "utf8");
-    const validation = validateWorkflowAppTarget(manifestPath);
+    const validation = validateGeneratedManifest(manifestPath);
     if (!validation.valid) {
         throw new app_schema_1.WorkflowAppValidationError("Generated workflow app is invalid", validation.issues);
     }

package/dist/wiring/capability-table/basics.js

@@ -18,7 +18,7 @@ const registry_core_1 = require("./registry-core");
 const version_1 = require("../../core/version");
 const help_1 = require("../../core/format/help");
 const completion_1 = require("../../core/format/completion");
-const io_1 = require("../../cli/io");
+const cli_args_1 = require("../../core/util/cli-args");
 // This whole module is required unconditionally at startup for EVERY
 // command (see wiring/capability-table/index.ts) — a top-level import of
 // `shell/workflow-app-loader` here means even `cw --version` pays its
@@ -38,7 +38,7 @@ function loadWorkflowAppLoader() {
     path: ["completion"],
     jsonMode: "human",
     handler: (args) => {
-        const shell = (0, io_1.optionalArg)(args.positionals[0]);
+        const shell = (0, cli_args_1.optionalArg)(args.positionals[0]);
         if (!shell)
             throw new Error('Missing shell name.\n  Try: cw completion bash|zsh|fish');
         return { text: (0, completion_1.formatCompletionScript)(shell) };
@@ -78,6 +78,11 @@ function loadWorkflowAppLoader() {
     path: ["list"],
     jsonMode: "default",
     handler: () => ({ json: (0, registry_core_1.listBundledWorkflows)() }),
+    // UI/UX fix: a person at a real terminal used to get the raw JSON array.
+    // On a TTY (and only there — piped bytes stay the exact same JSON, see
+    // cli/dispatch.ts's shouldRenderHuman) render one "<id> — <title>" line
+    // per workflow plus the next-step footer.
+    humanRender: help_1.formatWorkflowList,
 });
 (0, registry_core_1.attachCliBinding)("status", {
     path: ["status"],

package/dist/wiring/capability-table/exec-backend.js

@@ -16,23 +16,26 @@ const registry_core_1 = require("./registry-core");
 // their milestone-2 placeholder `mcp.handler` with the real body, exactly
 // as milestones 3/4 did for their own rows.
 // ---------------------------------------------------------------------
-const exec_backend_cli_1 = require("../../shell/exec-backend-cli");
-const io_1 = require("../../cli/io");
-// This slice is required unconditionally at startup for every command;
-// load doctor/app-run-cli lazily so only doctor/fix/sandbox.choose/
-// sandbox.resolve/app.run handlers pay their require cost.
+const cli_args_1 = require("../../core/util/cli-args");
+// This slice is required unconditionally at startup for every command; every
+// shell import below is lazy (require()'d only inside the handler that
+// actually uses it), so a command that never touches doctor/fix/sandbox/
+// backend/app.run never pays any of these shell modules' require cost.
 function loadDoctor() {
     return require("../../shell/doctor");
 }
 function loadAppRunCli() {
     return require("../../shell/app-run-cli");
 }
+function loadExecBackendCli() {
+    return require("../../shell/exec-backend-cli");
+}
 (0, registry_core_1.attachCliBinding)("sandbox.list", {
     path: ["sandbox", "list"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.listSandboxProfilesCli)(args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().listSandboxProfilesCli(args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.list").mcp.handler = (args) => (0, exec_backend_cli_1.listSandboxProfilesCli)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.list").mcp.handler = (args) => loadExecBackendCli().listSandboxProfilesCli(args);
 // GAP #24: cw_sandbox_choose / cw_sandbox_resolve + cw_app_run were declared
 // MCP-only rows with the notYetImplemented placeholder handler. Wire them to
 // the ported shell bodies (both are MCP-only in the old build — no CLI path).
@@ -42,18 +45,18 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("app.run").mcp.handler = (args) => lo
 (0, registry_core_1.attachCliBinding)("sandbox.show", {
     path: ["sandbox", "show"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.showSandboxProfileCli)((0, io_1.required)(args.positionals[0], "profile id"), args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().showSandboxProfileCli((0, cli_args_1.required)(args.positionals[0], "profile id"), args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.show").mcp.handler = (args) => (0, exec_backend_cli_1.showSandboxProfileCli)((0, io_1.required)((0, io_1.optionalArg)(args.profileId), "profile id"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.show").mcp.handler = (args) => loadExecBackendCli().showSandboxProfileCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileId), "profile id"), args);
 (0, registry_core_1.attachCliBinding)("sandbox.validate", {
     path: ["sandbox", "validate"],
     jsonMode: "default",
     handler: (args) => {
-        const result = (0, exec_backend_cli_1.validateSandboxProfileCli)((0, io_1.required)(args.positionals[0], "profile file"), args.options);
+        const result = loadExecBackendCli().validateSandboxProfileCli((0, cli_args_1.required)(args.positionals[0], "profile file"), args.options);
         return { json: result, exitCode: result.valid ? undefined : 1 };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (args) => (0, exec_backend_cli_1.validateSandboxProfileCli)((0, io_1.required)((0, io_1.optionalArg)(args.profileFile), "profile file"), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (args) => loadExecBackendCli().validateSandboxProfileCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.profileFile), "profile file"), args);
 // PARITY: `sandbox.choose`/`sandbox.resolve` are BOTH-surface capabilities
 // per SPEC/mcp.md (old build cli.path ["sandbox","choose"]/["sandbox",
 // "resolve"]) — they were left MCP-only at GAP #24 (see the comment
@@ -74,21 +77,21 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("sandbox.validate").mcp.handler = (ar
 (0, registry_core_1.attachCliBinding)("backend.list", {
     path: ["backend", "list"],
     jsonMode: "default",
-    handler: () => ({ json: (0, exec_backend_cli_1.listBackendsCli)() }),
+    handler: () => ({ json: loadExecBackendCli().listBackendsCli() }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.list").mcp.handler = () => (0, exec_backend_cli_1.listBackendsCli)();
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.list").mcp.handler = () => loadExecBackendCli().listBackendsCli();
 (0, registry_core_1.attachCliBinding)("backend.show", {
     path: ["backend", "show"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.showBackendCli)((0, io_1.required)(args.positionals[0], "backend id")) }),
+    handler: (args) => ({ json: loadExecBackendCli().showBackendCli((0, cli_args_1.required)(args.positionals[0], "backend id")) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.show").mcp.handler = (args) => (0, exec_backend_cli_1.showBackendCli)((0, io_1.required)((0, io_1.optionalArg)(args.backendId), "backend id"));
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.show").mcp.handler = (args) => loadExecBackendCli().showBackendCli((0, cli_args_1.required)((0, cli_args_1.optionalArg)(args.backendId), "backend id"));
 (0, registry_core_1.attachCliBinding)("backend.probe", {
     path: ["backend", "probe"],
     jsonMode: "default",
-    handler: (args) => ({ json: (0, exec_backend_cli_1.probeBackendCli)(args.positionals[0], args.options) }),
+    handler: (args) => ({ json: loadExecBackendCli().probeBackendCli(args.positionals[0], args.options) }),
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args) => (0, exec_backend_cli_1.probeBackendCli)((0, io_1.optionalArg)(args.backendId), args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args) => loadExecBackendCli().probeBackendCli((0, cli_args_1.optionalArg)(args.backendId), args);
 // `backend agent config [show]` = read-only; `backend agent config set
 // ...` = mutating. CLI path is ["backend", "agent"] (2 tokens, matching
 // dispatchTable's supported path lengths); the remaining positionals
@@ -102,8 +105,8 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args)
     handler: (args) => {
         const action = args.positionals[1];
         if (action === "set")
-            return { json: (0, exec_backend_cli_1.backendAgentConfigSet)(args.options) };
-        return { json: (0, exec_backend_cli_1.backendAgentConfigShow)(args.options) };
+            return { json: loadExecBackendCli().backendAgentConfigSet(args.options) };
+        return { json: loadExecBackendCli().backendAgentConfigShow(args.options) };
     },
 });
 // `backend.agent.config.set` shares the SAME dispatch path/handler as
@@ -124,12 +127,12 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.probe").mcp.handler = (args)
     handler: (args) => {
         const action = args.positionals[1];
         if (action === "set")
-            return { json: (0, exec_backend_cli_1.backendAgentConfigSet)(args.options) };
-        return { json: (0, exec_backend_cli_1.backendAgentConfigShow)(args.options) };
+            return { json: loadExecBackendCli().backendAgentConfigSet(args.options) };
+        return { json: loadExecBackendCli().backendAgentConfigShow(args.options) };
     },
 });
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.show").mcp.handler = (args) => (0, exec_backend_cli_1.backendAgentConfigShow)(args);
-registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").mcp.handler = (args) => (0, exec_backend_cli_1.backendAgentConfigSet)(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.show").mcp.handler = (args) => loadExecBackendCli().backendAgentConfigShow(args);
+registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").mcp.handler = (args) => loadExecBackendCli().backendAgentConfigSet(args);
 // PARITY: `backend.agent.config.set` mutates $CW_HOME/agent-config.json
 // (secret-stripped) before returning the effective config; both surfaces
 // perform the same write, so it is a documented opt-out from the
@@ -151,9 +154,24 @@ registry_core_1.REGISTRY_BY_CAPABILITY.get("backend.agent.config.set").reason =
         // renderer only appends "\n" when the text does NOT already end in
         // one, so a bare `formatDoctorFixes(report)` here would silently
         // drop the old build's trailing blank line.
-        const text = (0, io_1.wantsJson)(args.options) ? undefined : args.options.fix ? `${doctor.formatDoctorFixes(report)}\n` : doctor.formatDoctorReport(report);
+        const text = (0, cli_args_1.wantsJson)(args.options) ? undefined : args.options.fix ? `${doctor.formatDoctorFixes(report)}\n` : doctor.formatDoctorReport(report);
         return { json: report, text, exitCode: report.ok ? undefined : 1 };
     },
+    // UI/UX fix: `cw help doctor` used to list only the one-line summary
+    // above, so a first-run user had no way to learn these flags without
+    // reading source. Real flag names verified against this handler and
+    // the `runDoctor(args.options, ...)` call it makes (shell/doctor.ts).
+    flags: [
+        { name: "--onramp", summary: "Run the extra onramp checks (3-step quick start)." },
+        { name: "--fix", summary: "Print fix commands instead of the full report." },
+        { name: "--changed-from REF", summary: "Check the onramp only for the change since REF." },
+        { name: "--json", summary: "Print the report as JSON." },
+    ],
+    // The handler above and runDoctor (shell/doctor.ts) read exactly
+    // onramp/fix/changed-from/json plus the shared globals (cwd, format)
+    // — the list above is complete, so the dispatcher may warn about an
+    // unknown flag (TTY-only; see cli/global-flags.ts).
+    flagsComplete: true,
 }, "Environment diagnostics are inherently local to the CLI host — Node version, $PATH, $CW_HOME/cwd writability. An MCP client diagnosing the server process's environment is not meaningful; agents already receive the same readiness facts in their typed results (e.g. status: blocked, agentConfigured). Inspired by `brew doctor`.");
 (0, registry_core_1.addCliOnlyCapability)("fix", "Print consolidated fix commands for CW setup issues.", {
     path: ["fix"],