@wanbicoi/next-steps 0.1.1 → 0.1.2

package/README.md

@@ -92,6 +92,7 @@ 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 agents  [--json]
 
 next-steps workflow new [--json]
 next-steps workflow show [--json]
@@ -106,6 +107,68 @@ documented in `docs/AGENTS.sample.md`.
 `create` only opens a session (the key is the task id; a UUID is generated when
 omitted). It does not author the graph — use `workflow new` for that.
 
+`agents` prints `docs/AGENTS.sample.md`, the playbook an agent reads to drive
+this CLI from another repo. Copy the output into that repo's `AGENTS.md`:
+
+```sh
+next-steps agents > /tmp/agents.md
+```
+
+## Hooks
+
+If `.next-steps/hook` exists and is executable (`chmod +x`), every successful
+`log` runs it after the state is written. Use it to mirror progress into a
+status bar, window title, or agent sidebar. Any language works; a Python hook:
+
+```python
+#!/usr/bin/env python3
+# .next-steps/hook — mirror the state into a status file
+import json
+import sys
+
+payload = json.load(sys.stdin)
+
+if payload["status"] == "done":
+    label = "done"
+elif payload["status"] == "review":
+    label = ", ".join(n["title"] for n in payload["next"] if n["reviewRequired"])
+else:
+    label = " | ".join(n["title"] for n in payload["next"]) or payload["last"]["title"]
+
+with open("/tmp/next-steps-status", "w") as out:
+    out.write(f'{payload["key"]}  {payload["status"]}  {label}\n')
+```
+
+Replace the file write with a call to your status tool (a tmux status line, a
+Herdr sidebar, a file watcher). The hook runs from the project root and inherits
+the normal environment; its stdout and stderr are discarded, so report through
+the tool it drives.
+
+The payload on stdin is a status snapshot, not the full event:
+
+```json
+{
+  "event": "log",
+  "key": "4f1c...",
+  "status": "review",
+  "last": { "id": "read-issue", "title": "Read the issue" },
+  "next": [{ "id": "implement", "title": "Implement", "reviewRequired": true }]
+}
+```
+
+`status` is derived: `done` when the run finished, `review` when any legal next
+node has `reviewRequired`, otherwise `running`. `last` is the node just logged;
+`next` is what the agent may do now. For anything richer (edges, descriptions,
+conditions, history), call `next-steps next --key <key> --json` — the payload
+carries the `key`.
+
+Hooks run synchronously with a five-second timeout. A missing hook is silent; a
+hook that fails, times out, or lacks the execute bit prints a warning to stderr
+and never changes the log's exit code. Only `log` triggers the hook, so a fresh
+session stays quiet until its first node is finished. Commit `.next-steps/hook`
+when the whole team should share the behaviour; leave it untracked for a local
+adapter.
+
 ## Workflow format
 
 ```json

package/dist/cli.js

@@ -2,11 +2,16 @@
 // @bun
 
 // src/cli.ts
-import { existsSync as existsSync3 } from "fs";
-import { basename, join as join2 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { basename, dirname as dirname5, join as join3 } from "path";
 import { pathToFileURL } from "url";
 import { parseArgs } from "util";
 
+// src/commands/agents.ts
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
 // src/types.ts
 var END = "END";
 
@@ -23,6 +28,40 @@ class AppError extends Error {
   }
 }
 
+// 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/agents.ts
+var SAMPLE = join("docs", "AGENTS.sample.md");
+function findSample() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0;depth < 6; depth++) {
+    const candidate = join(dir, SAMPLE);
+    if (existsSync(candidate))
+      return candidate;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  throw new AppError("agents_sample_missing", "could not find docs/AGENTS.sample.md next to the package", 3);
+}
+function cmdAgents(json) {
+  const markdown = readFileSync(findSample(), "utf8");
+  return json ? toJson({ markdown }) : markdown.trimEnd();
+}
+
 // src/format.ts
 function table(headers, rows) {
   const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? "").length)));
@@ -63,20 +102,6 @@ function formatCurrent(next) {
   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 });
@@ -101,10 +126,12 @@ function cmdCreate(service, input) {
   ].join(`
 `);
 }
-function cmdLog(service, input) {
+function cmdLog(service, input, onLogged) {
   const key = requireString(input.key, "key");
   const node = requireString(input.node, "node");
-  const { session, step, next } = service.log(key, node);
+  const result = service.log(key, node);
+  const { session, step, next } = result;
+  onLogged?.(result);
   if (input.json) {
     return toJson({
       step,
@@ -213,19 +240,19 @@ function toJson2(value) {
 }
 
 // src/commands/viz.ts
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
 import { createServer } from "node:http";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 var require2 = createRequire(import.meta.url);
 function findTemplate() {
-  let dir = dirname(fileURLToPath(import.meta.url));
+  let dir = dirname2(fileURLToPath2(import.meta.url));
   for (let depth = 0;depth < 6; depth++) {
-    const candidate = join(dir, "viz", "template.html");
-    if (existsSync(candidate))
+    const candidate = join2(dir, "viz", "template.html");
+    if (existsSync2(candidate))
       return candidate;
-    const parent = dirname(dir);
+    const parent = dirname2(dir);
     if (parent === dir)
       break;
     dir = parent;
@@ -237,9 +264,9 @@ function renderVizHtml(template, workflow) {
   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 template = readFileSync2(findTemplate(), "utf8");
+  const cytoscapeJs = readFileSync2(require2.resolve("cytoscape/dist/cytoscape.min.js"), "utf8");
+  const dagreJs = readFileSync2(require2.resolve("cytoscape-dagre"), "utf8");
   const html = renderVizHtml(template, workflow);
   const server = createServer((request, response) => {
     const path = (request.url ?? "/").split("?")[0];
@@ -270,8 +297,8 @@ function startVizServer(workflow, port) {
 }
 
 // src/commands/workflow.ts
-import { existsSync as existsSync2, mkdirSync, writeFileSync } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { existsSync as existsSync3, mkdirSync, writeFileSync } from "node:fs";
+import { dirname as dirname3 } from "node:path";
 var ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 function skeleton(id) {
   return {
@@ -289,11 +316,11 @@ function skeleton(id) {
   };
 }
 function cmdWorkflowNew(graphPath, id, json) {
-  if (existsSync2(graphPath)) {
+  if (existsSync3(graphPath)) {
     throw usageError(`workflow file already exists: ${graphPath}`);
   }
   const workflowId = ID_PATTERN.test(id) ? id : "workflow";
-  mkdirSync(dirname2(graphPath), { recursive: true });
+  mkdirSync(dirname3(graphPath), { recursive: true });
   writeFileSync(graphPath, `${JSON.stringify(skeleton(workflowId), null, 2)}
 `, "utf8");
   if (json)
@@ -355,6 +382,10 @@ function cmdWorkflowCheck(load, json) {
 `);
 }
 
