@wanbicoi/next-steps 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,1440 @@
+#!/usr/bin/env node
+// @bun
+
+// src/cli.ts
+import { join as join4 } from "path";
+import { pathToFileURL } from "url";
+import { parseArgs } from "util";
+
+// src/types.ts
+var END = "END";
+
+class AppError extends Error {
+  code;
+  exitCode;
+  details;
+  constructor(code, message, exitCode = 1, details) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+    this.name = "AppError";
+  }
+}
+
+// src/format.ts
+function table(headers, rows) {
+  const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? "").length)));
+  const render = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join("  ").trimEnd();
+  return [render(headers), ...rows.map(render)].join(`
+`);
+}
+function formatScope(scope) {
+  return scope.length > 0 ? scope.join(" > ") : "-";
+}
+function formatTime(iso) {
+  return iso.slice(0, 19).replace("T", " ");
+}
+function optionLine(option, index) {
+  const label = option.edge ? `${option.edge} -> ${option.node}` : option.node;
+  const title = option.node === END ? "" : option.title;
+  const head = `  ${index + 1}. ${label}${title ? `  ${title}` : ""}`.trimEnd();
+  const lines = [head, `     ${option.description}`];
+  if (option.condition)
+    lines.push(`     when: ${option.condition}`);
+  return lines;
+}
+function formatNext(next) {
+  if (next.done && next.next.length === 0)
+    return "done: true";
+  if (next.next.length === 0)
+    return "next: (none)";
+  const lines = ["next:"];
+  for (const [index, option] of next.next.entries()) {
+    lines.push(...optionLine(option, index));
+  }
+  return lines.join(`
+`);
+}
+function formatCurrent(next) {
+  if (next.done) {
+    return `current: ${next.current ?? END}  (finished)   scope: ${formatScope(next.scope)}`;
+  }
+  if (next.current === null) {
+    return `current: (not started)   scope: ${formatScope(next.scope)}`;
+  }
+  const title = next.currentTitle ? `  (${next.currentTitle})` : "";
+  return `current: ${next.current}${title}   scope: ${formatScope(next.scope)}`;
+}
+
+// src/commands/shared.ts
+function usageError(message) {
+  return new AppError("usage", message, 2);
+}
+function requireString(value, flag) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw usageError(`--${flag} is required`);
+  }
+  return value;
+}
+function toJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+// src/commands/session.ts
+function cmdCreate(service, input) {
+  const workflowId = requireString(input.workflowId, "workflow");
+  const { session, workflowTitle, next } = service.create({ workflowId, key: input.key });
+  if (input.json) {
+    return toJson({
+      key: session.key,
+      workflowId: session.workflowId,
+      workflowTitle,
+      status: session.status,
+      current: null,
+      scope: next.scope,
+      done: next.done,
+      next: next.next,
+      statePath: service.statePath
+    });
+  }
+  return [
+    `session: ${session.key}`,
+    `workflow: ${session.workflowId}  ${workflowTitle}`,
+    `status: ${session.status}`,
+    "",
+    formatNext(next)
+  ].join(`
+`);
+}
+function cmdLog(service, input) {
+  const key = requireString(input.key, "key");
+  const node = requireString(input.node, "node");
+  const { session, step, next } = service.log(key, node);
+  if (input.json) {
+    return toJson({
+      step,
+      state: session,
+      done: next.done,
+      next: next.next,
+      statePath: service.statePath
+    });
+  }
+  const origin = step.from ? `  (from ${step.from}${step.edge ? ` via ${step.edge}` : ""})` : "  (entry)";
+  return [
+    `logged: #${step.seq} ${step.node}${origin}`,
+    `scope: ${formatScope(step.scope)}   status: ${session.status}`,
+    "",
+    formatNext(next)
+  ].join(`
+`);
+}
+function cmdNext(service, input) {
+  const key = requireString(input.key, "key");
+  const { session, next } = service.next(key);
+  if (input.json) {
+    return toJson({
+      key,
+      workflowId: session.workflowId,
+      status: session.status,
+      current: next.current === null ? null : { node: next.current, title: next.currentTitle, at: session.updatedAt },
+      scope: next.scope,
+      done: next.done,
+      next: next.next,
+      statePath: service.statePath
+    });
+  }
+  return [formatCurrent(next), "", formatNext(next)].join(`
+`);
+}
+function cmdSteps(service, input) {
+  const key = requireString(input.key, "key");
+  const { session, steps } = service.steps(key, { limit: input.limit, after: input.after });
+  if (input.json) {
+    return toJson({
+      key,
+      workflowId: session.workflowId,
+      status: session.status,
+      current: session.current,
+      scope: session.stack.map((frame) => frame.workflowId),
+      steps,
+      statePath: service.statePath
+    });
+  }
+  const head = [
+    `session: ${key}   status: ${session.status}   current: ${session.current ?? "(not started)"}`,
+    `scope: ${formatScope(session.stack.map((frame) => frame.workflowId))}`,
+    ""
+  ].join(`
+`);
+  if (steps.length === 0)
+    return `${head}no steps yet`;
+  const rows = steps.map((step) => [
+    String(step.seq),
+    step.node,
+    step.edge ?? "-",
+    step.from ?? "-",
+    formatScope(step.scope),
+    formatTime(step.at)
+  ]);
+  return head + table(["SEQ", "NODE", "EDGE", "FROM", "SCOPE", "AT"], rows);
+}
+function cmdKeys(service, input) {
+  const sessions = service.keys(input.workflowId);
+  if (input.json) {
+    return toJson({ statePath: service.statePath, sessions });
+  }
+  const head = `state: ${service.statePath}
+`;
+  if (sessions.length === 0)
+    return `${head}no sessions`;
+  const rows = sessions.map((session) => [
+    session.key,
+    session.workflowId,
+    session.status,
+    session.current ?? "-",
+    formatTime(session.updatedAt)
+  ]);
+  return head + table(["KEY", "WORKFLOW", "STATUS", "CURRENT", "UPDATED"], rows);
+}
+function cmdReset(service, input) {
+  const key = requireString(input.key, "key");
+  const result = service.reset(key);
+  if (input.json) {
+    return toJson({ ...result, statePath: service.statePath });
+  }
+  return `reset: ${result.key} (${result.deletedSteps} steps deleted)`;
+}
+
+// src/commands/shared.ts
+function usageError2(message) {
+  return new AppError("usage", message, 2);
+}
+function optionalInt(value, flag) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    throw usageError2(`--${flag} must be a non-negative integer`);
+  }
+  return Number(value);
+}
+function toJson2(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+// src/commands/viz.ts
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var require2 = createRequire(import.meta.url);
+function findTemplate() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0;depth < 6; depth++) {
+    const candidate = join(dir, "viz", "template.html");
+    if (existsSync(candidate))
+      return candidate;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  throw new AppError("viz_template_missing", "could not find viz/template.html next to the package", 3);
+}
+function renderVizHtml(template, workflows) {
+  const order = Object.keys(workflows).sort();
+  const data = JSON.stringify({ workflows, order }).replaceAll("<", "\\u003c");
+  return template.replace("__WORKFLOW_DATA__", data);
+}
+function startVizServer(registry, port) {
+  const template = readFileSync(findTemplate(), "utf8");
+  const cytoscapeJs = readFileSync(require2.resolve("cytoscape/dist/cytoscape.min.js"), "utf8");
+  const dagreJs = readFileSync(require2.resolve("cytoscape-dagre"), "utf8");
+  const workflows = {};
+  for (const workflow of registry.values())
+    workflows[workflow.id] = workflow;
+  const html = renderVizHtml(template, workflows);
+  const server = createServer((request, response) => {
+    const path = (request.url ?? "/").split("?")[0];
+    if (path === "/" || path === "/index.html") {
+      response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      response.end(html);
+      return;
+    }
+    if (path === "/vendor/cytoscape.min.js") {
+      response.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8" });
+      response.end(cytoscapeJs);
+      return;
+    }
+    if (path === "/vendor/cytoscape-dagre.js") {
+      response.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8" });
+      response.end(dagreJs);
+      return;
+    }
+    response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    response.end("not found");
+  });
+  server.on("error", (error) => {
+    console.error(`viz: ${error.message}`);
+    process.exitCode = 1;
+  });
+  server.listen(port, "127.0.0.1");
+  return { url: `http://127.0.0.1:${port}`, workflows: Object.keys(workflows).sort() };
+}
+
+// src/commands/workflow.ts
+import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/workflow/validate.ts
+import { z } from "zod";
+var nodeSchema = z.object({
+  id: z.string().min(1),
+  type: z.enum(["node", "subgraph"]),
+  title: z.string().min(1),
+  description: z.string(),
+  workflow: z.string().min(1).optional()
+}).strict();
+var edgeSchema = z.object({
+  id: z.string().min(1),
+  from: z.string().min(1),
+  to: z.string().min(1),
+  description: z.string(),
+  condition: z.string().min(1).optional()
+}).strict();
+var workflowSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  start: z.string().min(1),
+  nodes: z.array(nodeSchema).min(1),
+  edges: z.array(edgeSchema)
+}).strict();
+function validateWorkflow(raw, source) {
+  const errors = [];
+  const warnings = [];
+  const report = (message) => {
+    errors.push(`${source}: ${message}`);
+  };
+  const parsed = workflowSchema.safeParse(raw);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      const path = issue.path.length > 0 ? `.${issue.path.join(".")}` : "";
+      report(`${path} ${issue.message}`.trim());
+    }
+    return { errors, warnings };
+  }
+  const wf = parsed.data;
+  const nodes = new Map;
+  for (const node of wf.nodes) {
+    if (node.id === END) {
+      report(`node id "${END}" is reserved; point an edge at END instead`);
+    }
+    if (nodes.has(node.id)) {
+      report(`duplicate node id "${node.id}"`);
+    }
+    nodes.set(node.id, node);
+    if (node.type === "subgraph") {
+      if (!node.workflow) {
+        report(`subgraph node "${node.id}" needs a "workflow" field`);
+      } else if (node.workflow === wf.id) {
+        report(`subgraph node "${node.id}" references its own workflow "${wf.id}"`);
+      }
+    } else if (node.workflow) {
+      report(`node "${node.id}" is not a subgraph but has a "workflow" field`);
+    }
+  }
+  if (wf.start === END) {
+    report(`start must be a node, not END`);
+  } else if (!nodes.has(wf.start)) {
+    report(`start "${wf.start}" is not a node`);
+  }
+  const edgeIds = new Set;
+  const pairs = new Set;
+  for (const edge of wf.edges) {
+    if (edgeIds.has(edge.id)) {
+      report(`duplicate edge id "${edge.id}"`);
+    }
+    edgeIds.add(edge.id);
+    const pair = `${edge.from} -> ${edge.to}`;
+    if (pairs.has(pair)) {
+      report(`duplicate edge ${pair}; transitions must be unambiguous`);
+    }
+    pairs.add(pair);
+    if (!nodes.has(edge.from)) {
+      report(`edge "${edge.id}" starts at unknown node "${edge.from}"`);
+    }
+    if (edge.to !== END && !nodes.has(edge.to)) {
+      report(`edge "${edge.id}" targets unknown node "${edge.to}" (use END to finish)`);
+    }
+  }
+  for (const node of wf.nodes) {
+    if (!wf.edges.some((edge) => edge.from === node.id)) {
+      report(`node "${node.id}" has no outgoing edge (add one to END if it is the last step)`);
+    }
+  }
+  if (!wf.edges.some((edge) => edge.to === END)) {
+    report(`workflow "${wf.id}" has no edge to END`);
+  }
+  if (errors.length === 0) {
+    const reachable = new Set([wf.start]);
+    const queue = [wf.start];
+    while (queue.length > 0) {
+      const id = queue.shift();
+      for (const edge of wf.edges) {
+        if (edge.from !== id)
+          continue;
+        if (edge.to === END || reachable.has(edge.to))
+          continue;
+        reachable.add(edge.to);
+        queue.push(edge.to);
+      }
+    }
+    for (const node of wf.nodes) {
+      if (!reachable.has(node.id)) {
+        warnings.push(`${source}: node "${node.id}" is unreachable from start "${wf.start}"`);
+      }
+    }
+    const canFinish = new Set;
+    for (const edge of wf.edges) {
+      if (edge.to === END)
+        canFinish.add(edge.from);
+    }
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const edge of wf.edges) {
+        if (edge.to === END)
+          continue;
+        if (!canFinish.has(edge.to) || canFinish.has(edge.from))
+          continue;
+        canFinish.add(edge.from);
+        grew = true;
+      }
+    }
+    for (const node of wf.nodes) {
+      if (!canFinish.has(node.id)) {
+        warnings.push(`${source}: node "${node.id}" cannot reach END`);
+      }
+    }
+  }
+  return { workflow: wf, errors, warnings };
+}
+function outgoingEdges(wf, nodeId) {
+  return wf.edges.filter((edge) => edge.from === nodeId);
+}
+function onlyEnd(wf, nodeId) {
+  const out = outgoingEdges(wf, nodeId);
+  return out.length === 1 && out[0].to === END;
+}
+
+// src/workflow/load.ts
+function requireWorkflow(workflows, id) {
+  const workflow = workflows.get(id);
+  if (!workflow) {
+    throw new AppError("workflow_not_found", `workflow "${id}" not found in ./workflows`, 3, {
+      available: [...workflows.keys()].sort()
+    });
+  }
+  return workflow;
+}
+
+// src/commands/workflow.ts
+var ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function skeleton(id) {
+  return {
+    id,
+    title: id,
+    start: "start",
+    nodes: [
+      {
+        id: "start",
+        type: "node",
+        title: "Start",
+        description: "Describe the first step."
+      }
+    ],
+    edges: [
+      {
+        id: "e1",
+        from: "start",
+        to: END,
+        description: "Done."
+      }
+    ]
+  };
+}
+function cmdWorkflowNew(workflowsDir, id, json) {
+  if (!id)
+    throw usageError("workflow id is required: next-steps workflow new <id>");
+  if (!ID_PATTERN.test(id)) {
+    throw usageError(`invalid workflow id "${id}"; use A-Z a-z 0-9 . _ - (max 64)`);
+  }
+  const file = join2(workflowsDir, `${id}.json`);
+  if (existsSync2(file)) {
+    throw usageError(`workflow file already exists: ${file}`);
+  }
+  mkdirSync(workflowsDir, { recursive: true });
+  writeFileSync(file, `${JSON.stringify(skeleton(id), null, 2)}
+`, "utf8");
+  if (json)
+    return toJson({ created: file, workflowId: id });
+  return `created: ${file}`;
+}
+function cmdWorkflowList(load, json) {
+  if (json) {
+    return toJson({
+      dir: load.dir,
+      workflows: load.reports.map((report) => ({
+        file: report.file,
+        id: report.id,
+        title: report.title,
+        nodes: report.nodes,
+        edges: report.edges,
+        valid: report.valid,
+        errors: report.errors
+      })),
+      errors: load.errors,
+      warnings: load.warnings
+    });
+  }
+  if (load.reports.length === 0) {
+    return `no workflows in ${load.dir} (run "next-steps workflow new <id>")`;
+  }
+  const rows = load.reports.map((report) => [
+    report.id,
+    report.title,
+    String(report.nodes),
+    String(report.edges),
+    report.valid ? "ok" : "invalid"
+  ]);
+  const body = table(["ID", "TITLE", "NODES", "EDGES", "STATUS"], rows);
+  const failures = load.reports.filter((report) => !report.valid);
+  if (failures.length === 0)
+    return body;
+  const details = failures.flatMap((report) => report.errors.map((error) => `  ${error}`));
+  return `${body}
+
+invalid:
+${details.join(`
+`)}`;
+}
+function findReport(load, id) {
+  if (!id)
+    throw usageError("workflow id is required");
+  const report = load.reports.find((candidate) => candidate.id === id);
+  if (!report) {
+    throw new AppError("workflow_not_found", `workflow "${id}" not found in ${load.dir}`, 3, {
+      available: load.reports.map((candidate) => candidate.id).sort()
+    });
+  }
+  return report;
+}
+function cmdWorkflowShow(load, id, json) {
+  const report = findReport(load, id);
+  if (!report.valid) {
+    throw new AppError("invalid_workflow", `workflow "${report.id}" is invalid`, 5, {
+      errors: report.errors
+    });
+  }
+  const wf = requireWorkflow(load.registry, report.id);
+  if (json)
+    return toJson({ workflow: wf, warnings: report.warnings });
+  const nodeRows = wf.nodes.map((node) => [
+    node.id,
+    node.type,
+    node.type === "subgraph" ? `${node.title} -> ${node.workflow ?? "?"}` : node.title
+  ]);
+  const edgeRows = wf.edges.map((edge) => [
+    edge.id,
+    `${edge.from} -> ${edge.to}`,
+    edge.condition ? `${edge.description}  [when: ${edge.condition}]` : edge.description
+  ]);
+  const indent = (block) => block.split(`
+`).map((line) => `  ${line}`).join(`
+`);
+  return [
+    `${wf.id}  ${wf.title}`,
+    `start: ${wf.start}`,
+    "",
+    "nodes:",
+    indent(table(["ID", "TYPE", "TITLE"], nodeRows)),
+    "",
+    "edges:",
+    indent(table(["ID", "TRANSITION", "DESCRIPTION"], edgeRows))
+  ].join(`
+`);
+}
+function cmdWorkflowCheck(load, id, json) {
+  const reports = id ? [findReport(load, id)] : load.reports;
+  const errors = reports.flatMap((report) => report.errors);
+  const warnings = reports.flatMap((report) => report.warnings);
+  if (errors.length > 0) {
+    throw new AppError("invalid_workflow", "workflow validation failed", 5, { errors });
+  }
+  if (json) {
+    return toJson({
+      ok: true,
+      workflows: reports.map((report) => ({
+        id: report.id,
+        title: report.title,
+        nodes: report.nodes,
+        edges: report.edges
+      })),
+      warnings
+    });
+  }
+  if (reports.length === 0) {
+    return `no workflows in ${load.dir}`;
+  }
+  const lines = reports.map((report) => `ok: ${report.id}  (${report.nodes} nodes, ${report.edges} edges)`);
+  for (const warning of warnings)
+    lines.push(`warning: ${warning}`);
+  return lines.join(`
+`);
+}
+
+// src/workflow/graph.ts
+function getNode(wf, id) {
+  return wf.nodes.find((node) => node.id === id);
+}
+function effectiveStack(lookup, stack) {
+  const frames = stack.map((frame) => ({ ...frame }));
+  while (frames.length > 1) {
+    const top = frames[frames.length - 1];
+    if (!top || top.nodeId === null)
+      break;
+    const wf = lookup.get(top.workflowId);
+    if (!wf || !onlyEnd(wf, top.nodeId))
+      break;
+    frames.pop();
+  }
+  return frames;
+}
+function computeNext(lookup, session) {
+  if (session.status === "done") {
+    return {
+      done: true,
+      current: session.current,
+      currentTitle: null,
+      scope: session.stack.map((frame) => frame.workflowId),
+      next: []
+    };
+  }
+  const frames = effectiveStack(lookup, session.stack);
+  const scope = frames.map((frame) => frame.workflowId);
+  const top = frames[frames.length - 1];
+  if (!top) {
+    return { done: true, current: null, currentTitle: null, scope, next: [] };
+  }
+  const wf = lookup.get(top.workflowId);
+  if (!wf) {
+    return { done: true, current: null, currentTitle: null, scope, next: [] };
+  }
+  if (top.nodeId === null) {
+    const entry = getNode(wf, wf.start);
+    return {
+      done: false,
+      current: null,
+      currentTitle: null,
+      scope,
+      next: [
+        {
+          edge: null,
+          node: wf.start,
+          title: entry?.title ?? wf.start,
+          description: entry?.description ?? ""
+        }
+      ]
+    };
+  }
+  const node = getNode(wf, top.nodeId);
+  if (onlyEnd(wf, top.nodeId)) {
+    return {
+      done: true,
+      current: top.nodeId,
+      currentTitle: node?.title ?? null,
+      scope,
+      next: []
+    };
+  }
+  const next = outgoingEdges(wf, top.nodeId).map((edge) => {
+    if (edge.to === END) {
+      return {
+        edge: edge.id,
+        node: END,
+        title: "finish",
+        description: edge.description,
+        ...edge.condition ? { condition: edge.condition } : {}
+      };
+    }
+    const target = getNode(wf, edge.to);
+    return {
+      edge: edge.id,
+      node: edge.to,
+      title: target?.title ?? edge.to,
+      description: edge.description,
+      ...edge.condition ? { condition: edge.condition } : {}
+    };
+  });
+  return {
+    done: false,
+    current: top.nodeId,
+    currentTitle: node?.title ?? null,
+    scope,
+    next
+  };
+}
+
+// src/runs/service.ts
+var KEY_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+var MAX_DEPTH = 16;
+function legalOptions(wf, current) {
+  if (current === null) {
+    const entry = getNode(wf, wf.start);
+    return [{ edge: null, node: wf.start, description: entry?.description ?? "" }];
+  }
+  return outgoingEdges(wf, current).map((edge) => ({
+    edge: edge.id,
+    node: edge.to,
+    description: edge.description
+  }));
+}
+function invalidTransition(wf, current, node, scope) {
+  return new AppError("invalid_transition", `cannot move to "${node}" from "${current ?? "(start)"}" in workflow "${wf.id}"`, 4, { current, node, scope, legal: legalOptions(wf, current) });
+}
+function keyNotFound(key) {
+  return new AppError("key_not_found", `session "${key}" does not exist`, 3);
+}
+
+class SessionService {
+  registry;
+  store;
+  constructor(registry, store) {
+    this.registry = registry;
+    this.store = store;
+  }
+  get statePath() {
+    return this.store.path;
+  }
+  create(input) {
+    const workflow = requireWorkflow(this.registry, input.workflowId);
+    const key = (input.key ?? "").trim() || crypto.randomUUID();
+    if (!KEY_PATTERN.test(key)) {
+      throw new AppError("key_invalid", `key "${key}" is invalid; use 1-128 characters from A-Z a-z 0-9 . _ -`, 2);
+    }
+    const now = new Date().toISOString();
+    const session = {
+      key,
+      workflowId: workflow.id,
+      status: "running",
+      current: null,
+      stack: [{ workflowId: workflow.id, nodeId: null }],
+      version: 0,
+      createdAt: now,
+      updatedAt: now
+    };
+    if (!this.store.createSession(session)) {
+      throw new AppError("key_exists", `session "${key}" already exists`, 2, { key });
+    }
+    return {
+      session,
+      workflowTitle: workflow.title,
+      next: computeNext(this.registry, session)
+    };
+  }
+  log(key, node) {
+    return this.store.transaction(() => {
+      const session = this.requireSession(key);
+      if (session.status === "done") {
+        throw new AppError("invalid_transition", `session "${key}" is already done`, 4, {
+          current: END,
+          node,
+          legal: []
+        });
+      }
+      const frames = effectiveStack(this.registry, session.stack);
+      const top = frames[frames.length - 1];
+      if (!top) {
+        throw new AppError("invalid_transition", `session "${key}" has no active scope`, 4);
+      }
+      const wf = requireWorkflow(this.registry, top.workflowId);
+      const scope = frames.map((frame) => frame.workflowId);
+      const now = new Date().toISOString();
+      const stack = frames.map((frame) => ({ ...frame }));
+      let stepInput;
+      let current;
+      let endsRun = false;
+      if (node === END) {
+        if (top.nodeId === null)
+          throw invalidTransition(wf, top.nodeId, node, scope);
+        const edge = outgoingEdges(wf, top.nodeId).find((candidate) => candidate.to === END);
+        if (!edge)
+          throw invalidTransition(wf, top.nodeId, node, scope);
+        stepInput = {
+          key,
+          node: END,
+          from: top.nodeId,
+          edge: edge.id,
+          workflowId: top.workflowId,
+          scope,
+          at: now
+        };
+        if (stack.length === 1) {
+          current = END;
+          endsRun = true;
+        } else {
+          stack.pop();
+          current = stack[stack.length - 1]?.nodeId ?? null;
+        }
+      } else {
+        const target = getNode(wf, node);
+        if (!target) {
+          throw new AppError("unknown_node", `node "${node}" does not exist in workflow "${wf.id}"`, 4, { legal: legalOptions(wf, top.nodeId) });
+        }
+        let edge = null;
+        if (top.nodeId === null) {
+          if (node !== wf.start)
+            throw invalidTransition(wf, top.nodeId, node, scope);
+        } else {
+          const found = outgoingEdges(wf, top.nodeId).find((candidate) => candidate.to === node);
+          if (!found)
+            throw invalidTransition(wf, top.nodeId, node, scope);
+          edge = found;
+        }
+        const last = stack[stack.length - 1];
+        if (last)
+          last.nodeId = node;
+        if (target.type === "subgraph") {
+          if (stack.length >= MAX_DEPTH) {
+            throw new AppError("max_depth_exceeded", `subgraph nesting exceeded ${MAX_DEPTH} levels`, 4, { scope });
+          }
+          const child = requireWorkflow(this.registry, target.workflow);
+          stack.push({ workflowId: child.id, nodeId: null });
+        }
+        current = node;
+        stepInput = {
+          key,
+          node,
+          from: top.nodeId,
+          edge: edge?.id ?? null,
+          workflowId: top.workflowId,
+          scope,
+          at: now
+        };
+      }
+      session.stack = stack;
+      session.current = current;
+      session.status = endsRun ? "done" : "running";
+      session.version += 1;
+      session.updatedAt = now;
+      const next = this.settle(session);
+      const step = this.store.appendStep(stepInput);
+      this.store.updateSession(session);
+      return { session, step, next };
+    });
+  }
+  next(key) {
+    const session = this.requireSession(key);
+    return { session, next: computeNext(this.registry, session) };
+  }
+  steps(key, query = {}) {
+    const session = this.requireSession(key);
+    return { session, steps: this.store.listSteps(key, query) };
+  }
+  keys(workflowId) {
+    if (workflowId)
+      requireWorkflow(this.registry, workflowId);
+    return this.store.listSessions(workflowId);
+  }
+  reset(key) {
+    this.requireSession(key);
+    return { key, deletedSteps: this.store.reset(key) };
+  }
+  settle(session) {
+    const next = computeNext(this.registry, session);
+    if (!next.done)
+      return next;
+    session.status = "done";
+    session.current = END;
+    return computeNext(this.registry, session);
+  }
+  requireSession(key) {
+    const session = this.store.getSession(key);
+    if (!session)
+      throw keyNotFound(key);
+    return session;
+  }
+}
+
+// src/runs/store.ts
+import { mkdirSync as mkdirSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+
+// src/runs/driver.ts
+import { createRequire as createRequire2 } from "node:module";
+
+class BunDriver {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  exec(sql) {
+    this.db.exec(sql);
+  }
+  run(sql, params) {
+    return Number(this.db.run(sql, params).changes);
+  }
+  get(sql, params) {
+    return this.db.query(sql).get(...params) ?? null;
+  }
+  all(sql, params) {
+    return this.db.query(sql).all(...params);
+  }
+  transaction(fn) {
+    return this.db.transaction(fn)();
+  }
+  close() {
+    this.db.close();
+  }
+}
+
+class NodeDriver {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  exec(sql) {
+    this.db.exec(sql);
+  }
+  run(sql, params) {
+    return Number(this.db.prepare(sql).run(...params).changes);
+  }
+  get(sql, params) {
+    return this.db.prepare(sql).get(...params) ?? null;
+  }
+  all(sql, params) {
+    return this.db.prepare(sql).all(...params);
+  }
+  transaction(fn) {
+    this.db.exec("BEGIN");
+    try {
+      const result = fn();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+  close() {
+    this.db.close();
+  }
+}
+function openDriver(path) {
+  const load = createRequire2(import.meta.url);
+  if ("bun" in process.versions) {
+    const { Database } = load("bun:sqlite");
+    return new BunDriver(new Database(path, { create: true }));
+  }
+  const { DatabaseSync } = load("node:sqlite");
+  return new NodeDriver(new DatabaseSync(path));
+}
+
+// src/runs/store.ts
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS runs (
+  key         TEXT PRIMARY KEY,
+  workflow_id TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  current     TEXT,
+  stack       TEXT NOT NULL,
+  version     INTEGER NOT NULL DEFAULT 0,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS steps (
+  key         TEXT NOT NULL REFERENCES runs(key) ON DELETE CASCADE,
+  seq         INTEGER NOT NULL,
+  node        TEXT NOT NULL,
+  from_node   TEXT,
+  edge        TEXT,
+  workflow_id TEXT NOT NULL,
+  scope       TEXT NOT NULL,
+  at          TEXT NOT NULL,
+  PRIMARY KEY (key, seq)
+);
+`;
+function toSession(row) {
+  return {
+    key: row.key,
+    workflowId: row.workflow_id,
+    status: row.status,
+    current: row.current,
+    stack: JSON.parse(row.stack),
+    version: row.version,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function toStep(row) {
+  return {
+    key: row.key,
+    seq: row.seq,
+    node: row.node,
+    from: row.from_node,
+    edge: row.edge,
+    workflowId: row.workflow_id,
+    scope: JSON.parse(row.scope),
+    at: row.at
+  };
+}
+
+class SqliteRunStore {
+  path;
+  db;
+  constructor(path) {
+    this.path = path;
+    if (path !== ":memory:") {
+      mkdirSync2(dirname2(path), { recursive: true });
+    }
+    this.db = openDriver(path);
+    this.db.exec("PRAGMA foreign_keys = ON;");
+    this.db.exec("PRAGMA busy_timeout = 5000;");
+    if (path !== ":memory:") {
+      this.db.exec("PRAGMA journal_mode = WAL;");
+    }
+    this.db.exec(SCHEMA);
+  }
+  createSession(session) {
+    return this.db.run(`INSERT OR IGNORE INTO runs
+           (key, workflow_id, status, current, stack, version, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+      session.key,
+      session.workflowId,
+      session.status,
+      session.current,
+      JSON.stringify(session.stack),
+      session.version,
+      session.createdAt,
+      session.updatedAt
+    ]) > 0;
+  }
+  getSession(key) {
+    const row = this.db.get("SELECT * FROM runs WHERE key = ?", [key]);
+    return row ? toSession(row) : null;
+  }
+  updateSession(session) {
+    this.db.run(`UPDATE runs
+          SET status = ?, current = ?, stack = ?, version = ?, updated_at = ?
+        WHERE key = ?`, [
+      session.status,
+      session.current,
+      JSON.stringify(session.stack),
+      session.version,
+      session.updatedAt,
+      session.key
+    ]);
+  }
+  appendStep(step) {
+    const row = this.db.get("SELECT COALESCE(MAX(seq), 0) + 1 AS next FROM steps WHERE key = ?", [
+      step.key
+    ]);
+    const seq = row?.next ?? 1;
+    this.db.run(`INSERT INTO steps (key, seq, node, from_node, edge, workflow_id, scope, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+      step.key,
+      seq,
+      step.node,
+      step.from,
+      step.edge,
+      step.workflowId,
+      JSON.stringify(step.scope),
+      step.at
+    ]);
+    return { ...step, seq };
+  }
+  listSteps(key, query = {}) {
+    const limit = Math.min(Math.max(query.limit ?? 50, 1), 500);
+    const after = Math.max(query.after ?? 0, 0);
+    const rows = this.db.all("SELECT * FROM steps WHERE key = ? AND seq > ? ORDER BY seq ASC LIMIT ?", [key, after, limit]);
+    return rows.map(toStep);
+  }
+  listSessions(workflowId) {
+    const rows = workflowId ? this.db.all("SELECT * FROM runs WHERE workflow_id = ? ORDER BY updated_at DESC", [
+      workflowId
+    ]) : this.db.all("SELECT * FROM runs ORDER BY updated_at DESC", []);
+    return rows.map(toSession);
+  }
+  reset(key) {
+    const count = this.db.get("SELECT COUNT(*) AS n FROM steps WHERE key = ?", [key]);
+    this.db.run("DELETE FROM runs WHERE key = ?", [key]);
+    return count?.n ?? 0;
+  }
+  transaction(fn) {
+    return this.db.transaction(fn);
+  }
+  close() {
+    this.db.close();
+  }
+}
+
+// src/types.ts
+class AppError2 extends Error {
+  code;
+  exitCode;
+  details;
+  constructor(code, message, exitCode = 1, details) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+    this.name = "AppError";
+  }
+}
+
+// src/workflow/load.ts
+import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+function rawId(raw) {
+  return typeof raw === "object" && raw !== null && typeof raw.id === "string" ? raw.id : "(invalid)";
+}
+function loadWorkflows(dir) {
+  const registry = new Map;
+  const reports = [];
+  if (!existsSync3(dir)) {
+    const message = `workflow directory not found: ${dir} (run "next-steps workflow new <id>")`;
+    return { dir, registry, reports, errors: [message], warnings: [] };
+  }
+  const parsed = [];
+  for (const file of readdirSync(dir).filter((name) => name.endsWith(".json")).sort()) {
+    const path = join3(dir, file);
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync2(path, "utf8"));
+    } catch (error) {
+      const message = `${file}: invalid JSON (${error instanceof Error ? error.message : String(error)})`;
+      reports.push({
+        file,
+        id: "(unreadable)",
+        title: "",
+        nodes: 0,
+        edges: 0,
+        valid: false,
+        errors: [message],
+        warnings: []
+      });
+      continue;
+    }
+    const check = validateWorkflow(raw, file);
+    if (check.workflow) {
+      parsed.push({
+        file,
+        workflow: check.workflow,
+        errors: check.errors,
+        warnings: check.warnings
+      });
+    } else {
+      reports.push({
+        file,
+        id: rawId(raw),
+        title: "",
+        nodes: 0,
+        edges: 0,
+        valid: false,
+        errors: check.errors,
+        warnings: check.warnings
+      });
+    }
+  }
+  const byId = new Map;
+  for (const entry of parsed) {
+    const group = byId.get(entry.workflow.id) ?? [];
+    group.push(entry);
+    byId.set(entry.workflow.id, group);
+  }
+  for (const [id, group] of byId) {
+    if (group.length < 2)
+      continue;
+    const message = `workflow id "${id}" is defined in more than one file: ${group.map((entry) => entry.file).join(", ")}`;
+    for (const entry of group)
+      entry.errors.push(message);
+  }
+  const knownIds = new Set(parsed.map((entry) => entry.workflow.id));
+  for (const entry of parsed) {
+    for (const node of entry.workflow.nodes) {
+      if (node.type !== "subgraph" || !node.workflow)
+        continue;
+      if (!knownIds.has(node.workflow)) {
+        entry.errors.push(`${entry.file}: subgraph node "${node.id}" references unknown workflow "${node.workflow}"`);
+      }
+    }
+  }
+  for (const entry of parsed) {
+    const valid = entry.errors.length === 0;
+    reports.push({
+      file: entry.file,
+      id: entry.workflow.id,
+      title: entry.workflow.title,
+      nodes: entry.workflow.nodes.length,
+      edges: entry.workflow.edges.length,
+      valid,
+      errors: entry.errors,
+      warnings: entry.warnings
+    });
+    if (valid)
+      registry.set(entry.workflow.id, entry.workflow);
+  }
+  return {
+    dir,
+    registry,
+    reports,
+    errors: reports.flatMap((report) => report.errors),
+    warnings: reports.flatMap((report) => report.warnings)
+  };
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var HELP = `next-steps \u2014 record the current step, ask what comes next
+
+usage:
+  next-steps create  --workflow <id> [--key <key>] [--json]
+  next-steps log     --key <key> --node <node> [--json]
+  next-steps next    --key <key> [--json]
+  next-steps steps   --key <key> [--limit <n>] [--after <seq>] [--json]
+  next-steps keys    [--workflow <id>] [--json]
+  next-steps reset   --key <key> [--json]
+
+  next-steps workflow new <id> [--json]
+  next-steps workflow list [--json]
+  next-steps workflow show <id> [--json]
+  next-steps workflow check [id] [--json]
+
+  next-steps viz [--port <n>] [--json]   (serve a graph viewer on a local port)
+
+  next-steps help
+  next-steps version
+
+state:   ./.next-steps/state.db   (created on first use, gitignored)
+graphs:  ./workflows/*.json
+
+exit codes:
+  0 ok   2 usage   3 not found   4 invalid transition   5 invalid workflow`;
+function parseOptions(args, options, allowPositionals = false) {
+  try {
+    return parseArgs({ args, options, allowPositionals, strict: true });
+  } catch (error) {
+    throw usageError2(error instanceof Error ? error.message : String(error));
+  }
+}
+function asString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function requireRegistry(workflowsDir) {
+  const load = loadWorkflows(workflowsDir);
+  if (load.errors.length > 0) {
+    throw new AppError2("invalid_workflow", "workflow files are invalid", 5, {
+      errors: load.errors
+    });
+  }
+  return load.registry;
+}
+function execute(argv, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const workflowsDir = options.workflowsDir ?? join4(cwd, "workflows");
+  const dbPath = options.dbPath ?? join4(cwd, ".next-steps", "state.db");
+  const [command, ...rest] = argv;
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    return HELP;
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    return `next-steps ${VERSION}`;
+  }
+  if (command === "workflow") {
+    const { positionals, values } = parseOptions(rest, { json: { type: "boolean" } }, true);
+    const [subcommand, id] = positionals;
+    const json = Boolean(values.json);
+    const load = loadWorkflows(workflowsDir);
+    switch (subcommand) {
+      case "new":
+        return cmdWorkflowNew(workflowsDir, id, json);
+      case "list":
+        return cmdWorkflowList(load, json);
+      case "show":
+        return cmdWorkflowShow(load, id, json);
+      case "check":
+        return cmdWorkflowCheck(load, id, json);
+      default:
+        throw usageError2("usage: next-steps workflow <new|list|show|check> ...");
+    }
+  }
+  if (command === "viz") {
+    const { values } = parseOptions(rest, { port: { type: "string" }, json: { type: "boolean" } });
+    const port = optionalInt(values.port, "port") ?? 3000;
+    if (port < 1 || port > 65535) {
+      throw usageError2("--port must be between 1 and 65535");
+    }
+    const registry2 = requireRegistry(workflowsDir);
+    if (registry2.size === 0) {
+      throw new AppError2("no_workflows", `no workflows in ${workflowsDir}`, 3);
+    }
+    const result = startVizServer(registry2, port);
+    return values.json ? toJson2({ url: result.url, workflows: result.workflows }) : `viewer: ${result.url}
+press Ctrl+C to stop`;
+  }
+  const registry = requireRegistry(workflowsDir);
+  const store = new SqliteRunStore(dbPath);
+  try {
+    const service = new SessionService(registry, store);
+    switch (command) {
+      case "create": {
+        const { values } = parseOptions(rest, {
+          workflow: { type: "string" },
+          key: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdCreate(service, {
+          workflowId: asString(values.workflow),
+          key: asString(values.key),
+          json: Boolean(values.json)
+        });
+      }
+      case "log": {
+        const { values } = parseOptions(rest, {
+          key: { type: "string" },
+          node: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdLog(service, {
+          key: asString(values.key),
+          node: asString(values.node),
+          json: Boolean(values.json)
+        });
+      }
+      case "next": {
+        const { values } = parseOptions(rest, {
+          key: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdNext(service, {
+          key: asString(values.key),
+          json: Boolean(values.json)
+        });
+      }
+      case "steps": {
+        const { values } = parseOptions(rest, {
+          key: { type: "string" },
+          limit: { type: "string" },
+          after: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdSteps(service, {
+          key: asString(values.key),
+          limit: optionalInt(values.limit, "limit"),
+          after: optionalInt(values.after, "after"),
+          json: Boolean(values.json)
+        });
+      }
+      case "keys": {
+        const { values } = parseOptions(rest, {
+          workflow: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdKeys(service, {
+          workflowId: asString(values.workflow),
+          json: Boolean(values.json)
+        });
+      }
+      case "reset": {
+        const { values } = parseOptions(rest, {
+          key: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdReset(service, {
+          key: asString(values.key),
+          json: Boolean(values.json)
+        });
+      }
+      default:
+        throw usageError2(`unknown command "${command}" (try: next-steps help)`);
+    }
+  } finally {
+    store.close();
+  }
+}
+function prettyError(error) {
+  const lines = [`error: ${error.message}`];
+  const details = error.details;
+  if (details) {
+    if (Array.isArray(details.errors)) {
+      for (const message of details.errors)
+        lines.push(`  - ${String(message)}`);
+    }
+    if (Array.isArray(details.legal)) {
+      if (details.legal.length === 0) {
+        lines.push("  no legal next steps");
+      } else {
+        lines.push("  legal next steps:");
+        for (const option of details.legal) {
+          const label = option.edge ? `${option.edge} -> ${option.node}` : option.node;
+          lines.push(`    - ${label}  ${option.description}`);
+        }
+      }
+    }
+    if (Array.isArray(details.available)) {
+      lines.push(`  available: ${details.available.join(", ")}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function formatError(error, json) {
+  if (error instanceof AppError2) {
+    if (json) {
+      return JSON.stringify({
+        error: {
+          code: error.code,
+          message: error.message,
+          ...error.details === undefined ? {} : { details: error.details }
+        }
+      }, null, 2);
+    }
+    return prettyError(error);
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  if (json) {
+    return JSON.stringify({ error: { code: "internal", message } }, null, 2);
+  }
+  return `error: ${message}`;
+}
+async function run(argv, options = {}) {
+  const wantsJson = argv.includes("--json");
+  try {
+    return { exitCode: 0, stdout: execute(argv, options), stderr: "" };
+  } catch (error) {
+    const exitCode = error instanceof AppError2 ? error.exitCode : 1;
+    return { exitCode, stdout: "", stderr: formatError(error, wantsJson) };
+  }
+}
+function isEntrypoint() {
+  const meta = import.meta;
+  if (typeof meta.main === "boolean")
+    return meta.main;
+  const entry = process.argv[1];
+  return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
+}
+if (isEntrypoint()) {
+  const result = await run(process.argv.slice(2));
+  if (result.stdout)
+    process.stdout.write(`${result.stdout}
+`);
+  if (result.stderr)
+    process.stderr.write(`${result.stderr}
+`);
+  process.exitCode = result.exitCode;
+}
+export {
+  run
+};