@bastani/atomic 0.6.4 → 0.6.5-0

package/src/commands/cli/workflow.ts

@@ -1,16 +1,196 @@
 /**
- * Workflow CLI command — thin delegation to the SDK WorkflowCli.
+ * `atomic workflow` command — built directly on the SDK's primitives.
  *
- * The Command returned here is mounted directly into the parent program
- * (src/cli.ts), which attaches the `list`, `inputs`, `status`, and
- * `session` subcommands on top of it.
+ * Produces a Commander `Command` with the same UX as the previous
+ * `createWorkflowCli`-driven implementation:
+ *   - `-n/--name <name>` selects the workflow
+ *   - `-a/--agent <agent>` selects the agent backend
+ *   - `-d/--detach` runs in the background
+ *   - one `--<input>` flag per declared input across the registry (with
+ *     reserved-name and type-conflict checks via `buildInputUnion`)
+ *   - `[prompt...]` positional for free-form workflows
+ *   - interactive picker when `-a` is given without `-n` in a TTY
+ *
+ * The exported Command is mounted as a subcommand of the root atomic
+ * program (see `src/cli.ts`), which then attaches `list`, `inputs`,
+ * `status`, and `session` siblings on top of it.
+ */
+
+import { Command } from "@commander-js/extra-typings";
+import {
+  type AgentType,
+  type WorkflowDefinition,
+  type WorkflowInput,
+  getInputSchema,
+  listWorkflows,
+  runWorkflow,
+} from "../../sdk/index.ts";
+import { buildInputUnion, toCamelCase } from "../../sdk/worker-shared.ts";
+import { createBuiltinRegistry } from "../builtin-registry.ts";
+import { WorkflowPickerPanel } from "../../sdk/components/workflow-picker-panel.tsx";
+
+const VALID_AGENTS: readonly AgentType[] = ["claude", "opencode", "copilot"];
+
+/** Resolve a workflow against the builtin registry, throwing with a usable hint. */
+function resolveWorkflow(
+  registry: ReturnType<typeof createBuiltinRegistry>,
+  name: string,
+  agent: AgentType,
+): WorkflowDefinition {
+  const def = registry.resolve(name, agent);
+  if (def) return def;
+  const sameName = listWorkflows(registry)
+    .filter((w) => w.name === name)
+    .map((w) => w.agent);
+  const hint =
+    sameName.length > 0
+      ? `available agents for "${name}": ${sameName.join(", ")}`
+      : `no workflow named "${name}" in registry`;
+  throw new Error(
+    `[atomic/workflow] no workflow named "${name}" for agent "${agent}"; ${hint}`,
+  );
+}
+
+/** Run a resolved workflow with merged inputs. */
+async function dispatch(
+  workflow: WorkflowDefinition,
+  cliInputs: Record<string, string>,
+  detach: boolean,
+): Promise<void> {
+  await runWorkflow({
+    workflow,
+    inputs: cliInputs,
+    detach,
+  });
+}
+
+/**
+ * Drive the interactive picker. The picker reads its registry directly
+ * (filtered by agent) and returns the chosen workflow + populated input
+ * map; we then hand off to `runWorkflow`.
  */
