omp-conductor 0.16.0 → 0.16.2

package/src/command-manifest.ts

@@ -0,0 +1,471 @@
+import { COMMAND_DETAILS, COMMAND_HELP_TAIL } from "./command-help.ts";
+import { AMEND_AREA_IDS } from "./setup.ts";
+import type { CommandScope } from "./commands/context.ts";
+
+export type CommandCompleter = "project" | "shell" | "area";
+
+export interface CommandFlag {
+  name: string;
+  alias?: string;
+  description: string;
+  takesValue: boolean;
+  completer?: CommandCompleter;
+}
+
+export interface CommandPositional {
+  name: string;
+  completer?: CommandCompleter;
+  variadic?: boolean;
+}
+
+export interface CommandManifestEntry {
+  name: string;
+  description: string;
+  scope: CommandScope;
+  usage: readonly string[];
+  subcommands?: readonly { name: string; description: string }[];
+  flags: readonly CommandFlag[];
+  positionals?: readonly CommandPositional[];
+  /** Long-form operator help, kept on the manifest so generated help cannot drift. */
+  details?: string;
+}
+
+const project = (): CommandFlag => ({
+  name: "--project",
+  description: "target the named configured project",
+  takesValue: true,
+  completer: "project",
+});
+const all = (): CommandFlag => ({
+  name: "--all",
+  description: "target every configured project",
+  takesValue: false,
+});
+const value = (
+  name: string,
+  description: string,
+  completer?: CommandCompleter,
+): CommandFlag => ({ name, description, takesValue: true, completer });
+const toggle = (name: string, description: string, alias?: string): CommandFlag => ({
+  name,
+  alias,
+  description,
+  takesValue: false,
+});
+
+export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
+  {
+    name: "setup",
+    description: "interview, configure the fleet, or install host and graph surfaces",
+    scope: "project",
+    usage: [
+      "setup [area] [--no-ai] [--project NAME]",
+      "setup host [NAME] [--project NAME]",
+      "setup graph [--no-seed] [--print] [--project NAME]",
+    ],
+    details: COMMAND_DETAILS,
+    subcommands: [
+      { name: "host", description: "stage and install the host services" },
+      { name: "graph", description: "install and seed code-graph indexes" },
+    ],
+    flags: [
+      project(),
+      toggle("--no-ai", "ask every question without AI repository probes"),
+      toggle("--no-seed", "enable graph indexing without the initial seed"),
+      toggle("--print", "print the graph install plan without changing anything"),
+    ],
+    positionals: [
+      { name: AMEND_AREA_IDS.join("|"), completer: "area" },
+      { name: "project", completer: "project" },
+    ],
+  },
+  {
+    name: "start",
+    description: "start the installed service or background dispatch daemon",
+    scope: "host",
+    usage: ["start [--port N] [--project NAME]"],
+    flags: [value("--port", "health endpoint port"), project()],
+  },
+  {
+    name: "version",
+    description: "print the installed package version (also --version, -V)",
+    scope: "none",
+    usage: ["--version"],
+    flags: [],
+  },
+  {
+    name: "stop",
+    description: "hold the fleet and stop the dispatch daemon",
+    scope: "fleet",
+    usage: ["stop [--pane] [--project NAME | --all]"],
+    flags: [toggle("--pane", "also stop and pin off pane recovery"), project(), all()],
+  },
+  {
+    name: "restart",
+    description: "drain and restart the shared dispatch daemon",
+    scope: "host",
+    usage: ["restart [--now] [--timeout SECONDS] [--port N] [--project NAME]"],
+    flags: [
+      toggle("--now", "restart immediately without draining workers"),
+      value("--timeout", "maximum drain time in seconds"),
+      value("--port", "health endpoint port"),
+      project(),
+    ],
+  },
+  {
+    name: "upgrade",
+    description: "upgrade all installed conductor surfaces as one transaction",
+    scope: "host",
+    usage: ["upgrade [--to VERSION] [--project NAME]"],
+    flags: [value("--to", "package version to install"), project()],
+  },
+  {
+    name: "upgrade-install",
+    description: "run the detached upgrade transaction",
+    scope: "host",
+    usage: ["upgrade-install --to VERSION [--project NAME]"],
+    flags: [value("--to", "package version to install"), project()],
+  },
+  {
+    name: "upgrade-rollback",
+    description: "restore surfaces from the durable pre-upgrade snapshot",
+    scope: "host",
+    usage: ["upgrade-rollback"],
+    flags: [],
+  },
+  {
+    name: "board",
+    description: "open the live keyboard-driven fleet board",
+    scope: "fleet",
+    usage: ["board [--project NAME] [--json]"],
+    flags: [project(), toggle("--json", "print the stable board JSON shape")],
+  },
+  {
+    name: "dashboard",
+    description: "serve the read-only browser dashboard",
+    scope: "none",
+    usage: ["dashboard [--port N] [--host ADDR]"],
+    flags: [value("--port", "dashboard port"), value("--host", "dashboard bind address")],
+  },
+  {
+    name: "status",
+    description: "print layered fleet and deployment status",
+    scope: "fleet",
+    usage: ["status [--project NAME]"],
+    flags: [project()],
+  },
+  {
+    name: "stats",
+    description: "summarize fleet throughput, failures, spend, and GitHub calls",
+    scope: "project",
+    usage: ["stats [--since 7d|30d|YYYY-MM-DD] [--project NAME] [--json]"],
+    flags: [
+      value("--since", "reporting window start"),
+      project(),
+      toggle("--json", "print the stable stats JSON shape"),
+    ],
+  },
+  {
+    name: "doctor",
+    description: "run read-only deployment health checks",
+    scope: "fleet",
+    usage: ["doctor [--project NAME] [--json] [--probe-telegram]"],
+    flags: [
+      project(),
+      toggle("--json", "print the stable doctor JSON shape"),
+      toggle("--probe-telegram", "send the self-identified Telegram health probe"),
+    ],
+  },
+  {
+    name: "restore-db",
+    description: "restore conductor.db from a safe snapshot",
+    scope: "host",
+    usage: ["restore-db [SNAPSHOT]"],
+    flags: [],
+    positionals: [{ name: "snapshot" }],
+  },
+  {
+    name: "ledger",
+    description: "print conductor verb and daemon decision history",
+    scope: "project",
+    usage: ["ledger [--issue N] [--limit N] [--project NAME]"],
+    flags: [value("--issue", "filter by issue number"), value("--limit", "maximum rows"), project()],
+  },
+  {
+    name: "hold",
+    description: "pause claims and disarm ticks while keeping processes up",
+    scope: "fleet",
+    usage: ["hold [--keep-ticks] [--project NAME | --all]"],
+    flags: [toggle("--keep-ticks", "pause claims without disarming ticks"), project(), all()],
+  },
+  {
+    name: "arm",
+    description: "prove Telegram delivery and arm scheduled ticks",
+    scope: "fleet",
+    usage: ["arm [--project NAME | --all]"],
+    flags: [project(), all()],
+  },
+  {
+    name: "disarm",
+    description: "disarm scheduled ticks without stopping processes",
+    scope: "fleet",
+    usage: ["disarm [--project NAME | --all]"],
+    flags: [project(), all()],
+  },
+  {
+    name: "tail",
+    description: "follow the newest worker run for an issue",
+    scope: "project",
+    usage: ["tail <issue> [--project NAME]"],
+    flags: [project()],
+    positionals: [{ name: "issue" }],
+  },
+  {
+    name: "extend",
+    description: "raise a live or next-attempt worker turn ceiling",
+    scope: "project",
+    usage: ["extend <issue> --turns N [--project NAME]"],
+    flags: [value("--turns", "positive turn ceiling"), project()],
+    positionals: [{ name: "issue" }],
+  },
+  {
+    name: "worker",
+    description: "pause, resume, or stop one worker session",
+    scope: "project",
+    usage: [
+      "worker pause <issue> [--project NAME]",
+      "worker resume <issue> [--project NAME]",
+      "worker stop <issue> --reason TEXT [--project NAME]",
+    ],
+    subcommands: [
+      { name: "pause", description: "park the worker at harness idle" },
+      { name: "resume", description: "resume the parked worker" },
+      { name: "stop", description: "stop the worker with a recorded reason" },
+    ],
+    flags: [value("--reason", "reason for stopping the worker"), project()],
+    positionals: [{ name: "action" }, { name: "issue" }],
+  },
+  {
+    name: "unblock",
+    description: "clear blocked and failed labels so an issue can be claimed again",
+    scope: "project",
+    usage: ["unblock <issue> [--force] [--no-requeue] [--project NAME]"],
+    flags: [
+      toggle("--force", "accept missing salvage and continue"),
+      toggle("--no-requeue", "clear state labels without restoring the queue label"),
+      project(),
+    ],
+    positionals: [{ name: "issue" }],
+  },
+  {
+    name: "unfreeze",
+    description: "clear a repository freeze with a recorded reason",
+    scope: "project",
+    usage: ["unfreeze <repo> [--reason TEXT] [--project NAME]"],
+    flags: [value("--reason", "reason for clearing the freeze"), project()],
+    positionals: [{ name: "repo" }],
+  },
+  {
+    name: "verb",
+    description: "run a gated conductor_* verb as the orchestrator",
+    scope: "project",
+    usage: ["verb <conductor_*> [--project NAME] [--arg k=v ...]"],
+    flags: [project(), value("--arg", "repeatable conductor verb argument")],
+    positionals: [{ name: "conductor-verb" }],
+  },
+  {
+    name: "daemon",
+    description: "run the dispatch loop in the foreground",
+    scope: "host",
+    usage: ["daemon [--once] [--port N] [--project NAME]"],
+    flags: [toggle("--once", "run one tick and exit"), value("--port", "health endpoint port"), project()],
+  },
+  {
+    name: "resume",
+    description: "clear fleet pause and pane recovery pins without arming ticks",
+    scope: "fleet",
+    usage: ["resume [--project NAME | --all]"],
+    flags: [project(), all()],
+  },
+  {
+    name: "brief-upgrade",
+    description: "inspect or migrate the project brief overlay",
+    scope: "project",
+    usage: ["brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]"],
+    flags: [
+      toggle("--migrate", "migrate the owned brief half into POLICY.md"),
+      toggle("--retrofit", "add the ownership cut to an older brief"),
+      toggle("--apply", "write the proposed brief changes"),
+      value("--file", "brief path"),
+      project(),
+    ],
+  },
+  {
+    name: "friction",
+    description: "record a bounded escalation or report-quality observation",
+    scope: "project",
+    usage: [
+      "friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]",
+    ],
+    flags: [value("--detail", "bounded observation detail"), value("--issue", "related issue number"), project()],
+    positionals: [{ name: "category" }],
+  },
+  {
+    name: "event",
+    description: "persist one ordinary material outcome without sending it",
+    scope: "project",
+    usage: [
+      "event record --category NAME --summary TEXT --evidence REF [--occurred-at ISO] [--project NAME]",
+    ],
+    subcommands: [{ name: "record", description: "record a material outcome" }],
+    flags: [
+      value("--category", "short lowercase event category"),
+      value("--summary", "event summary"),
+      value("--evidence", "verifiable evidence reference"),
+      value("--occurred-at", "ISO occurrence timestamp"),
+      project(),
+    ],
+    positionals: [{ name: "action" }],
+  },
+  {
+    name: "report",
+    description: "hand a rendered report to the daemon's durable outbox",
+    scope: "project",
+    usage: [
+      "report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]",
+    ],
+    flags: [
+      value("--text", "rendered report text"),
+      value("--kind", "material, digest, or escalation category"),
+      value("--events", "comma-separated event ledger ids"),
+      value("--notices", "comma-separated notice ledger ids"),
+      project(),
+    ],
+  },
+  {
+    name: "message",
+    description: "deliver one direct message to the project's Telegram topic",
+    scope: "project",
+    usage: ["message --text TEXT [--category CATEGORY] [--blocks TEXT] [--project NAME]"],
+    flags: [
+      value("--text", "message text"),
+      value("--category", "escalation category"),
+      value("--blocks", "what the message blocks"),
+      project(),
+    ],
+  },
+  {
+    name: "decision",
+    description: "record, list, resolve, and withdraw operator decisions",
+    scope: "project",
+    usage: [
+      "decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]",
+      "decision resolve <id> --answer TEXT [--project NAME]",
+      "decision withdraw <id> [--reason TEXT] [--project NAME]",
+      "decision list [--project NAME]",
+    ],
+    subcommands: [
+      { name: "open", description: "record a question for the operator" },
+      { name: "resolve", description: "record the operator's answer" },
+      { name: "withdraw", description: "withdraw an obsolete question" },
+      { name: "list", description: "list open operator decisions" },
+    ],
+    flags: [
+      value("--question", "question for the operator"),
+      value("--blocks", "what the decision blocks"),
+      value("--resolves-when", "automatic resolution condition"),
+      value("--answer", "operator answer"),
+      value("--reason", "withdrawal reason"),
+      project(),
+    ],
+    positionals: [{ name: "action" }, { name: "id" }],
+  },
+  {
+    name: "watch",
+    description: "record or list orchestrator-only conditions and carry notes",
+    scope: "project",
+    usage: [
+      "watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]",
+      "watch list [--project NAME]",
+    ],
+    subcommands: [
+      { name: "add", description: "record a watch" },
+      { name: "list", description: "list open watches" },
+    ],
+    flags: [
+      value("--note", "note carried when the watch resolves"),
+      value("--blocks", "what the watch blocks"),
+      value("--resolves-when", "automatic resolution condition"),
+      project(),
+    ],
+    positionals: [{ name: "action" }],
+  },
+  {
+    name: "intake",
+    description: "capture and groom raw ideas durably",
+    scope: "project",
+    usage: [
+      'intake "<text>" [--project NAME]',
+      "intake list [--project NAME]",
+      "intake dismiss <id> [--project NAME]",
+      "intake groomed <id> --issue <url> [--project NAME]",
+    ],
+    subcommands: [
+      { name: "list", description: "list pending intake items" },
+      { name: "dismiss", description: "dismiss an intake item" },
+      { name: "groomed", description: "link an intake item to its issue" },
+    ],
+    flags: [value("--issue", "groomed issue URL"), project()],
+    positionals: [{ name: "text|action" }, { name: "id" }],
+  },
+  {
+    name: "help",
+    description: "print command usage (also --help, -h)",
+    scope: "none",
+    usage: ["help"],
+    details: COMMAND_HELP_TAIL,
+    flags: [],
+  },
+  {
+    name: "complete",
+    description: "generate shell setup or answer one completion request",
+    scope: "none",
+    usage: ["complete <zsh|bash|fish|powershell>", "complete -- <args...>"],
+    flags: [],
+    positionals: [
+      { name: "shell", completer: "shell" },
+      { name: "args", variadic: true },
+    ],
+  },
+];
+
+export function renderUsage(manifest: readonly CommandManifestEntry[] = COMMAND_MANIFEST): string {
+  const synopsis = manifest.flatMap((command) =>
+    command.usage.map((line) => `  omp-conductor ${line}`),
+  );
+  const width = Math.max(...manifest.map((command) => command.name.length));
+  const commands = manifest.map(
+    (command) => `  ${command.name.padEnd(width)}  ${command.description}`,
+  );
+  const details = manifest.flatMap((command) =>
+    command.details === undefined ? [] : [...command.details.split("\n"), ""],
+  );
+  return [
+    "omp-conductor — dispatch ready issues to omp coding sessions",
+    "",
+    "usage:",
+    ...synopsis,
+    "",
+    "commands:",
+    ...commands,
+    "",
+    "details:",
+    ...details,
+    "recipes:",
+    "  hold              no claims, no tick sends (inspectable)",
+    "  stop              hold + stop dispatch daemon",
+    "  stop --pane       stop + pin conductor-pane recovery off",
+    "  resume            clear pause and pane pin (ticks stay disarmed)",
+    "  resume && arm     clear pause and pane pin, then prove inbound Telegram",
+  ].join("\n");
+}

