@cleocode/cleo 2026.10.3 → 2026.10.4

package/dist/cli/roadmap-7OOQLXKG.js

@@ -0,0 +1,61 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import {
+  defineCommand
+} from "./chunk-PKKZPOOP.js";
+import {
+  dispatchFromCli
+} from "./chunk-3IOQVUO7.js";
+import "./chunk-AWCQH2W5.js";
+import "./chunk-OGV57L4J.js";
+import "./chunk-ZBISIPCK.js";
+import "./chunk-3ZO3M37V.js";
+import "./chunk-6JSJNYH2.js";
+import "./chunk-QFFQSKRC.js";
+
+// packages/cleo/src/cli/commands/roadmap.ts
+var roadmapCommand = defineCommand({
+  meta: {
+    name: "roadmap",
+    description: "Generate project roadmap from task provenance \u2014 epics grouped by status with progress"
+  },
+  args: {
+    "include-history": {
+      type: "boolean",
+      description: "Include release history from CHANGELOG.md"
+    },
+    "upcoming-only": {
+      type: "boolean",
+      description: "Only show pending/upcoming epics (exclude completed)"
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "query",
+      "admin",
+      "roadmap",
+      {
+        includeHistory: args["include-history"],
+        upcomingOnly: args["upcoming-only"]
+      },
+      { command: "roadmap", operation: "admin.roadmap" }
+    );
+  }
+});
+export {
+  roadmapCommand
+};
+//# sourceMappingURL=roadmap-7OOQLXKG.js.map

package/dist/cli/run-2U5NZV5Z.js