+async function runPicker(
+  registry: ReturnType<typeof createBuiltinRegistry>,
+  agent: AgentType,
+  detach: boolean,
+): Promise<void> {
+  const panel = await WorkflowPickerPanel.create({ agent, registry });
+  const result = await panel.waitForSelection();
+  panel.destroy();
+  if (!result) {
+    process.stdout.write("No workflow selected.\n");
+    return;
+  }
+  await dispatch(result.workflow, result.inputs, detach);
+}
+
+/**
+ * Build the workflow command tree. Exported so third-party CLIs (and
+ * tests) can reuse the dispatcher with their own registries.
+ *
+ * @param registry workflow registry to drive the dispatcher; defaults
+ *   to the atomic CLI's builtin registry.
+ */
+export function buildWorkflowCommand(
+  registry: ReturnType<typeof createBuiltinRegistry> = createBuiltinRegistry(),
+): Command {
+  const all = listWorkflows(registry);
+  const allNames = [...new Set(all.map((w) => w.name))];
+  // buildInputUnion enforces the reserved-name and type-conflict checks
+  // the SDK previously ran inside createWorkflowCli.
+  const unionInputs: Map<string, WorkflowInput> = buildInputUnion(all);
+
+  const cmd = new Command("workflow");
+
+  // Subcommands declare their own `-a`; without enablePositionalOptions
+  // the parent would greedily bind the flag.
+  cmd.enablePositionalOptions();
+
+  cmd.option("-n, --name <name>", "Workflow name", (v) => {
+    if (allNames.length > 0 && !allNames.includes(v)) {
+      throw new Error(
+        `[atomic/workflow] Unknown workflow name "${v}". ` +
+          `Available: ${allNames.join(", ")}.`,
+      );
+    }
+    return v;
+  });
+
+  cmd.option(
+    "-a, --agent <agent>",
+    "Agent (claude | opencode | copilot)",
+    (v) => {
+      if (!(VALID_AGENTS as readonly string[]).includes(v)) {
+        throw new Error(
+          `[atomic/workflow] Unknown agent "${v}". ` +
+            `Valid agents: ${VALID_AGENTS.join(", ")}.`,
+        );
+      }
+      return v as AgentType;
+    },
+  );
+
+  for (const [, input] of unionInputs) {
+    const desc =
+      input.description ??
+      (input.type === "enum"
+        ? `one of: ${(input.values ?? []).join(", ")}`
+        : input.type);
+    cmd.option(`--${input.name} <value>`, desc);
+  }
+
+  cmd.option("-d, --detach", "Run workflow in background (detach from tmux)");
+
+  cmd.argument("[prompt...]", "Free-form prompt (joined, stored as inputs.prompt)");
+
+  cmd.allowUnknownOption(false);
+  cmd.allowExcessArguments(true);
+
+  cmd.action(async function (this: Command) {
+    const options = this.opts() as Record<string, string | boolean | undefined>;
+    const promptTokens: string[] = this.args;
+
+    const name = options["name"] as string | undefined;
+    const agent = options["agent"] as AgentType | undefined;
+    const detach = options["detach"] === true;
+
+    const cliInputs: Record<string, string> = {};
+    for (const [inputName] of unionInputs) {
+      const camelKey = toCamelCase(inputName);
+      const v = options[camelKey];
+      if (typeof v === "string" && v !== "") {
+        cliInputs[inputName] = v;
+      }
+    }
+
+    // Free-form workflows: collapse the trailing positional args into
+    // `inputs.prompt` so workflow authors can keep reading
+    // `ctx.inputs.prompt` regardless of declared schema.
+    const promptStr = promptTokens.join(" ");
+    if (promptStr !== "" && name) {
+      const def = registry.resolve(name, agent as AgentType);
+      if (def && getInputSchema(def).length === 0) {
+        cliInputs["prompt"] = promptStr;
+      }
+    }
+
+    if (!name && agent && process.stdout.isTTY) {
+      await runPicker(registry, agent, detach);
+      return;
+    }
+
+    if (name === undefined || agent === undefined) {
+      // help() exits the process; the explicit `return` keeps narrowing
+      // happy for the lines below.
+      cmd.help();
+      return;
+    }
+
+    const workflow = resolveWorkflow(registry, name, agent);
+    await dispatch(workflow, cliInputs, detach);
+  });
 
-import { createWorkflowCli } from "../../sdk/workflow-cli.ts";
-import { toCommand } from "../../sdk/commander.ts";
-import { createBuiltinRegistry } from "../../sdk/workflows/builtin-registry.ts";
+  return cmd;
+}
 
-export const workflowCommand = toCommand(
-  createWorkflowCli(createBuiltinRegistry()),
-  "workflow",
-);
+export const workflowCommand = buildWorkflowCommand();

package/src/sdk/define-workflow.test.ts