package/src/commands/complete.ts

@@ -0,0 +1,93 @@
+import { RootCommand, type Complete } from "@bomb.sh/tab";
+import { COMMAND_MANIFEST, type CommandCompleter } from "../command-manifest.ts";
+import { loadConfig } from "../config.ts";
+import { AMEND_AREA_IDS } from "../setup.ts";
+
+export const COMPLETION_SHELLS = ["zsh", "bash", "fish", "powershell"] as const;
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+
+function suggestions(kind: CommandCompleter, complete: Complete): void {
+  try {
+    if (kind === "project") {
+      for (const project of loadConfig().projects) complete(project.name, "configured project");
+      return;
+    }
+    if (kind === "area") {
+      for (const area of AMEND_AREA_IDS) complete(area, "setup area");
+      return;
+    }
+    for (const shell of COMPLETION_SHELLS) complete(shell, "supported shell");
+  } catch {
+    // Completion runs on every TAB press. A missing or invalid config must make
+    // completion empty, never turn an interactive shell into an error surface.
+  }
+}
+
+export function completionRoot(): RootCommand {
+  const root = new RootCommand();
+  for (const entry of COMMAND_MANIFEST) {
+    const command = root.command(entry.name, entry.description);
+    for (const flag of entry.flags) {
+      const name = flag.name.replace(/^--/, "");
+      const alias = flag.alias?.replace(/^-+/, "");
+      const completer = flag.completer;
+      const complete =
+        completer === undefined ? undefined : ((add: Complete) => suggestions(completer, add));
+      if (flag.takesValue) {
+        command.option(name, flag.description, complete ?? (() => undefined), alias);
+      } else if (alias !== undefined) {
+        command.option(name, flag.description, alias);
+      } else {
+        command.option(name, flag.description);
+      }
+    }
+    for (const [index, positional] of (entry.positionals ?? []).entries()) {
+      const subcommands = index === 0 ? entry.subcommands : undefined;
+      command.argument(
+        positional.name,
+        positional.completer === undefined && subcommands === undefined
+          ? undefined
+          : (complete) => {
+              for (const subcommand of subcommands ?? []) {
+                complete(subcommand.name, subcommand.description);
+              }
+              if (positional.completer !== undefined) suggestions(positional.completer, complete);
+            },
+        positional.variadic,
+      );
+    }
+  }
+  return root;
+}
+
+function shellFrom(value: string | undefined): CompletionShell {
+  if ((COMPLETION_SHELLS as readonly string[]).includes(value ?? "")) {
+    return value as CompletionShell;
+  }
+  throw new Error(`complete expects one of: ${COMPLETION_SHELLS.join(", ")}`);
+}
+
+export function printCompletionScript(shell: CompletionShell): void {
+  completionRoot().setup("omp-conductor", "omp-conductor", shell);
+}
+
+export function renderCompletionScript(shell: CompletionShell): string {
+  const lines: string[] = [];
+  const original = console.log;
+  console.log = (...args: unknown[]) => lines.push(args.map(String).join(" "));
+  try {
+    printCompletionScript(shell);
+  } finally {
+    console.log = original;
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function completeCommand(args: string[]): void {
+  if (args[0] === "--") {
+    const request = args[1] === "omp-conductor" ? args.slice(2) : args.slice(1);
+    completionRoot().parse(request);
+    return;
+  }
+  printCompletionScript(shellFrom(args[0]));
+}

package/src/commands/context.ts

@@ -115,6 +115,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   status: "fleet",
   stop: "fleet",
   // none — no project at all
+  complete: "none",
   dashboard: "none",
   help: "none",
   "--help": "none",

package/src/commands/setup.ts

@@ -6,13 +6,18 @@
  * changed from the original bodies.
  */
 
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
 import type { CommandContext } from "./context.ts";
+import type { CompletionShell } from "./complete.ts";
 import { findProject, loadConfig, resolveCaps } from "../config.ts";
 import { AMEND_AREA_IDS, type AmendAreaId } from "../setup.ts";
 import { runGraphInstall, runHostInstall, type InstallOutcome } from "../setup-install.ts";
 import { DEFAULT_PROBES, NO_PROBES, setup } from "../setup-wizard.ts";
 import { telegramStateDir } from "../fleet.ts";
-import { terminalUi } from "../wizard-ui.ts";
+import { terminalUi, type WizardUi } from "../wizard-ui.ts";
 import type { ConductorConfig, ProjectConfig } from "../types.ts";
 
 /**
@@ -63,6 +68,52 @@ export function setupInstallProject(
   return findProject(cfg, projectFlag ?? positionalName);
 }
 
+export async function installShellCompletions(
+  shell: Extract<CompletionShell, "zsh" | "bash">,
+  home: string = homedir(),
+): Promise<{ scriptPath: string; rcPath: string }> {
+  const completionDir = join(home, ".omp", "conductor");
+  mkdirSync(completionDir, { recursive: true });
+  const scriptPath = join(completionDir, `completions.${shell}`);
+  writeFileSync(
+    scriptPath,
+    (await import("./complete.ts")).renderCompletionScript(shell),
+    "utf8",
+  );
+
+  const rcPath = join(home, shell === "zsh" ? ".zshrc" : ".bashrc");
+  const sourceLine =
+    `[ -f ~/.omp/conductor/completions.${shell} ] && ` +
+    `source ~/.omp/conductor/completions.${shell}`;
+  const current = existsSync(rcPath) ? readFileSync(rcPath, "utf8") : "";
+  if (!current.split(/\r?\n/).includes(sourceLine)) {
+    const separator = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+    appendFileSync(rcPath, `${separator}${sourceLine}\n`, "utf8");
+  }
+  return { scriptPath, rcPath };
+}
+
+async function offerCompletionInstall(ui: WizardUi): Promise<void> {
+  const install = await ui.confirm(
+    "Install shell completions?",
+    "Writes a generated completion script and one idempotent source line to your shell rc file.",
+  );
+  if (install !== true) return;
+
+  const detected = basename(process.env.SHELL ?? "");
+  const selected = await ui.select(
+    "Shell",
+    [
+      { label: "zsh", description: "Install through ~/.zshrc" },
+      { label: "bash", description: "Install through ~/.bashrc" },
+    ],
+    { initialIndex: detected === "bash" ? 1 : 0 },
+  );
+  if (selected !== "zsh" && selected !== "bash") return;
+  const installed = await installShellCompletions(selected);
+  ui.notify(`Installed completions at ${installed.scriptPath}; sourced from ${installed.rcPath}.`);
+}
+
 export async function setupCommand(ctx: CommandContext): Promise<void> {
 // Help first, and only in the first trailing position: a help request
 // must never open a UI, read config, probe GitHub or pause dispatch.
@@ -136,7 +187,22 @@ try {
   // is still asked, nothing is proposed. For a host with no omp peer, a
   // private repo no probe can clone, or an operator who would rather type the
   // gates than review a model's reading of their CI.
-  await setup(ui, ctx.projectFlag, area, ctx.argv.includes("--no-ai") ? NO_PROBES : DEFAULT_PROBES);
+  const completed = await setup(
+    ui,
+    ctx.projectFlag,
+    area,
+    ctx.argv.includes("--no-ai") ? NO_PROBES : DEFAULT_PROBES,
+  );
+  if (completed && process.stdin.isTTY && process.stdout.isTTY) {
+    try {
+      await offerCompletionInstall(ui);
+    } catch (err) {
+      ui.notify(
+        `Skipped completion install: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
+  }
 } finally {
   ui.close();
 }