@bastani/atomic 0.6.4 → 0.6.5

package/src/sdk/index.ts

@@ -1,18 +1,26 @@
 /**
- * atomic SDK
+ * @bastani/atomic — SDK barrel.
  *
- * Public API barrel — re-exports the SDK surface.
- * CLI-only concerns (colors, prompts, process management) are not exported here.
+ * 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
+// ─── Typed errors ───────────────────────────────────────────────────────────
 export {
   MissingDependencyError,
   WorkflowNotCompiledError,
   InvalidWorkflowError,
+  SessionNotFoundError,
 } from "./errors.ts";
 
-// Shared types
+// ─── 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,
@@ -25,21 +33,69 @@ export type {
   WorkflowContext,
   WorkflowOptions,
   WorkflowDefinition,
+  WorkflowInput,
+  WorkflowInputType,
   StageClientOptions,
   StageSessionOptions,
   ProviderClient,
   ProviderSession,
 } from "./types.ts";
 
-// Workflow SDK (also available as atomic/workflows subpath)
-export { defineWorkflow } from "./define-workflow.ts";
+// ─── Metadata accessors ─────────────────────────────────────────────────────
+export {
+  getName,
+  getDescription,
+  getAgent,
+  getInputSchema,
+  getSource,
+  getMinSDKVersion,
+} from "./primitives/metadata.ts";
 
-// Registry
-export type { Registry } from "./registry.ts";
-export { createRegistry } from "./registry.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();
+}
 
-// WorkflowCli — the factory that drives workflow CLIs. Accepts a lone
-// workflow, an array of workflows, or a Registry for programmatic
-// composition. Ships with the interactive picker out of the box.
-export { createWorkflowCli } from "./workflow-cli.ts";
-export type { WorkflowCli, CreateWorkflowCliOptions } from "./types.ts";
+/** 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

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * 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

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