@@ -4,41 +4,60 @@ import type { WorkflowInput } from "./types.ts";
 
 describe("defineWorkflow", () => {
   test("returns a WorkflowBuilder", () => {
-    const builder = defineWorkflow({ name: "test" });
+    const builder = defineWorkflow({ name: "test", source: import.meta.path });
     expect(builder).toBeInstanceOf(WorkflowBuilder);
     expect(builder.__brand).toBe("WorkflowBuilder");
   });
 
   test("throws on empty name", () => {
-    expect(() => defineWorkflow({ name: "" })).toThrow("Workflow name is required");
+    expect(() => defineWorkflow({ name: "", source: import.meta.path })).toThrow("Workflow name is required");
   });
 
   test("throws on whitespace-only name", () => {
-    expect(() => defineWorkflow({ name: "   " })).toThrow("Workflow name is required");
+    expect(() => defineWorkflow({ name: "   ", source: import.meta.path })).toThrow("Workflow name is required");
+  });
+
+  test("throws on missing source at compile()", () => {
+    expect(() =>
+      // Cast required because the type requires `source`; this exercises the
+      // runtime guard for users who silence the type error.
+      defineWorkflow({ name: "no-source" } as unknown as { name: string; source: string })
+        .for("copilot")
+        .run(async () => {})
+        .compile(),
+    ).toThrow(/missing the `source` option/);
+  });
+
+  test("propagates source onto the compiled definition", () => {
+    const def = defineWorkflow({ name: "with-src", source: import.meta.path })
+      .for("copilot")
+      .run(async () => {})
+      .compile();
+    expect(def.source).toBe(import.meta.path);
   });
 });
 
 describe("WorkflowBuilder.run()", () => {
   test("accepts a function and returns this for chaining", () => {
-    const builder = defineWorkflow({ name: "test" });
+    const builder = defineWorkflow({ name: "test", source: import.meta.path });
     const result = builder.run(async () => {});
     expect(result).toBe(builder);
   });
 
   test("throws if called twice", () => {
-    const builder = defineWorkflow({ name: "test" }).run(async () => {});
+    const builder = defineWorkflow({ name: "test", source: import.meta.path }).run(async () => {});
     expect(() => builder.run(async () => {})).toThrow("run() can only be called once");
   });
 
   test("throws if argument is not a function", () => {
-    const builder = defineWorkflow({ name: "test" });
+    const builder = defineWorkflow({ name: "test", source: import.meta.path });
     expect(() => builder.run("not a function" as never)).toThrow("run() requires a function");
   });
 });
 
 describe("WorkflowBuilder.compile()", () => {
   test("produces a WorkflowDefinition with correct brand", () => {
-    const def = defineWorkflow({ name: "test" })
+    const def = defineWorkflow({ name: "test", source: import.meta.path })
       .for("copilot")
       .run(async () => {})
       .compile();
@@ -46,7 +65,7 @@ describe("WorkflowBuilder.compile()", () => {
   });
 
   test("defaults inputs to an empty array when none are declared", () => {
-    const def = defineWorkflow({ name: "test" })
+    const def = defineWorkflow({ name: "test", source: import.meta.path })
       .for("copilot")
       .run(async () => {})
       .compile();
@@ -56,6 +75,7 @@ describe("WorkflowBuilder.compile()", () => {
   test("preserves declared inputs in order", () => {
     const def = defineWorkflow({
       name: "gen-spec",
+      source: import.meta.path,
       inputs: [
         {
           name: "research_doc",
@@ -84,6 +104,7 @@ describe("WorkflowBuilder.compile()", () => {
   test("freezes declared inputs to prevent downstream mutation", () => {
     const def = defineWorkflow({
       name: "test",
+      source: import.meta.path,
       inputs: [{ name: "foo", type: "string" }],
     })
       .for("claude")
@@ -98,6 +119,7 @@ describe("WorkflowBuilder.compile()", () => {
     expect(() =>
       defineWorkflow({
         name: "bad",
+        source: import.meta.path,
         inputs: [{ name: "mode", type: "enum" }],
       })
         .for("copilot")
@@ -110,6 +132,7 @@ describe("WorkflowBuilder.compile()", () => {
     expect(() =>
       defineWorkflow({
         name: "bad",
+        source: import.meta.path,
         inputs: [
           {
             name: "mode",
@@ -129,6 +152,7 @@ describe("WorkflowBuilder.compile()", () => {
     expect(() =>
       defineWorkflow({
         name: "bad",
+        source: import.meta.path,
         inputs: [{ name: "1bad", type: "string" }],
       })
         .for("copilot")
@@ -141,6 +165,7 @@ describe("WorkflowBuilder.compile()", () => {
     expect(() =>
       defineWorkflow({
         name: "bad",
+        source: import.meta.path,
         inputs: [
           { name: "foo", type: "string" },
           { name: "foo", type: "string" },
@@ -153,7 +178,7 @@ describe("WorkflowBuilder.compile()", () => {
   });
 
   test("preserves name, description, and agent", () => {
-    const def = defineWorkflow({ name: "my-wf", description: "A description" })
+    const def = defineWorkflow({ name: "my-wf", description: "A description", source: import.meta.path })
       .for("claude")
       .run(async () => {})
       .compile();
@@ -163,7 +188,7 @@ describe("WorkflowBuilder.compile()", () => {
   });
 
   test("defaults description to empty string", () => {
-    const def = defineWorkflow({ name: "test" })
+    const def = defineWorkflow({ name: "test", source: import.meta.path })
       .for("opencode")
       .run(async () => {})
       .compile();
@@ -172,17 +197,17 @@ describe("WorkflowBuilder.compile()", () => {
 
   test("stores the run function", () => {
     const fn = async () => {};
-    const def = defineWorkflow({ name: "test" }).for("copilot").run(fn).compile();
+    const def = defineWorkflow({ name: "test", source: import.meta.path }).for("copilot").run(fn).compile();
     expect(def.run).toBe(fn);
   });
 
   test("throws if no run callback was provided", () => {
-    const builder = defineWorkflow({ name: "test" }).for("copilot");
+    const builder = defineWorkflow({ name: "test", source: import.meta.path }).for("copilot");
     expect(() => builder.compile()).toThrow("has no run callback");
   });
 
   test("throws if .for() was not called before compile()", () => {
-    const builder = defineWorkflow({ name: "test" }).run(async () => {});
+    const builder = defineWorkflow({ name: "test", source: import.meta.path }).run(async () => {});
     expect(() => builder.compile()).toThrow("has no agent");
   });
 });
@@ -203,6 +228,7 @@ describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
       expect(() =>
         defineWorkflow({
           name: "bad",
+          source: import.meta.path,
           inputs: [{ name: reserved, type: "string" }],
         })
           .for("copilot")
@@ -217,6 +243,7 @@ describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
     try {
       defineWorkflow({
         name: "bad",
+        source: import.meta.path,
         inputs: [{ name: "name", type: "string" }],
       })
         .for("copilot")
@@ -234,6 +261,7 @@ describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
     expect(() =>
       defineWorkflow({
         name: "ok",
+        source: import.meta.path,
         inputs: [{ name: "topic", type: "string" }],
       })
         .for("copilot")
@@ -246,6 +274,7 @@ describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
     expect(() =>
       defineWorkflow({
         name: "ok",
+        source: import.meta.path,
         inputs: [{ name: "named", type: "string" }],
       })
         .for("copilot")
@@ -257,7 +286,7 @@ describe("RESERVED_INPUT_NAMES — reserved name validation", () => {
 
 describe("WorkflowBuilder.for()", () => {
   test("returns a new builder with agent set", () => {
-    const builder = defineWorkflow({ name: "test" });
+    const builder = defineWorkflow({ name: "test", source: import.meta.path });
     const narrowed = builder.for("copilot");
     // .for() returns a new builder instance
     expect(narrowed).toBeInstanceOf(WorkflowBuilder);
@@ -265,7 +294,7 @@ describe("WorkflowBuilder.for()", () => {
   });
 
   test("stores agent on the compiled definition", () => {
-    const def = defineWorkflow({ name: "test" })
+    const def = defineWorkflow({ name: "test", source: import.meta.path })
       .for("copilot")
       .run(async () => {})
       .compile();
@@ -275,6 +304,7 @@ describe("WorkflowBuilder.for()", () => {
   test("chains with run and compile", () => {
     const def = defineWorkflow({
       name: "test",
+      source: import.meta.path,
       inputs: [{ name: "greeting", type: "string" }],
     })
       .for("copilot")
@@ -293,6 +323,7 @@ describe("typed inputs (compile-time)", () => {
     // file without errors (or produces errors only where expected).
     defineWorkflow({
       name: "typed-test",
+      source: import.meta.path,
       inputs: [
         { name: "greeting", type: "string", required: true },
         { name: "style", type: "enum", values: ["formal", "casual"] },
@@ -312,7 +343,7 @@ describe("typed inputs (compile-time)", () => {
   });
 
   test("free-form workflows allow any key", () => {
-    defineWorkflow({ name: "freeform-test" })
+    defineWorkflow({ name: "freeform-test", source: import.meta.path })
       .for("copilot")
       .run(async (ctx) => {
         const _p: string | undefined = ctx.inputs.prompt;

package/src/sdk/define-workflow.ts

@@ -22,12 +22,17 @@ import type {
 type AnyInputs = readonly WorkflowInput[];
 
 /**
- * Flag and subcommand names reserved by the worker CLI that cannot be used as
- * workflow input names. The first block (`name` / `agent` / `detach` / `list`
- * / `help` / `version`) collides with Commander's own flags on the root
- * command; the second block (`session` / `status`) collides with the auto-
- * registered management subcommands added by `createWorkflowCli` when
- * `includeManagementCommands` is left at its default (`true`).
+ * Input names reserved because they collide with the atomic CLI's `workflow`
+ * subcommand surface. The first block (`name` / `agent` / `detach` / `list`
+ * / `help` / `version`) collides with the atomic CLI's `workflow` subcommand
+ * flags (`-n/--name`, `-a/--agent`, `-d/--detach`, `-l/--list`, `-h/--help`,
+ * `-v/--version`). The second block (`session` / `status`) collides with the
+ * atomic CLI's management subcommands (`atomic workflow session …`,
+ * `atomic workflow status`).
+ *
+ * User-app CLIs built with the SDK primitives are NOT bound by these
+ * reservations at runtime — the check runs only inside `defineWorkflow` so
+ * that workflows remain portable to the atomic CLI without renaming.
  */
 export const RESERVED_INPUT_NAMES = [
   "name",
@@ -207,6 +212,18 @@ export class WorkflowBuilder<
       );
     }
 
+    if (
+      typeof this.options.source !== "string" ||
+      this.options.source.trim() === ""
+    ) {
+      throw new Error(
+        `Workflow "${this.options.name}" is missing the \`source\` option. ` +
+          `Pass \`source: import.meta.path\` in the \`defineWorkflow({ ... })\` ` +
+          `call so the SDK orchestrator can re-import the workflow module ` +
+          `inside the spawned tmux session.`,
+      );
+    }
+
     return {
       __brand: "WorkflowDefinition" as const,
       name: this.options.name,
@@ -214,6 +231,7 @@ export class WorkflowBuilder<
       description: this.options.description ?? "",
       inputs,
       minSDKVersion: this.options.minSDKVersion ?? null,
+      source: this.options.source,
       run: runFn,
     };
   }

package/src/sdk/errors.test.ts

@@ -4,6 +4,7 @@ import {
   WorkflowNotCompiledError,
   InvalidWorkflowError,
   IncompatibleSDKError,
+  SessionNotFoundError,
   errorMessage,
 } from "./errors";
 
@@ -43,6 +44,16 @@ describe("InvalidWorkflowError", () => {
   });
 });
 
+describe("SessionNotFoundError", () => {
+  test("sets name, id, and message", () => {
+    const err = new SessionNotFoundError("atomic-wf-claude-ralph-deadbeef");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("SessionNotFoundError");
+    expect(err.id).toBe("atomic-wf-claude-ralph-deadbeef");
+    expect(err.message).toBe("session not found: atomic-wf-claude-ralph-deadbeef");
+  });
+});
+
 describe("IncompatibleSDKError", () => {
   test("sets name, versions, and message", () => {
     const err = new IncompatibleSDKError("/tmp/wf.ts", "2.0.0", "1.4.0");

package/src/sdk/errors.ts

@@ -38,6 +38,19 @@ export class InvalidWorkflowError extends Error {
   }
 }
 
+/**
+ * Thrown by session primitives when the requested tmux session id is
+ * not present on the atomic socket. Carries the id so the CLI layer can
+ * render an actionable "run `atomic session list` to see what's
+ * running" hint without parsing message text.
+ */
+export class SessionNotFoundError extends Error {
+  constructor(public readonly id: string) {
+    super(`session not found: ${id}`);
+    this.name = "SessionNotFoundError";
+  }
+}
+
 /**
  * Thrown when a workflow declares a `minSDKVersion` newer than the
  * bundled CLI. Carries both versions so the CLI can render an

package/src/sdk/index.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Tests for the registry-iteration helpers exported from the SDK barrel.
+ *
+ * `listWorkflows` and `getWorkflow` are thin wrappers around the
+ * registry's `list` / `resolve` methods, but they're the public surface
+ * that downstream CLIs use to enumerate registered workflows — worth
+ * pinning to a regression test so changes to the wrapper signature
+ * surface here first.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRegistry,
+  defineWorkflow,
+  getWorkflow,
+  listWorkflows,
+} from "./index.ts";
+
+function makeWorkflow(name: string, agent: "claude" | "copilot" | "opencode") {
+  return defineWorkflow({ name, source: import.meta.path })
+    .for(agent)
+    .run(async () => {})
+    .compile();
+}
+
+describe("listWorkflows", () => {
+  test("returns an empty array for an empty registry", () => {
+    const registry = createRegistry();
+    expect(listWorkflows(registry)).toEqual([]);
+  });
+
+  test("returns every registered workflow regardless of agent", () => {
+    const registry = createRegistry()
+      .register(makeWorkflow("a", "claude"))
+      .register(makeWorkflow("b", "copilot"))
+      .register(makeWorkflow("c", "opencode"));
+
+    const all = listWorkflows(registry);
+    expect(all).toHaveLength(3);
+    expect(all.map((w) => `${w.agent}/${w.name}`).sort()).toEqual([
+      "claude/a",
+      "copilot/b",
+      "opencode/c",
+    ]);
+  });
+
+  test("preserves the (agent, name) pair so the same name across agents stays distinct", () => {
+    const registry = createRegistry()
+      .register(makeWorkflow("ralph", "claude"))
+      .register(makeWorkflow("ralph", "copilot"));
+
+    const all = listWorkflows(registry);
+    expect(all).toHaveLength(2);
+    const keys = all.map((w) => `${w.agent}/${w.name}`).sort();
+    expect(keys).toEqual(["claude/ralph", "copilot/ralph"]);
+  });
+});
+
+describe("getWorkflow", () => {
+  test("returns undefined when the (name, agent) pair is not registered", () => {
+    const registry = createRegistry();
+    expect(getWorkflow(registry, "claude", "missing")).toBeUndefined();
+  });
+
+  test("returns undefined when only the name (but not the agent) matches", () => {
+    const registry = createRegistry().register(makeWorkflow("ralph", "claude"));
+    // Same name, different agent — must NOT resolve.
+    expect(getWorkflow(registry, "copilot", "ralph")).toBeUndefined();
+  });
+
+  test("resolves the matching (name, agent) pair", () => {
+    const wf = makeWorkflow("ralph", "claude");
+    const registry = createRegistry().register(wf);
+    const result = getWorkflow(registry, "claude", "ralph");
+    expect(result).toBeDefined();
+    expect(result!.name).toBe("ralph");
+    expect(result!.agent).toBe("claude");
+  });
+
+  test("does not return a workflow registered under a different agent", () => {
+    const registry = createRegistry()
+      .register(makeWorkflow("ralph", "claude"))
+      .register(makeWorkflow("ralph", "copilot"));
+
+    const claudeRalph = getWorkflow(registry, "claude", "ralph");
+    const copilotRalph = getWorkflow(registry, "copilot", "ralph");
+    expect(claudeRalph).toBeDefined();
+    expect(copilotRalph).toBeDefined();
+    expect(claudeRalph!.agent).toBe("claude");
+    expect(copilotRalph!.agent).toBe("copilot");
+  });
+});