@@ -0,0 +1,211 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import "./chunk-C3B7C43W.js";
+import {
+  defineCommand
+} from "./chunk-PKKZPOOP.js";
+import {
+  cliError,
+  cliOutput
+} from "./chunk-3ZO3M37V.js";
+import "./chunk-6JSJNYH2.js";
+
+// packages/cleo/src/cli/commands/run.ts
+import { constants } from "node:os";
+import {
+  RESOURCE_DEFERRED_CODE,
+  RUN_COMMAND_FAILED_CODE,
+  RUN_DEFERRED_EXIT_CODE
+} from "@cleocode/contracts";
+import {
+  canonicalForClass,
+  isWatchCommand,
+  resolveRunClass
+} from "@cleocode/core/resources/run-admission.js";
+import {
+  runGoverned
+} from "@cleocode/core/resources/run-governed.js";
+import { planHeavyToolEnv } from "@cleocode/core/tasks/heavy-tool-env.js";
+function commandAfterDashes(rawArgs) {
+  const idx = rawArgs.indexOf("--");
+  return idx === -1 ? [] : rawArgs.slice(idx + 1);
+}
+function invalid(message, fix, stderr) {
+  cliError(
+    message,
+    "E_VALIDATION",
+    { name: "E_VALIDATION", fix },
+    { operation: "resources.run" },
+    { stderr }
+  );
+  process.exit(6);
+}
+function runExitCode(r) {
+  if (r.spawnError !== null) return 127;
+  if (r.signal !== null) return 128 + (constants.signals[r.signal] ?? 0);
+  return r.exitCode ?? 1;
+}
+function exitFailed(result, code, passthrough, resources) {
+  const { kind: _kind, ...rest } = result;
+  const data = resources === null ? rest : { ...rest, resources };
+  const message = result.spawnError !== null ? `could not start command: ${result.spawnError}` : `command ${result.signal !== null ? `killed by ${result.signal}` : `exited with ${result.exitCode}`}`;
+  if (passthrough && result.spawnError === null) {
+    process.stderr.write(`[cleo run] ${RUN_COMMAND_FAILED_CODE}: ${message}
+`);
+  } else {
+    cliError(
+      message,
+      RUN_COMMAND_FAILED_CODE,
+      { name: RUN_COMMAND_FAILED_CODE, details: data },
+      { operation: "resources.run" },
+      { stderr: passthrough }
+    );
+  }
+  process.exit(code);
+}
+var runCommand = defineCommand({
+  meta: {
+    name: "run",
+    description: "Run a heavy command (tests, builds, installs) under the machine-wide resource budget: cleo run [--class test|build|full-build] [--wait] [--passthrough] -- <command...>"
+  },
+  args: {
+    class: {
+      type: "string",
+      description: "Resource class: test, build, typecheck, install, scan, full-build, db (default: inferred from the command)"
+    },
+    wait: {
+      type: "boolean",
+      description: "Join the FIFO queue for the class instead of returning E_RESOURCE_DEFERRED",
+      default: false
+    },
+    timeout: {
+      type: "string",
+      description: "With --wait: give up after this many seconds (default 1800)"
+    },
+    passthrough: {
+      type: "boolean",
+      description: "Give the command this process's stdin, stdout and stderr and exit with its code. cleo run then writes nothing to stdout (an explicit ADR-086 exception, like docs fetch --content): its own envelopes go to stderr, and it prints only a deferral (exit 75), an ungoverned run, a pause or a failure",
+      default: false
+    }
+  },
+  async run({ args, rawArgs }) {
+    const passthrough = args.passthrough === true;
+    const argv = commandAfterDashes(rawArgs ?? []);
+    if (argv.length === 0) {
+      invalid(
+        "cleo run needs a command after --",
+        "cleo run --class test -- npx vitest run path/to/file.test.ts",
+        passthrough
+      );
+    }
+    if (args.class === void 0 && isWatchCommand(argv)) {
+      invalid(
+        `cleo run refuses watch/dev/serve commands, which never exit and would hold a resource slot forever: ${argv.join(" ")}`,
+        "Run the watcher directly, without cleo run. If it is a bounded job, say so with --class (cleo run --class test -- <cmd>)",
+        passthrough
+      );
+    }
+    let timeoutMs = 18e5;
+    if (args.timeout !== void 0) {
+      if (!args.wait)
+        invalid("--timeout requires --wait", "cleo run --wait --timeout 600 -- <cmd>", passthrough);
+      const seconds = Number(args.timeout);
+      if (!Number.isFinite(seconds) || seconds <= 0) {
+        invalid(
+          `--timeout must be a positive number of seconds (got '${args.timeout}')`,
+          "--timeout 600",
+          passthrough
+        );
+      }
+      timeoutMs = seconds * 1e3;
+    }
+    let cls;
+    try {
+      cls = resolveRunClass(args.class, argv, process.cwd());
+    } catch (err) {
+      invalid(
+        err instanceof Error ? err.message : String(err),
+        "cleo run --class test -- <cmd>",
+        passthrough
+      );
+    }
+    const notice = (line, level) => {
+      if (passthrough && level === "info") return;
+      process.stderr.write(`[cleo run] ${line}
+`);
+    };
+    const { overlay, resources } = planHeavyToolEnv(canonicalForClass(cls));
+    if (resources !== null) {
+      notice(
+        `planned resources: ${resources.summary}`,
+        resources.clamped.length > 0 || resources.overBudget ? "warn" : "info"
+      );
+    }
+    let result;
+    try {
+      result = await runGoverned({
+        argv,
+        cls,
+        cwd: process.cwd(),
+        env: { ...process.env, ...overlay },
+        sessionId: process.env.CLEO_SESSION_ID ?? process.env.CLAUDE_CODE_SESSION_ID ?? null,
+        wait: Boolean(args.wait),
+        timeoutMs,
+        passthrough,
+        // A terminal on stdin: keep the child in its foreground group.
+        foreground: passthrough && process.stdin.isTTY === true,
+        notice
+      });
+    } catch (err) {
+      cliError(
+        `cleo run failed: ${err instanceof Error ? err.message : String(err)}`,
+        1,
+        { name: "E_GENERAL" },
+        { operation: "resources.run" },
+        { stderr: passthrough }
+      );
+      process.exit(1);
+    }
+    if (result.kind === "deferred") {
+      cliError(
+        `not started: ${result.reason}`,
+        RESOURCE_DEFERRED_CODE,
+        {
+          name: RESOURCE_DEFERRED_CODE,
+          details: result.details,
+          fix: result.fix,
+          alternatives: result.alternatives
+        },
+        { operation: "resources.run" },
+        { stderr: passthrough }
+      );
+      process.exit(RUN_DEFERRED_EXIT_CODE);
+    }
+    const code = runExitCode(result);
+    if (code !== 0) exitFailed(result, code, passthrough, resources);
+    if (passthrough) return;
+    const { kind: _kind, ...data } = result;
+    cliOutput(resources === null ? data : { ...data, resources }, {
+      command: "run",
+      operation: "resources.run"
+    });
+  }
+});
+export {
+  runCommand,
+  runExitCode
+};
+//# sourceMappingURL=run-2U5NZV5Z.js.map

