@bastani/atomic 0.6.8 → 0.7.0-2

package/src/sdk/errors.test.ts

@@ -1,83 +0,0 @@
-import { test, expect, describe } from "bun:test";
-import {
-  MissingDependencyError,
-  WorkflowNotCompiledError,
-  InvalidWorkflowError,
-  IncompatibleSDKError,
-  SessionNotFoundError,
-  errorMessage,
-} from "./errors";
-
-describe("MissingDependencyError", () => {
-  test("sets name, dependency, and message", () => {
-    const err = new MissingDependencyError("tmux");
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("MissingDependencyError");
-    expect(err.dependency).toBe("tmux");
-    expect(err.message).toBe("Required dependency not found: tmux");
-  });
-
-  test.each(["tmux", "psmux", "bun"] as const)("accepts %s", (dep) => {
-    const err = new MissingDependencyError(dep);
-    expect(err.message).toContain(dep);
-  });
-});
-
-describe("WorkflowNotCompiledError", () => {
-  test("sets name, path, and message", () => {
-    const err = new WorkflowNotCompiledError("/tmp/wf.ts");
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("WorkflowNotCompiledError");
-    expect(err.path).toBe("/tmp/wf.ts");
-    expect(err.message).toContain("Workflow at /tmp/wf.ts was defined but not compiled");
-    expect(err.message).toContain(".compile()");
-  });
-});
-
-describe("InvalidWorkflowError", () => {
-  test("sets name, path, and message", () => {
-    const err = new InvalidWorkflowError("/tmp/bad.ts");
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("InvalidWorkflowError");
-    expect(err.path).toBe("/tmp/bad.ts");
-    expect(err.message).toContain("/tmp/bad.ts does not export a valid WorkflowDefinition");
-  });
-});
-
-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");
-    expect(err).toBeInstanceOf(Error);
-    expect(err.name).toBe("IncompatibleSDKError");
-    expect(err.path).toBe("/tmp/wf.ts");
-    expect(err.requiredVersion).toBe("2.0.0");
-    expect(err.currentVersion).toBe("1.4.0");
-    expect(err.message).toContain("/tmp/wf.ts");
-    expect(err.message).toContain("v2.0.0");
-    expect(err.message).toContain("v1.4.0");
-    expect(err.message).toContain("Update Atomic");
-  });
-});
-
-describe("errorMessage", () => {
-  test("extracts message from Error", () => {
-    expect(errorMessage(new Error("boom"))).toBe("boom");
-  });
-
-  test("stringifies non-Error values", () => {
-    expect(errorMessage("oops")).toBe("oops");
-    expect(errorMessage(42)).toBe("42");
-    expect(errorMessage(null)).toBe("null");
-    expect(errorMessage(undefined)).toBe("undefined");
-  });
-});

package/src/sdk/errors.ts

@@ -1,77 +0,0 @@
-/**
- * Typed error classes for the SDK.
- *
- * The SDK throws these instead of calling process.exit() or console.error().
- * The CLI layer catches them and maps to user-visible output.
- */
-
-/** Thrown when a required system dependency is not found on PATH. */
-export class MissingDependencyError extends Error {
-  constructor(public readonly dependency: "tmux" | "psmux" | "bun") {
-    super(`Required dependency not found: ${dependency}`);
-    this.name = "MissingDependencyError";
-  }
-}
-
-/** Thrown when a workflow file is defined but missing .compile(). */
-export class WorkflowNotCompiledError extends Error {
-  constructor(public readonly path: string) {
-    super(
-      `Workflow at ${path} was defined but not compiled.\n` +
-      `  Add .compile() at the end of your defineWorkflow() chain:\n\n` +
-      `    export default defineWorkflow({ ... })\n` +
-      `      .run(async (ctx) => { ... })\n` +
-      `      .compile();`,
-    );
-    this.name = "WorkflowNotCompiledError";
-  }
-}
-
-/** Thrown when a workflow file does not export a valid WorkflowDefinition. */
-export class InvalidWorkflowError extends Error {
-  constructor(public readonly path: string) {
-    super(
-      `${path} does not export a valid WorkflowDefinition.\n` +
-      `  Make sure it exports defineWorkflow(...).compile() as the default export.`,
-    );
-    this.name = "InvalidWorkflowError";
-  }
-}
-
-/**
- * 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
- * actionable "update atomic or re-save the workflow" hint rather than
- * a generic load error.
- */
-export class IncompatibleSDKError extends Error {
-  constructor(
-    public readonly path: string,
-    public readonly requiredVersion: string,
-    public readonly currentVersion: string,
-  ) {
-    super(
-      `${path} requires Atomic SDK v${requiredVersion}, but v${currentVersion} is installed.\n` +
-      `  Update Atomic, or re-save the workflow against the current SDK.`,
-    );
-    this.name = "IncompatibleSDKError";
-  }
-}
-
-/** Extract a human-readable message from an unknown thrown value. */
-export function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}

