@bastani/atomic 0.5.20-0 → 0.5.21-0

package/src/commands/cli/workflow-inputs.test.ts

@@ -0,0 +1,321 @@
+/**
+ * Unit tests for the workflow-inputs CLI command.
+ *
+ * Focused on the pure helpers (`buildInputsPayload` + `renderInputsText`)
+ * since they carry the schema-shaping logic. The thin command wrapper
+ * is exercised end-to-end by the existing workflow-command harness.
+ */
+
+import { describe, test, expect, beforeAll, afterAll, mock } from "bun:test";
+import {
+  buildInputsPayload,
+  renderInputsText,
+  workflowInputsCommand,
+  type WorkflowInputsDeps,
+} from "./workflow-inputs.ts";
+import type {
+  WorkflowInput,
+  DiscoveredWorkflow,
+  WorkflowDefinition,
+} from "../../sdk/workflows/index.ts";
+
+let originalNoColor: string | undefined;
+beforeAll(() => {
+  originalNoColor = process.env.NO_COLOR;
+  process.env.NO_COLOR = "1";
+});
+afterAll(() => {
+  if (originalNoColor === undefined) delete process.env.NO_COLOR;
+  else process.env.NO_COLOR = originalNoColor;
+});
+
+describe("buildInputsPayload", () => {
+  test("synthesises a 'prompt' field for free-form workflows", () => {
+    const out = buildInputsPayload("ralph", "claude", "loop", []);
+    expect(out.freeform).toBe(true);
+    expect(out.inputs).toHaveLength(1);
+    expect(out.inputs[0]!.name).toBe("prompt");
+    expect(out.inputs[0]!.type).toBe("text");
+  });
+
+  test("clones structured inputs without mutating callers' arrays", () => {
+    const schema: WorkflowInput[] = [
+      { name: "research_doc", type: "string", required: true },
+      {
+        name: "focus",
+        type: "enum",
+        values: ["minimal", "standard"],
+        default: "standard",
+      },
+    ];
+    const out = buildInputsPayload("gen-spec", "claude", "spec", schema);
+    expect(out.freeform).toBe(false);
+    expect(out.inputs).toHaveLength(2);
+    expect(out.inputs[0]!.name).toBe("research_doc");
+    expect(out.inputs[1]!.values).toEqual(["minimal", "standard"]);
+    // mutating the output must not leak into the input
+    out.inputs[0]!.required = false;
+    expect(schema[0]!.required).toBe(true);
+  });
+
+  test("propagates description and agent into the payload", () => {
+    const out = buildInputsPayload("foo", "copilot", "describe me", []);
+    expect(out.workflow).toBe("foo");
+    expect(out.agent).toBe("copilot");
+    expect(out.description).toBe("describe me");
+  });
+});
+
+describe("renderInputsText", () => {
+  test("free-form workflows show the positional-prompt run hint", () => {
+    const payload = buildInputsPayload("ralph", "claude", "loop", []);
+    const out = renderInputsText(payload);
+    expect(out).toContain("ralph");
+    expect(out).toContain("claude");
+    expect(out).toContain("free-form");
+    expect(out).toContain('atomic workflow -n ralph -a claude "<prompt>"');
+  });
+
+  test("renders placeholder hint when a field declares one", () => {
+    const schema: WorkflowInput[] = [
+      {
+        name: "note",
+        type: "text",
+        placeholder: "short summary goes here",
+      },
+    ];
+    const payload = buildInputsPayload("foo", "claude", "", schema);
+    const out = renderInputsText(payload);
+    expect(out).toContain("placeholder:");
+    expect(out).toContain("short summary goes here");
+  });
+
+  test("structured workflows render flag names, types, required, defaults, and enum values", () => {
+    const schema: WorkflowInput[] = [
+      {
+        name: "research_doc",
+        type: "string",
+        required: true,
+        description: "path to research notes",
+      },
+      {
+        name: "focus",
+        type: "enum",
+        values: ["minimal", "standard", "exhaustive"],
+        default: "standard",
+      },
+    ];
+    const payload = buildInputsPayload("gen-spec", "claude", "spec", schema);
+    const out = renderInputsText(payload);
+
+    expect(out).toContain("--research_doc");
+    expect(out).toContain("(required)");
+    expect(out).toContain("[string]");
+    expect(out).toContain("path to research notes");
+
+    expect(out).toContain("--focus");
+    expect(out).toContain("[enum]");
+    expect(out).toContain("minimal, standard, exhaustive");
+    expect(out).toContain("default: standard");
+
+    // run hint references both flags
+    expect(out).toContain("--research_doc=<string>");
+    expect(out).toContain("--focus=<enum>");
+  });
+});
+
+// ─── workflowInputsCommand ─────────────────────────────────────────
+
+function captureOutput(): {
+  stdout: () => string;
+  stderr: () => string;
+  restore: () => void;
+} {
+  const outChunks: string[] = [];
+  const errChunks: string[] = [];
+  const origOut = process.stdout.write;
+  const origErr = process.stderr.write;
+  process.stdout.write = ((c: string | Uint8Array) => {
+    outChunks.push(typeof c === "string" ? c : new TextDecoder().decode(c));
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((c: string | Uint8Array) => {
+    errChunks.push(typeof c === "string" ? c : new TextDecoder().decode(c));
+    return true;
+  }) as typeof process.stderr.write;
+  return {
+    stdout: () => outChunks.join(""),
+    stderr: () => errChunks.join(""),
+    restore: () => {
+      process.stdout.write = origOut;
+      process.stderr.write = origErr;
+    },
+  };
+}
+
+function fakeDiscovered(name: string): DiscoveredWorkflow {
+  return {
+    name,
+    agent: "claude",
+    path: `/fake/path/${name}.ts`,
+    source: "builtin",
+  };
+}
+
+function fakeDefinition(
+  name: string,
+  description: string,
+  inputs: WorkflowInput[],
+): WorkflowDefinition {
+  return {
+    __brand: "WorkflowDefinition",
+    name,
+    description,
+    inputs,
+    run: async () => {},
+  } as WorkflowDefinition;
+}
+
+function makeDeps(overrides: Partial<WorkflowInputsDeps> = {}): WorkflowInputsDeps {
+  return {
+    findWorkflow: mock(async () => fakeDiscovered("gen-spec")) as unknown as
+      WorkflowInputsDeps["findWorkflow"],
+    loadWorkflow: mock(async (plan) => ({
+      ok: true,
+      value: {
+        ...plan,
+        warnings: [],
+        definition: fakeDefinition("gen-spec", "spec generator", [
+          { name: "research_doc", type: "string", required: true },
+        ]),
+      },
+    })) as unknown as WorkflowInputsDeps["loadWorkflow"],
+    ...overrides,
+  };
+}
+
+describe("workflowInputsCommand", () => {
+  test("returns 1 with a JSON error envelope on unknown agent", async () => {
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "gen-spec", agent: "bogus", format: "json" },
+        makeDeps(),
+      );
+      expect(code).toBe(1);
+      const parsed = JSON.parse(cap.stdout());
+      expect(parsed.error).toContain("Unknown agent");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("returns 1 with a JSON error envelope when the workflow is missing", async () => {
+    const deps = makeDeps({
+      findWorkflow: mock(async () => null) as unknown as
+        WorkflowInputsDeps["findWorkflow"],
+    });
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "missing", agent: "claude", format: "json" },
+        deps,
+      );
+      expect(code).toBe(1);
+      const parsed = JSON.parse(cap.stdout());
+      expect(parsed.error).toContain("not found");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("returns 1 when the loader fails to load the workflow", async () => {
+    const deps = makeDeps({
+      loadWorkflow: mock(async () => ({
+        ok: false,
+        stage: "load" as const,
+        error: new Error("boom"),
+        message: "boom",
+      })) as unknown as WorkflowInputsDeps["loadWorkflow"],
+    });
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "gen-spec", agent: "claude", format: "json" },
+        deps,
+      );
+      expect(code).toBe(1);
+      const parsed = JSON.parse(cap.stdout());
+      expect(parsed.error).toBe("boom");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("prints the JSON payload on success", async () => {
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "gen-spec", agent: "claude", format: "json" },
+        makeDeps(),
+      );
+      expect(code).toBe(0);
+      const parsed = JSON.parse(cap.stdout());
+      expect(parsed.workflow).toBe("gen-spec");
+      expect(parsed.agent).toBe("claude");
+      expect(parsed.inputs).toHaveLength(1);
+      expect(parsed.inputs[0].name).toBe("research_doc");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("prints the text render on success when format is 'text'", async () => {
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "gen-spec", agent: "claude", format: "text" },
+        makeDeps(),
+      );
+      expect(code).toBe(0);
+      const out = cap.stdout();
+      expect(out).toContain("gen-spec");
+      expect(out).toContain("--research_doc");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("writes errors to stderr when format is 'text'", async () => {
+    const deps = makeDeps({
+      findWorkflow: mock(async () => null) as unknown as
+        WorkflowInputsDeps["findWorkflow"],
+    });
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "missing", agent: "claude", format: "text" },
+        deps,
+      );
+      expect(code).toBe(1);
+      expect(cap.stderr()).toContain("not found");
+    } finally {
+      cap.restore();
+    }
+  });
+
+  test("defaults format to 'json' when omitted", async () => {
+    const cap = captureOutput();
+    try {
+      const code = await workflowInputsCommand(
+        { name: "gen-spec", agent: "claude" },
+        makeDeps(),
+      );
+      expect(code).toBe(0);
+      // JSON parses cleanly
+      JSON.parse(cap.stdout());
+    } finally {
+      cap.restore();
+    }
+  });
+});