package/dist/cli/safestop-VR4VK56D.js

@@ -0,0 +1,88 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import {
+  negatedFlag
+} from "./chunk-47JYZAMS.js";
+import {
+  defineCommand,
+  showUsage
+} from "./chunk-PKKZPOOP.js";
+import {
+  dispatchFromCli
+} from "./chunk-3IOQVUO7.js";
+import "./chunk-AWCQH2W5.js";
+import "./chunk-OGV57L4J.js";
+import "./chunk-ZBISIPCK.js";
+import "./chunk-3ZO3M37V.js";
+import "./chunk-6JSJNYH2.js";
+import "./chunk-QFFQSKRC.js";
+
+// packages/cleo/src/cli/commands/safestop.ts
+var safestopCommand = defineCommand({
+  meta: {
+    name: "safestop",
+    description: "Graceful shutdown for agents approaching context limits"
+  },
+  args: {
+    reason: {
+      type: "string",
+      description: "Reason for stopping",
+      required: false
+    },
+    commit: {
+      type: "boolean",
+      description: "Commit pending git changes with WIP message",
+      default: false
+    },
+    handoff: {
+      type: "string",
+      description: "Generate handoff document (use - for stdout)"
+    },
+    "no-session-end": {
+      type: "boolean",
+      description: "Update notes but do not end session",
+      default: false
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Show actions without executing",
+      default: false
+    }
+  },
+  async run({ args, cmd }) {
+    if (!args.reason) {
+      await showUsage(cmd);
+      return;
+    }
+    await dispatchFromCli(
+      "mutate",
+      "admin",
+      "safestop",
+      {
+        reason: args.reason,
+        commit: args.commit,
+        handoff: args.handoff,
+        noSessionEnd: negatedFlag(args, "session-end"),
+        dryRun: args["dry-run"]
+      },
+      { command: "safestop", operation: "admin.safestop" }
+    );
+  }
+});
+export {
+  safestopCommand
+};
+//# sourceMappingURL=safestop-VR4VK56D.js.map

package/dist/cli/saga-SEWPIOX2.js