package/src/sdk/index.test.ts

@@ -1,92 +0,0 @@
-/**
- * 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");
-  });
-});

package/src/sdk/index.ts

@@ -1,101 +0,0 @@
-/**
- * @bastani/atomic — SDK barrel.
- *
- * Public API for authoring and running workflows. Composition primitives
- * are pure functions; consumers wire them into their own CLI shape (via
- * Commander, citty, yargs, an OpenTUI app, etc.). The SDK itself ships
- * no opinionated CLI wrapper.
- */
-
-// ─── Typed errors ───────────────────────────────────────────────────────────
-export {
-  MissingDependencyError,
-  WorkflowNotCompiledError,
-  InvalidWorkflowError,
-  SessionNotFoundError,
-} from "./errors.ts";
-
-// ─── Authoring ──────────────────────────────────────────────────────────────
-export { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
-export { createRegistry } from "./registry.ts";
-export type { Registry } from "./registry.ts";
-
-// ─── Shared types ───────────────────────────────────────────────────────────
-export type {
-  AgentType,
-  Transcript,
-  SavedMessage,
-  SaveTranscript,
-  SessionContext,
-  SessionRef,
-  SessionHandle,
-  SessionRunOptions,
-  WorkflowContext,
-  WorkflowOptions,
-  WorkflowDefinition,
-  WorkflowInput,
-  WorkflowInputType,
-  StageClientOptions,
-  StageSessionOptions,
-  ProviderClient,
-  ProviderSession,
-} from "./types.ts";
-
-// ─── Metadata accessors ─────────────────────────────────────────────────────
-export {
-  getName,
-  getDescription,
-  getAgent,
-  getInputSchema,
-  getSource,
-  getMinSDKVersion,
-} from "./primitives/metadata.ts";
-
-// ─── Registry iteration helpers ─────────────────────────────────────────────
-import type { AgentType, Registry, WorkflowDefinition } from "./types.ts";
-
-/** Snapshot every workflow registered in `registry`. */
-export function listWorkflows(registry: Registry): readonly WorkflowDefinition[] {
-  return registry.list();
-}
-
-/** Resolve a workflow by `(name, agent)`; returns `undefined` when not found. */
-export function getWorkflow(
-  registry: Registry,
-  agent: AgentType,
-  name: string,
-): WorkflowDefinition | undefined {
-  return registry.resolve(name, agent);
-}
-
-// ─── Input validation ───────────────────────────────────────────────────────
-export { validateInputs } from "./primitives/inputs.ts";
-export type { ResolvedInputs } from "./primitives/inputs.ts";
-
-// ─── Run a workflow ─────────────────────────────────────────────────────────
-export { runWorkflow } from "./primitives/run.ts";
-export type {
-  RunWorkflowOptions,
-  RunWorkflowResult,
-} from "./primitives/run.ts";
-
-// ─── Session management ─────────────────────────────────────────────────────
-export {
-  listSessions,
-  getSession,
-  stopSession,
-  attachSession,
-  detachSession,
-  nextWindow,
-  previousWindow,
-  gotoOrchestrator,
-  getSessionStatus,
-  getSessionTranscript,
-} from "./primitives/sessions.ts";
-export type {
-  SessionInfo,
-  SessionScope,
-  StatusSnapshot,
-  ListSessionsOptions,
-  SessionPrimitiveDeps,
-} from "./primitives/sessions.ts";

package/src/sdk/primitives/inputs.ts

@@ -1,48 +0,0 @@
-/**
- * Input validation primitive.
- *
- * Wraps `validateAndResolve` from `worker-shared.ts` with a workflow-aware
- * signature so consumers don't need to reach into the SDK internals to
- * coerce, default, and validate raw user-supplied input maps.
- */
-
-import type { WorkflowInput } from "../types.ts";
-import { validateAndResolve } from "../worker-shared.ts";
-
-/**
- * Validated, defaults-applied input map. The shape matches
- * `Record<string, string>` because the executor's tmux launcher serialises
- * inputs as JSON strings; integer coercion happens later, inside
- * `runOrchestrator`, against the same schema.
- */
-export type ResolvedInputs = Record<string, string>;
-
-/**
- * Structural shape `validateInputs` reads off a workflow definition.
- * Typed as a minimal interface (rather than `WorkflowDefinition`) so the
- * primitive accepts narrowly-typed compiled definitions without
- * triggering contravariance failures in the `run` method signature.
- */
-export interface ValidatableWorkflow {
-  readonly inputs: readonly WorkflowInput[];
-}
-
-/**
- * Validate raw user inputs against a workflow's declared schema.
- *
- * - Throws on unknown flags or missing required fields.
- * - Applies declared defaults and the first enum value when no value is given.
- * - Validates enum membership and integer parseability.
- * - For free-form workflows (no declared inputs), passes through every
- *   non-empty key as-is — this preserves the legacy
- *   `--prompt "<text>"` shape.
- */
-export function validateInputs(
-  workflow: ValidatableWorkflow,
-  raw: Record<string, string>,
-): ResolvedInputs {
-  if (workflow.inputs.length === 0) {
-    return { ...raw };
-  }
-  return validateAndResolve(raw, workflow.inputs);
-}

package/src/sdk/primitives/metadata.ts

@@ -1,63 +0,0 @@
-/**
- * Workflow metadata accessors.
- *
- * Function-style getters keep the public surface forward-compatible —
- * adding optional metadata fields to `WorkflowDefinition` doesn't force
- * every consumer to read directly off the object, so we can add lazy
- * derivation, deprecation warnings, or normalization in one place.
- */
-
-import type { AgentType, WorkflowInput } from "../types.ts";
-
-/**
- * Structural shape the metadata accessors read off a workflow
- * definition. Typed as a minimal interface (rather than the full
- * `WorkflowDefinition<A, I>`) so the accessors accept narrowly-typed
- * compiled definitions without triggering contravariance failures on
- * the `run` method signature.
- */
-export interface MetadataWorkflow {
-  readonly name: string;
-  readonly description: string;
-  readonly agent: AgentType;
-  readonly inputs: readonly WorkflowInput[];
-  readonly source: string;
-  readonly minSDKVersion: string | null;
-}
-
-/** Workflow's unique name. */
-export function getName(workflow: MetadataWorkflow): string {
-  return workflow.name;
-}
-
-/** Human-readable description (empty string when none was declared). */
-export function getDescription(workflow: MetadataWorkflow): string {
-  return workflow.description;
-}
-
-/** Agent backend the workflow targets. */
-export function getAgent(workflow: MetadataWorkflow): AgentType {
-  return workflow.agent;
-}
-
-/** Frozen copy of the declared input schema (empty for free-form workflows). */
-export function getInputSchema(
-  workflow: MetadataWorkflow,
-): readonly WorkflowInput[] {
-  return workflow.inputs;
-}
-
-/** Absolute path of the workflow's source file (`import.meta.path`). */
-export function getSource(workflow: MetadataWorkflow): string {
-  return workflow.source;
-}
-
-/**
- * Minimum SDK version this workflow declares (or `null` when none was
- * specified). Atomic uses this to gate stale workflows on older installs.
- */
-export function getMinSDKVersion(
-  workflow: MetadataWorkflow,
-): string | null {
-  return workflow.minSDKVersion;
-}

package/src/sdk/primitives/run.ts

@@ -1,81 +0,0 @@
-/**
- * `runWorkflow` primitive — the public entry point for spawning a
- * workflow tmux session.
- *
- * Thin wrapper around the runtime executor's `executeWorkflow`. Handles
- * the input-validation step so the executor's contract stays single-
- * responsibility: caller passes raw inputs, primitive validates them
- * against the workflow's schema, executor only sees a clean record.
- */
-
-import {
-  executeWorkflow,
-} from "../runtime/executor.ts";
-import type { RegistrableWorkflow, WorkflowDefinition } from "../types.ts";
-import { validateInputs } from "./inputs.ts";
-
-/** Options for `runWorkflow()`. */
-export interface RunWorkflowOptions {
-  /** Compiled workflow definition (the default export of a workflow module). */
-  workflow: RegistrableWorkflow;
-  /**
-   * Raw input map. The primitive runs the same validation pipeline the
-   * atomic CLI uses: required-field check, default fill-in, enum and
-   * integer parsing. Pass an empty object for free-form workflows that
-   * don't take any user input.
-   */
-  inputs?: Record<string, string>;
-  /** Project root the workflow runs in. Defaults to `process.cwd()`. */
-  cwd?: string;
-  /**
-   * When true, create the tmux session and return immediately instead
-   * of attaching. The orchestrator keeps running in the background on
-   * the shared atomic tmux socket and can be reattached later via
-   * `attachSession()`.
-   */
-  detach?: boolean;
-}
-
-/** Result of a successful `runWorkflow()` call. */
-export interface RunWorkflowResult {
-  /** Workflow run id (8-char hex; the trailing segment of the tmux session name). */
-  id: string;
-  /** Tmux session name (`atomic-wf-<agent>-<workflowName>-<id>`). */
-  tmuxSessionName: string;
-}
-
-/**
- * Run a compiled workflow.
- *
- * Validates inputs, then spawns the orchestrator tmux session via
- * `executeWorkflow`. In foreground mode, the returned promise resolves
- * after the user detaches from the session; in `detach: true` mode the
- * promise resolves as soon as the session is created on the atomic
- * socket.
- *
- * @example
- * ```ts
- * import workflow from "./hello.ts";
- * import { runWorkflow } from "@bastani/atomic/workflows";
- *
- * await runWorkflow({ workflow, inputs: { greeting: "hi" } });
- * ```
- */
-export async function runWorkflow(
-  options: RunWorkflowOptions,
-): Promise<RunWorkflowResult> {
-  const { workflow, inputs = {}, cwd, detach } = options;
-  const resolved = validateInputs(workflow, inputs);
-  return await executeWorkflow({
-    // Cast required because RegistrableWorkflow's `run` is `(...args: never[]) => Promise<void>`
-    // (a structural shape that bypasses contravariance), while the runtime
-    // executor takes the typed WorkflowDefinition. The runtime never
-    // calls `run` directly through this path — it spawns a tmux session
-    // and the SDK orchestrator entry imports the module fresh.
-    definition: workflow as unknown as WorkflowDefinition,
-    agent: workflow.agent,
-    inputs: resolved,
-    projectRoot: cwd,
-    detach,
-  });
-}