package/src/commands/cli/workflow-inputs.ts

@@ -0,0 +1,219 @@
+/**
+ * `atomic workflow inputs <name> -a <agent>` — print a workflow's
+ * declared input schema so an orchestrating agent can build a valid
+ * `atomic workflow -n <name> -a <agent> --<field>=<value>` invocation
+ * without having to read the workflow source.
+ *
+ * Output formats:
+ *   --format json   (default) — machine-parseable JSON
+ *   --format text             — human-friendly text table
+ *
+ * Free-form workflows (no declared inputs) report a single synthetic
+ * `prompt` field so callers can treat both shapes uniformly.
+ */
+
+import { COLORS, createPainter } from "../../theme/colors.ts";
+import { AGENT_CONFIG, type AgentKey } from "../../services/config/index.ts";
+import {
+  findWorkflow as _findWorkflow,
+  WorkflowLoader,
+} from "../../sdk/workflows/index.ts";
+import type { WorkflowInput } from "../../sdk/workflows/index.ts";
+
+export type WorkflowInputsFormat = "json" | "text";
+
+export interface WorkflowInputsResult {
+  workflow: string;
+  agent: string;
+  description: string;
+  freeform: boolean;
+  inputs: WorkflowInput[];
+}
+
+/**
+ * Build the JSON payload returned to the agent. Free-form workflows
+ * synthesise a single optional `prompt` field so consumers don't have
+ * to special-case them — the same call shape works for both kinds.
+ */
+export function buildInputsPayload(
+  workflowName: string,
+  agent: string,
+  description: string,
+  inputs: readonly WorkflowInput[],
+): WorkflowInputsResult {
+  const freeform = inputs.length === 0;
+  const declared: WorkflowInput[] = freeform
+    ? [
+        {
+          name: "prompt",
+          type: "text",
+          required: false,
+          description:
+            "Free-form prompt — pass as a positional arg to `atomic workflow -n <name> -a <agent> \"<prompt>\"`.",
+        },
+      ]
+    : inputs.map((i) => ({ ...i }));
+  return {
+    workflow: workflowName,
+    agent,
+    description,
+    freeform,
+    inputs: declared,
+  };
+}
+
+/** Render the payload as a human-friendly text block. */
+export function renderInputsText(payload: WorkflowInputsResult): string {
+  const paint = createPainter();
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(
+    "  " +
+      paint("text", payload.workflow, { bold: true }) +
+      paint("dim", " (") +
+      paint("accent", payload.agent) +
+      paint("dim", ")"),
+  );
+  if (payload.description) {
+    lines.push("  " + paint("dim", payload.description));
+  }
+  lines.push("");
+  if (payload.freeform) {
+    lines.push("  " + paint("dim", "free-form workflow — single positional prompt"));
+    lines.push("");
+    lines.push(
+      "  " +
+        paint("dim", "run: ") +
+        paint(
+          "accent",
+          `atomic workflow -n ${payload.workflow} -a ${payload.agent} "<prompt>"`,
+        ),
+    );
+    lines.push("");
+    return lines.join("\n") + "\n";
+  }
+
+  for (const field of payload.inputs) {
+    const requiredLabel = field.required ? paint("warning", " (required)") : "";
+    const typeLabel = paint("dim", ` [${field.type}]`);
+    lines.push(
+      "  " +
+        paint("accent", `--${field.name}`) +
+        typeLabel +
+        requiredLabel,
+    );
+    if (field.description) {
+      lines.push("      " + paint("text", field.description));
+    }
+    if (field.type === "enum" && field.values && field.values.length > 0) {
+      lines.push(
+        "      " +
+          paint("dim", "values: ") +
+          paint("text", field.values.join(", ")),
+      );
+    }
+    if (field.default !== undefined) {
+      lines.push(
+        "      " + paint("dim", "default: ") + paint("text", field.default),
+      );
+    }
+    if (field.placeholder) {
+      lines.push(
+        "      " +
+          paint("dim", "placeholder: ") +
+          paint("text", field.placeholder),
+      );
+    }
+  }
+
+  lines.push("");
+  const flagExample = payload.inputs
+    .map((i) => `--${i.name}=<${i.type}>`)
+    .join(" ");
+  lines.push(
+    "  " +
+      paint("dim", "run: ") +
+      paint(
+        "accent",
+        `atomic workflow -n ${payload.workflow} -a ${payload.agent} ${flagExample}`,
+      ),
+  );
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+
+export interface WorkflowInputsOptions {
+  name: string;
+  agent: string;
+  format?: WorkflowInputsFormat;
+  cwd?: string;
+}
+
+/**
+ * Deps for `workflowInputsCommand`. Injected so tests can drive every
+ * branch (unknown agent / missing workflow / load failure / success)
+ * without the SDK's real filesystem-dependent discovery.
+ */
+export interface WorkflowInputsDeps {
+  findWorkflow: typeof _findWorkflow;
+  loadWorkflow: typeof WorkflowLoader.loadWorkflow;
+}
+
+const defaultDeps: WorkflowInputsDeps = {
+  findWorkflow: _findWorkflow,
+  loadWorkflow: WorkflowLoader.loadWorkflow,
+};
+
+/**
+ * Resolve the workflow, then either print its input schema (success)
+ * or print an error and return a non-zero exit code. The json branch
+ * also writes errors as JSON so an agent can parse a single envelope
+ * regardless of outcome.
+ */
+export async function workflowInputsCommand(
+  options: WorkflowInputsOptions,
+  deps: WorkflowInputsDeps = defaultDeps,
+): Promise<number> {
+  const format: WorkflowInputsFormat = options.format ?? "json";
+
+  const validAgents = Object.keys(AGENT_CONFIG);
+  if (!validAgents.includes(options.agent)) {
+    return reportError(
+      format,
+      `Unknown agent '${options.agent}'. Valid agents: ${validAgents.join(", ")}`,
+    );
+  }
+  const agent = options.agent as AgentKey;
+
+  const discovered = await deps.findWorkflow(options.name, agent, options.cwd);
+  if (!discovered) {
+    return reportError(
+      format,
+      `Workflow '${options.name}' not found for agent '${agent}'.`,
+    );
+  }
+
+  const loaded = await deps.loadWorkflow(discovered);
+  if (!loaded.ok) {
+    return reportError(format, loaded.message);
+  }
+  const def = loaded.value.definition;
+
+  const payload = buildInputsPayload(def.name, agent, def.description, def.inputs);
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+  } else {
+    process.stdout.write(renderInputsText(payload));
+  }
+  return 0;
+}
+
+function reportError(format: WorkflowInputsFormat, message: string): number {
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ error: message }, null, 2) + "\n");
+  } else {
+    process.stderr.write(`${COLORS.red}Error: ${message}${COLORS.reset}\n`);
+  }
+  return 1;
+}