@@ -0,0 +1,285 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import {
+  defineCommand,
+  showUsage
+} from "./chunk-PKKZPOOP.js";
+import {
+  dispatchFromCli,
+  dispatchRaw,
+  handleRawError
+} from "./chunk-3IOQVUO7.js";
+import "./chunk-AWCQH2W5.js";
+import "./chunk-OGV57L4J.js";
+import "./chunk-ZBISIPCK.js";
+import {
+  cliOutput
+} from "./chunk-3ZO3M37V.js";
+import "./chunk-6JSJNYH2.js";
+import "./chunk-QFFQSKRC.js";
+
+// packages/cleo/src/cli/commands/saga.ts
+import { parseAcceptanceCriteria } from "@cleocode/core";
+var createCommand = defineCommand({
+  meta: {
+    name: "create",
+    description: "Create a new Saga (top-level task with type='saga')"
+  },
+  args: {
+    title: {
+      type: "string",
+      description: "Saga title",
+      required: true
+    },
+    description: {
+      type: "string",
+      description: "Saga description",
+      required: false
+    },
+    acceptance: {
+      type: "string",
+      description: 'Pipe-separated acceptance criteria (e.g. "AC1|AC2")',
+      required: false
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Validate and preview the Saga without writing task, relation, or doc rows",
+      required: false
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "mutate",
+      "tasks",
+      "saga.create",
+      {
+        title: args.title,
+        description: args.description,
+        // T9839/gh-409: route through bracket+quote-aware parser so criteria
+        // containing `ENUM (a|b|c)` or quoted unions aren't shredded.
+        acceptance: args.acceptance ? parseAcceptanceCriteria(args.acceptance) : void 0,
+        dryRun: args["dry-run"] === true
+      },
+      { command: "saga", operation: "tasks.saga.create" }
+    );
+  }
+});
+var addCommand = defineCommand({
+  meta: {
+    name: "add",
+    description: "Link a member Epic to a Saga via parent_id containment"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Saga task ID (must have type='saga')",
+      required: true
+    },
+    epicId: {
+      type: "positional",
+      description: "Epic task ID to add as a member",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "mutate",
+      "tasks",
+      "saga.add",
+      { sagaId: args.sagaId, epicId: args.epicId },
+      { command: "saga", operation: "tasks.saga.add" }
+    );
+  }
+});
+var detachCommand = defineCommand({
+  meta: {
+    name: "detach",
+    description: "Remove a Saga member via parent_id containment \u2014 idempotent, audit-logged"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Saga task ID",
+      required: true
+    },
+    memberId: {
+      type: "positional",
+      description: "Member task ID to detach from the Saga",
+      required: true
+    },
+    reason: {
+      type: "string",
+      description: "Human-readable reason recorded in the audit log entry",
+      required: false
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "mutate",
+      "tasks",
+      "saga.detach",
+      { sagaId: args.sagaId, memberId: args.memberId, reason: args.reason },
+      { command: "saga", operation: "tasks.saga.detach" }
+    );
+  }
+});
+var listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List all Sagas"
+  },
+  async run() {
+    await dispatchFromCli("query", "tasks", "saga.list", {}, { command: "saga" });
+  }
+});
+var membersCommand = defineCommand({
+  meta: {
+    name: "members",
+    description: "List all member Epics linked to a Saga via parent_id containment"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Saga task ID",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "query",
+      "tasks",
+      "saga.members",
+      { sagaId: args.sagaId },
+      { command: "saga" }
+    );
+  }
+});
+var repairCommand = defineCommand({
+  meta: {
+    name: "repair",
+    description: "Detach an I5-violating parentId from a Saga. Idempotent."
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Saga task ID (must have type='saga')",
+      required: true
+    }
+  },
+  async run({ args }) {
+    await dispatchFromCli(
+      "mutate",
+      "tasks",
+      "saga.repair",
+      { sagaId: args.sagaId },
+      { command: "saga", operation: "tasks.saga.repair" }
+    );
+  }
+});
+var reconcileCommand = defineCommand({
+  meta: {
+    name: "reconcile",
+    description: "Idempotent cron-safe saga auto-close repair \u2014 re-applies T10116 logic for state changed outside completeTask"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Optional saga task ID. Omit to walk every saga.",
+      required: false
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Report what would happen without mutating rows or writing audit log",
+      required: false
+    }
+  },
+  async run({ args }) {
+    const sagaId = typeof args.sagaId === "string" && args.sagaId.length > 0 ? args.sagaId : void 0;
+    await dispatchFromCli(
+      "mutate",
+      "tasks",
+      "saga.reconcile",
+      { sagaId, dryRun: args["dry-run"] === true },
+      { command: "saga", operation: "tasks.saga.reconcile" }
+    );
+  }
+});
+var rollupCommand = defineCommand({
+  meta: {
+    name: "rollup",
+    description: "Aggregate member Epic statuses: total/done/active/blocked/pending + completionPct"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Saga task ID",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const response = await dispatchRaw("query", "tasks", "saga.rollup", {
+      sagaId: args.sagaId
+    });
+    handleRawError(response, { command: "saga", operation: "tasks.saga.rollup" });
+    cliOutput(response.data ?? {}, { command: "saga", operation: "tasks.saga.rollup" });
+  }
+});
+var nextCommand = defineCommand({
+  meta: {
+    name: "next",
+    description: "Return the next actionable Saga and its ready-frontier task IDs"
+  },
+  args: {
+    sagaId: {
+      type: "positional",
+      description: "Optional saga task ID. Omit to auto-select from canonical order.",
+      required: false
+    }
+  },
+  async run({ args }) {
+    const { sagas, getProjectRoot } = await import("@cleocode/core");
+    const projectRoot = getProjectRoot();
+    const sagaId = typeof args.sagaId === "string" && args.sagaId.length > 0 ? args.sagaId : void 0;
+    const result = await sagas.sagaNext(projectRoot, { sagaId });
+    cliOutput(result.success ? result.data : result, { command: "saga", operation: "saga.next" });
+  }
+});
+var sagaCommand = defineCommand({
+  meta: {
+    name: "saga",
+    description: "Saga management \u2014 above-Epic grouping tier (ADR-073)"
+  },
+  subCommands: {
+    create: createCommand,
+    add: addCommand,
+    detach: detachCommand,
+    list: listCommand,
+    members: membersCommand,
+    rollup: rollupCommand,
+    repair: repairCommand,
+    reconcile: reconcileCommand,
+    next: nextCommand
+  },
+  async run({ cmd, rawArgs }) {
+    const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+    if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
+    await showUsage(cmd);
+  }
+});
+export {
+  sagaCommand
+};
+//# sourceMappingURL=saga-SEWPIOX2.js.map