@wanbicoi/next-steps 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,1174 @@
+#!/usr/bin/env node
+// @bun
+
+// src/cli.ts
+import { existsSync as existsSync3 } from "fs";
+import { basename, join as join2 } 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 formatTime(iso) {
+  return iso.slice(0, 19).replace("T", " ");
+}
+function optionLine(option, index) {
+  const title = option.node === END ? "" : option.title;
+  const review = option.reviewRequired ? "  [review]" : "";
+  const head = `  ${index + 1}. ${option.node}${title ? `  ${title}` : ""}${review}`.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)`;
+  if (next.current === null)
+    return "current: (not started)";
+  const title = next.currentTitle ? `  (${next.currentTitle})` : "";
+  return `current: ${next.current}${title}`;
+}
+
+// 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 { session, workflowTitle, next } = service.create({ key: input.key });
+  if (input.json) {
+    return toJson({
+      key: session.key,
+      workflowId: session.workflowId,
+      workflowTitle,
+      status: session.status,
+      current: null,
+      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})` : "  (entry)";
+  return [
+    `logged: #${step.seq} ${step.node}${origin}`,
+    `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 },
+      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,
+      steps,
+      statePath: service.statePath
+    });
+  }
+  const head = `session: ${key}   status: ${session.status}   current: ${session.current ?? "(not started)"}`;
+  if (steps.length === 0)
+    return `${head}
+
+no steps yet`;
+  const rows = steps.map((step) => [
+    String(step.seq),
+    step.node,
+    step.edge ?? "-",
+    step.from ?? "-",
+    formatTime(step.at)
+  ]);
+  return `${head}
+
+${table(["SEQ", "NODE", "EDGE", "FROM", "AT"], rows)}`;
+}
+function cmdKeys(service, input) {
+  const sessions = service.keys();
+  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, workflow) {
+  const data = JSON.stringify({ workflow }).replaceAll("<", "\\u003c");
+  return template.replace("__WORKFLOW_DATA__", data);
+}
+function startVizServer(workflow, 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 html = renderVizHtml(template, workflow);
+  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}`, workflow: workflow.id };
+}
+
+// src/commands/workflow.ts
+import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+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",
+        title: "Start",
+        description: "Describe the first step.",
+        next: [{ to: END, description: "Done." }]
+      }
+    ]
+  };
+}
+function cmdWorkflowNew(graphPath, id, json) {
+  if (existsSync2(graphPath)) {
+    throw usageError(`workflow file already exists: ${graphPath}`);
+  }
+  const workflowId = ID_PATTERN.test(id) ? id : "workflow";
+  mkdirSync(dirname2(graphPath), { recursive: true });
+  writeFileSync(graphPath, `${JSON.stringify(skeleton(workflowId), null, 2)}
+`, "utf8");
+  if (json)
+    return toJson({ created: graphPath, workflowId });
+  return `created: ${graphPath}`;
+}
+function requireValid(load) {
+  if (load.errors.length > 0 || !load.workflow) {
+    throw new AppError("invalid_workflow", `workflow file is invalid: ${load.path}`, 5, {
+      errors: load.errors
+    });
+  }
+  return load.workflow;
+}
+function cmdWorkflowShow(load, json) {
+  const wf = requireValid(load);
+  if (json)
+    return toJson({ workflow: wf, warnings: load.warnings });
+  const lines = [`${wf.id}  ${wf.title}`, `start: ${wf.start}`];
+  let group;
+  for (const node of wf.nodes) {
+    if (node.group !== group) {
+      group = node.group;
+      if (group)
+        lines.push("", group);
+    }
+    const review = node.reviewRequired ? "  [review]" : "";
+    lines.push(`  ${node.id}  ${node.title}${review}`);
+    for (const move of node.next) {
+      const when = move.condition ? `  [when: ${move.condition}]` : "";
+      lines.push(`    -> ${move.to}  ${move.description}${when}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function cmdWorkflowCheck(load, json) {
+  if (load.errors.length > 0 || !load.workflow) {
+    throw new AppError("invalid_workflow", "workflow validation failed", 5, {
+      errors: load.errors
+    });
+  }
+  const wf = load.workflow;
+  const moves = wf.nodes.reduce((count, node) => count + node.next.length, 0);
+  if (json) {
+    return toJson({
+      ok: true,
+      workflowId: wf.id,
+      title: wf.title,
+      nodes: wf.nodes.length,
+      moves,
+      warnings: load.warnings
+    });
+  }
+  const lines = [`ok: ${wf.id}  (${wf.nodes.length} nodes, ${moves} moves)`];
+  for (const warning of load.warnings)
+    lines.push(`warning: ${warning}`);
+  return lines.join(`
+`);
+}
+
+// src/workflow/validate.ts
+import { z } from "zod";
+var moveSchema = z.object({
+  to: z.string().min(1),
+  description: z.string(),
+  condition: z.string().min(1).optional()
+}).strict();
+var nodeSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+  group: z.string().min(1).optional(),
+  reviewRequired: z.boolean().optional(),
+  next: z.array(moveSchema).min(1)
+}).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)
+}).strict();
+function reportLegacyShape(raw, report) {
+  if (typeof raw !== "object" || raw === null)
+    return;
+  const file = raw;
+  if (Array.isArray(file.edges)) {
+    report(`edges are inline now: move each edge into its node's "next" list`);
+  }
+  if (!Array.isArray(file.nodes))
+    return;
+  for (const node of file.nodes) {
+    if (typeof node !== "object" || node === null)
+      continue;
+    const candidate = node;
+    if (candidate.type === "subgraph") {
+      report(`node "${String(candidate.id)}" is a subgraph: inline its nodes and use "group" for the label`);
+    } else if ("type" in candidate) {
+      report(`node "${String(candidate.id)}" has a "type" field; nodes are flat, drop it`);
+    }
+  }
+}
+function validateWorkflow(raw, source) {
+  const errors = [];
+  const warnings = [];
+  const report = (message) => {
+    errors.push(`${source}: ${message}`);
+  };
+  reportLegacyShape(raw, report);
+  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 a move at END instead`);
+    }
+    if (nodes.has(node.id)) {
+      report(`duplicate node id "${node.id}"`);
+    }
+    nodes.set(node.id, node);
+  }
+  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`);
+  }
+  let reachesEnd = false;
+  for (const node of wf.nodes) {
+    const seen = new Set;
+    for (const move of node.next) {
+      if (move.to === END) {
+        reachesEnd = true;
+      } else if (!nodes.has(move.to)) {
+        report(`move from "${node.id}" targets unknown node "${move.to}" (use END to finish)`);
+      }
+      if (seen.has(move.to)) {
+        report(`duplicate move ${node.id} -> ${move.to}; transitions must be unambiguous`);
+      }
+      seen.add(move.to);
+    }
+  }
+  if (!reachesEnd) {
+    report(`workflow "${wf.id}" has no move 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 move of movesFor(wf, id)) {
+        if (move.to === END || reachable.has(move.to))
+          continue;
+        reachable.add(move.to);
+        queue.push(move.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 node of wf.nodes) {
+      if (node.next.some((move) => move.to === END))
+        canFinish.add(node.id);
+    }
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const node of wf.nodes) {
+        if (canFinish.has(node.id))
+          continue;
+        if (!node.next.some((move) => canFinish.has(move.to)))
+          continue;
+        canFinish.add(node.id);
+        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 movesFor(wf, nodeId) {
+  return wf.nodes.find((node) => node.id === nodeId)?.next ?? [];
+}
+function onlyEnd(wf, nodeId) {
+  const moves = movesFor(wf, nodeId);
+  return moves.length === 1 && moves[0]?.to === END;
+}
+
+// src/workflow/graph.ts
+function getNode(wf, id) {
+  return wf.nodes.find((node) => node.id === id);
+}
+function computeNext(wf, session) {
+  if (session.status === "done") {
+    return { done: true, current: session.current, currentTitle: null, next: [] };
+  }
+  if (session.current === null) {
+    const entry = getNode(wf, wf.start);
+    return {
+      done: false,
+      current: null,
+      currentTitle: null,
+      next: [
+        {
+          edge: null,
+          node: wf.start,
+          title: entry?.title ?? wf.start,
+          description: entry?.description ?? "",
+          reviewRequired: entry?.reviewRequired ?? false
+        }
+      ]
+    };
+  }
+  const node = getNode(wf, session.current);
+  if (onlyEnd(wf, session.current)) {
+    return {
+      done: true,
+      current: session.current,
+      currentTitle: node?.title ?? null,
+      next: []
+    };
+  }
+  const current = session.current;
+  const next = movesFor(wf, current).map((move) => {
+    const edge = `${current}->${move.to}`;
+    if (move.to === END) {
+      return {
+        edge,
+        node: END,
+        title: "finish",
+        description: move.description,
+        ...move.condition ? { condition: move.condition } : {},
+        reviewRequired: false
+      };
+    }
+    const target = getNode(wf, move.to);
+    return {
+      edge,
+      node: move.to,
+      title: target?.title ?? move.to,
+      description: move.description,
+      ...move.condition ? { condition: move.condition } : {},
+      reviewRequired: target?.reviewRequired ?? false
+    };
+  });
+  return {
+    done: false,
+    current,
+    currentTitle: node?.title ?? null,
+    next
+  };
+}
+
+// src/runs/service.ts
+var KEY_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+
+class SessionService {
+  workflow;
+  store;
+  constructor(workflow, store) {
+    this.workflow = workflow;
+    this.store = store;
+  }
+  get statePath() {
+    return this.store.path;
+  }
+  create(input = {}) {
+    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: this.workflow.id,
+      status: "running",
+      current: 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: this.workflow.title,
+      next: computeNext(this.workflow, session)
+    };
+  }
+  log(key, node) {
+    return this.store.transaction(() => {
+      const session = this.requireSession(key);
+      const wf = this.workflow;
+      if (session.status === "done") {
+        throw new AppError("invalid_transition", `session "${key}" is already done`, 4, {
+          current: END,
+          node,
+          legal: []
+        });
+      }
+      const now = new Date().toISOString();
+      const from = session.current;
+      let stepInput;
+      if (node === END) {
+        if (from === null || !movesFor(wf, from).some((move) => move.to === END)) {
+          throw this.invalidTransition(from, node);
+        }
+        stepInput = {
+          key,
+          node: END,
+          from,
+          edge: `${from}->${END}`,
+          workflowId: wf.id,
+          at: now
+        };
+        session.current = END;
+        session.status = "done";
+      } else {
+        const target = getNode(wf, node);
+        if (!target) {
+          throw new AppError("unknown_node", `node "${node}" does not exist in workflow "${wf.id}"`, 4, { legal: this.legalOptions(from) });
+        }
+        let edge = null;
+        if (from === null) {
+          if (node !== wf.start)
+            throw this.invalidTransition(from, node);
+        } else {
+          if (!movesFor(wf, from).some((move) => move.to === node)) {
+            throw this.invalidTransition(from, node);
+          }
+          edge = `${from}->${node}`;
+        }
+        stepInput = { key, node, from, edge, workflowId: wf.id, at: now };
+        session.current = node;
+        if (onlyEnd(wf, node)) {
+          session.current = END;
+          session.status = "done";
+        }
+      }
+      session.version += 1;
+      session.updatedAt = now;
+      const next = computeNext(wf, 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.workflow, session) };
+  }
+  steps(key, query = {}) {
+    const session = this.requireSession(key);
+    return { session, steps: this.store.listSteps(key, query) };
+  }
+  keys() {
+    return this.store.listSessions();
+  }
+  reset(key) {
+    this.requireSession(key);
+    return { key, deletedSteps: this.store.reset(key) };
+  }
+  legalOptions(from) {
+    if (from === null) {
+      const entry = getNode(this.workflow, this.workflow.start);
+      return [{ edge: null, node: this.workflow.start, description: entry?.description ?? "" }];
+    }
+    return movesFor(this.workflow, from).map((move) => ({
+      edge: `${from}->${move.to}`,
+      node: move.to,
+      description: move.description
+    }));
+  }
+  invalidTransition(from, node) {
+    return new AppError("invalid_transition", `cannot move to "${node}" from "${from ?? "(start)"}" in workflow "${this.workflow.id}"`, 4, { current: from, node, legal: this.legalOptions(from) });
+  }
+  requireSession(key) {
+    const session = this.store.getSession(key);
+    if (!session)
+      throw new AppError("key_not_found", `session "${key}" does not exist`, 3);
+    return session;
+  }
+}
+
+// src/runs/store.ts
+import { mkdirSync as mkdirSync2, unlinkSync } from "node:fs";
+import { dirname as dirname3 } 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,
+  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,
+  at          TEXT NOT NULL,
+  PRIMARY KEY (key, seq)
+);
+`;
+var LEGACY_COLUMNS = new Set(["stack", "scope"]);
+function toSession(row) {
+  return {
+    key: row.key,
+    workflowId: row.workflow_id,
+    status: row.status,
+    current: row.current,
+    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,
+    at: row.at
+  };
+}
+
+class SqliteRunStore {
+  path;
+  db;
+  constructor(path) {
+    this.path = path;
+    if (path !== ":memory:") {
+      mkdirSync2(dirname3(path), { recursive: true });
+    }
+    this.db = openDriver(path);
+    if (path !== ":memory:") {
+      if (this.isOutdated())
+        this.recreate(path);
+      this.db.exec("PRAGMA journal_mode = WAL;");
+    }
+    this.db.exec("PRAGMA foreign_keys = ON;");
+    this.db.exec("PRAGMA busy_timeout = 5000;");
+    this.db.exec(SCHEMA);
+  }
+  isOutdated() {
+    const columns = [
+      ...this.db.all("PRAGMA table_info(runs)", []),
+      ...this.db.all("PRAGMA table_info(steps)", [])
+    ];
+    return columns.some((column) => LEGACY_COLUMNS.has(column.name));
+  }
+  recreate(path) {
+    this.db.close();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        unlinkSync(`${path}${suffix}`);
+      } catch {}
+    }
+    this.db = openDriver(path);
+  }
+  createSession(session) {
+    return this.db.run(`INSERT OR IGNORE INTO runs
+           (key, workflow_id, status, current, version, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+      session.key,
+      session.workflowId,
+      session.status,
+      session.current,
+      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 = ?, version = ?, updated_at = ?
+        WHERE key = ?`, [session.status, session.current, 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, at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, [step.key, seq, step.node, step.from, step.edge, step.workflowId, 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() {
+    const rows = 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 { readFileSync as readFileSync2 } from "node:fs";
+function loadWorkflowFile(path) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const missing = error.code === "ENOENT";
+    return {
+      path,
+      errors: [
+        missing ? `workflow file not found: ${path} (run "next-steps workflow new")` : `${path}: invalid JSON (${message})`
+      ],
+      warnings: []
+    };
+  }
+  const check = validateWorkflow(raw, path);
+  return { path, workflow: check.workflow, errors: check.errors, warnings: check.warnings };
+}
+
+// src/cli.ts
+var VERSION = "0.1.1";
+var HELP = `next-steps \u2014 record the current step, ask what comes next
+
+usage:
+  next-steps create  [--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    [--json]
+  next-steps reset   --key <key> [--json]
+
+  next-steps workflow new [--json]
+  next-steps workflow show [--json]
+  next-steps workflow check [--json]
+
+  next-steps viz [--port <n>] [--json]   (serve the graph viewer on a local port)
+
+  next-steps help
+  next-steps version
+
+state:   ./.next-steps/state.db       (created on first use, gitignored)
+graph:   ./.next-steps/workflow.json  (one graph per project, committed)
+
+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 requireGraphFile(graphPath) {
+  if (existsSync3(graphPath))
+    return;
+  throw new AppError2("workflow_not_found", `workflow file not found: ${graphPath} (run "next-steps workflow new")`, 3);
+}
+function requireWorkflow(graphPath) {
+  requireGraphFile(graphPath);
+  const load = loadWorkflowFile(graphPath);
+  if (load.errors.length > 0 || !load.workflow) {
+    throw new AppError2("invalid_workflow", "workflow file is invalid", 5, {
+      errors: load.errors
+    });
+  }
+  return load.workflow;
+}
+function execute(argv, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const graphPath = options.graphPath ?? join2(cwd, ".next-steps", "workflow.json");
+  const dbPath = options.dbPath ?? join2(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] = positionals;
+    const json = Boolean(values.json);
+    if (subcommand === "new") {
+      if (positionals.length > 1)
+        throw usageError2(`unexpected argument "${positionals[1]}"`);
+      return cmdWorkflowNew(graphPath, basename(cwd), json);
+    }
+    if (subcommand !== "show" && subcommand !== "check") {
+      throw usageError2("usage: next-steps workflow <new|show|check> [--json]");
+    }
+    if (positionals.length > 1)
+      throw usageError2(`unexpected argument "${positionals[1]}"`);
+    requireGraphFile(graphPath);
+    const load = loadWorkflowFile(graphPath);
+    return subcommand === "show" ? cmdWorkflowShow(load, json) : cmdWorkflowCheck(load, json);
+  }
+  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 result = startVizServer(requireWorkflow(graphPath), port);
+    return values.json ? toJson2({ url: result.url, workflow: result.workflow }) : `viewer: ${result.url}
+press Ctrl+C to stop`;
+  }
+  const workflow = requireWorkflow(graphPath);
+  const store = new SqliteRunStore(dbPath);
+  try {
+    const service = new SessionService(workflow, store);
+    switch (command) {
+      case "create": {
+        const { values } = parseOptions(rest, {
+          key: { type: "string" },
+          json: { type: "boolean" }
+        });
+        return cmdCreate(service, {
+          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, { json: { type: "boolean" } });
+        return cmdKeys(service, { 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
+};