+// src/runs/hook.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync4, statSync } from "node:fs";
+
 // src/workflow/validate.ts
 import { z } from "zod";
 var moveSchema = z.object({
@@ -560,6 +591,58 @@ function computeNext(wf, session) {
   };
 }
 
+// src/runs/hook.ts
+var TIMEOUT_MS = 5000;
+function isExecutable(path) {
+  try {
+    return (statSync(path).mode & 73) !== 0;
+  } catch {
+    return false;
+  }
+}
+function warn(message) {
+  process.stderr.write(`hook: ${message}
+`);
+}
+function runPostLogHook(config, result) {
+  if (!existsSync4(config.path))
+    return;
+  if (!isExecutable(config.path)) {
+    warn(`${config.path} is not executable (chmod +x)`);
+    return;
+  }
+  const { done, next } = result.next;
+  const review = next.filter((option) => option.reviewRequired);
+  const payload = {
+    event: "log",
+    key: result.session.key,
+    status: done ? "done" : review.length > 0 ? "review" : "running",
+    last: {
+      id: result.step.node,
+      title: getNode(config.workflow, result.step.node)?.title ?? result.step.node
+    },
+    next: next.map((option) => ({
+      id: option.node,
+      title: option.title,
+      reviewRequired: option.reviewRequired
+    }))
+  };
+  const run = spawnSync(config.path, [], {
+    cwd: config.cwd,
+    input: JSON.stringify(payload),
+    encoding: "utf8",
+    timeout: TIMEOUT_MS
+  });
+  if (run.error) {
+    warn(`${config.path} failed: ${run.error.message}`);
+    return;
+  }
+  if (run.status !== 0) {
+    const detail = (run.stderr ?? "").trim();
+    warn(`${config.path} exited ${run.status}${detail ? `: ${detail}` : ""}`);
+  }
+}
+
 // src/runs/service.ts
 var KEY_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
 
@@ -694,7 +777,7 @@ class SessionService {
 
 // src/runs/store.ts
 import { mkdirSync as mkdirSync2, unlinkSync } from "node:fs";
-import { dirname as dirname3 } from "node:path";
+import { dirname as dirname4 } from "node:path";
 
 // src/runs/driver.ts
 import { createRequire as createRequire2 } from "node:module";
@@ -819,7 +902,7 @@ class SqliteRunStore {
   constructor(path) {
     this.path = path;
     if (path !== ":memory:") {
-      mkdirSync2(dirname3(path), { recursive: true });
+      mkdirSync2(dirname4(path), { recursive: true });
     }
     this.db = openDriver(path);
     if (path !== ":memory:") {
@@ -916,11 +999,11 @@ class AppError2 extends Error {
 }
 
 // src/workflow/load.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 function loadWorkflowFile(path) {
   let raw;
   try {
-    raw = JSON.parse(readFileSync2(path, "utf8"));
+    raw = JSON.parse(readFileSync3(path, "utf8"));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const missing = error.code === "ENOENT";
@@ -947,6 +1030,7 @@ usage:
   next-steps steps   --key <key> [--limit <n>] [--after <seq>] [--json]
   next-steps keys    [--json]
   next-steps reset   --key <key> [--json]
+  next-steps agents  [--json]             (print the agent playbook)
 
   next-steps workflow new [--json]
   next-steps workflow show [--json]
@@ -959,6 +1043,7 @@ usage:
 
 state:   ./.next-steps/state.db       (created on first use, gitignored)
 graph:   ./.next-steps/workflow.json  (one graph per project, committed)
+hook:    ./.next-steps/hook           (optional, runs after each log)
 
 exit codes:
   0 ok   2 usage   3 not found   4 invalid transition   5 invalid workflow`;
@@ -973,7 +1058,7 @@ function asString(value) {
   return typeof value === "string" ? value : undefined;
 }
 function requireGraphFile(graphPath) {
-  if (existsSync3(graphPath))
+  if (existsSync5(graphPath))
     return;
   throw new AppError2("workflow_not_found", `workflow file not found: ${graphPath} (run "next-steps workflow new")`, 3);
 }
@@ -989,8 +1074,8 @@ function requireWorkflow(graphPath) {
 }
 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 graphPath = options.graphPath ?? join3(cwd, ".next-steps", "workflow.json");
+  const dbPath = options.dbPath ?? join3(cwd, ".next-steps", "state.db");
   const [command, ...rest] = argv;
   if (!command || command === "help" || command === "--help" || command === "-h") {
     return HELP;
@@ -998,6 +1083,10 @@ function execute(argv, options) {
   if (command === "version" || command === "--version" || command === "-v") {
     return `next-steps ${VERSION}`;
   }
+  if (command === "agents") {
+    const { values } = parseOptions(rest, { json: { type: "boolean" } });
+    return cmdAgents(Boolean(values.json));
+  }
   if (command === "workflow") {
     const { positionals, values } = parseOptions(rest, { json: { type: "boolean" } }, true);
     const [subcommand] = positionals;
@@ -1051,7 +1140,7 @@ press Ctrl+C to stop`;
           key: asString(values.key),
           node: asString(values.node),
           json: Boolean(values.json)
-        });
+        }, (result) => runPostLogHook({ path: join3(dirname5(graphPath), "hook"), cwd, workflow }, result));
       }
       case "next": {
         const { values } = parseOptions(rest, {

package/docs/AGENTS.sample.md

@@ -0,0 +1,120 @@
+<!-- Template: copy this to AGENTS.md in a repo that uses next-steps on PATH. -->
+
+# Work the graph with next-steps
+
+This repo defines its work as one graph in `.next-steps/workflow.json`.
+`next-steps` walks that graph one node at a time: it tells you which nodes are
+legal now, and records the path you take.
+
+Pass `--json` to every command.
+
+## Walk
+
+1. **Open a session.**
+
+   ```sh
+   next-steps create --json
+   ```
+
+   The response holds `key` (your task id) and the first `next` list.
+
+   **Done when:** you have `key` in hand and a non-empty `next` list.
+
+2. **Choose one next node.**
+
+   Each entry has `node`, `edge`, `title`, `description`, `reviewRequired`, and
+   sometimes `condition`. The `condition` is prose telling you when that branch
+   applies; you judge it against the task, nothing checks it for you. `edge` is
+   derived from `from->to` and is what the log will record.
+
+   ```json
+   {
+     "current": { "node": "verify", "title": "Verify" },
+     "next": [
+       { "edge": "verify->implement", "node": "implement", "title": "Implement",
+         "description": "Loop back and fix the failure.",
+         "condition": "the build or the tests failed",
+         "reviewRequired": true },
+       { "edge": "verify->review", "node": "review", "title": "Peer review",
+         "description": "Hand the change to review.",
+         "condition": "the build and the tests pass",
+         "reviewRequired": false }
+     ],
+     "done": false
+   }
+   ```
+
+   **Done when:** exactly one entry is chosen.
+
+3. **If that entry has `reviewRequired: true`, stop and ask.**
+
+   Prepare everything the node needs — the plan, the diff, the command you are
+   about to run — show it to the user, and wait for an explicit yes. Then act.
+
+   **Done when:** the user said yes. The CLI only reports the flag — nothing
+   enforces it. A node without the flag: skip this step.
+
+4. **Do that node's work.**
+
+   **Done when:** the node's `description` is satisfied — not when you started
+   it.
+
+5. **Log the node.**
+
+   ```sh
+   next-steps log --key <key> --node <node> --json
+   ```
+
+   One log per visit, after the work. Log is the only call per node; the
+   response already carries the new `next` list, so continue straight from it.
+
+   **Done when:** exit `0` and the response contains the new `next` list.
+
+6. **Repeat 2–5 until the response says `done: true`.**
+
+   **Done when:** `done` is true. Stop there; a written summary is its own node
+   if the graph wants one.
+
+`next-steps next --key <key> --json` returns the same list on demand. Use it when
+you resume rather than during the walk.
+
+## Branches
+
+- **`END` is a legal target.** Log it like any node; the session becomes
+  `done`. The `next` list also labels it `finish`.
+- **A node whose only move is `END`** finishes the run as soon as you log it.
+  The response is already `done: true`; there is no extra step.
+- **Exit `4`** means the move is not legal. The error's `details.legal` is the
+  complete list of nodes you can move to; choose from it, or correct the work and
+  log the node the graph expects.
+- **Exit `3`** means the key is unknown or `.next-steps/workflow.json` is
+  missing — run `next-steps workflow new` if the graph has never been created. A
+  key belongs to one task: create a fresh session for a new task.
+
+## Resume
+
+A new agent, or the same one after a context reset, rebuilds the task from the
+tool:
+
+```sh
+next-steps steps --key <key> --json   # audit trail: seq, node, from, edge, at
+next-steps next  --key <key> --json   # legal moves now
+```
+
+The `steps` record is the source of truth for what already happened.
+
+## Housekeeping
+
+```sh
+next-steps keys --json                     # sessions on this machine
+next-steps reset --key <key> --json        # delete a finished or abandoned session
+```
+
+`.next-steps/state.db` is local state and is gitignored. The graph,
+`.next-steps/workflow.json`, is source code: commit it with the rest of the repo.
+
+## Exit codes
+
+`0` ok · `2` usage, duplicate key, or invalid key · `3` not found ·
+`4` invalid move or unknown node · `5` invalid workflow file. Errors go to
+stderr as `{ "error": { "code", "message", "details" } }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wanbicoi/next-steps",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Agent-facing workflow walker: log a step, list the next ones.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "viz/template.html",
+    "docs/AGENTS.sample.md",
     "README.md",
     "LICENSE"
   ],