@wanbicoi/next-steps 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 next-steps contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+# next-steps
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small CLI that keeps an agent on a predefined workflow. The graph is one file,
+`.next-steps/workflow.json`; the tool records one session per task and always
+answers the same question: **what can I do next?**
+
+```
+$ next-steps create
+session: 4f1c9b3e-9a02-4d1c-8e11-7c6b1f0a2d33
+workflow: feature-work  Implement a feature end to end
+status: running
+
+next:
+  1. read-issue  Read the issue
+     Open the ticket and summarize the acceptance criteria.
+
+$ next-steps log --key 4f1c... --node read-issue
+logged: #1 read-issue  (entry)
+status: running
+
+next:
+  1. implement  Implement  [review]
+     Criteria are understood.
+```
+
+The point is not to constrain what the agent can think — it is to make the path
+it took readable afterwards, and to stop it from skipping work or losing its
+place. A node marked `[review]` means the agent shows the plan and waits for an
+explicit yes before doing the work; the flag is advisory, so nothing blocks a
+scripted run.
+
+## Run it
+
+Published package (Node 22.13+):
+
+```sh
+npx @wanbicoi/next-steps help
+bunx @wanbicoi/next-steps help
+pnpm dlx @wanbicoi/next-steps help
+```
+
+The npm package is scoped, but the installed command is still `next-steps`, so a
+project-local install shortens these to `next-steps help`, `bunx next-steps help`,
+or `pnpm exec next-steps help`:
+
+```sh
+npm install --save-dev @wanbicoi/next-steps
+bun add -d @wanbicoi/next-steps
+pnpm add -D @wanbicoi/next-steps
+```
+
+From this repo (Bun):
+
+```sh
+bun install
+bun src/cli.ts help
+```
+
+You can also use the package script: `bun run next-steps -- help`.
+
+State is created on first use at `./.next-steps/state.db` (SQLite, gitignored).
+The graph is read from `./.next-steps/workflow.json`; commit that file, and run
+the tool from the project root. There are no path flags.
+
+This repo keeps sample graphs under `test/fixtures/<id>/.next-steps/`. To try the
+commands from the repo root:
+
+```sh
+mkdir -p .next-steps && cp test/fixtures/feature-work/.next-steps/workflow.json .next-steps/
+```
+
+## Visualize the graph
+
+`next-steps viz` serves an interactive Cytoscape viewer for
+`.next-steps/workflow.json`:
+
+```sh
+next-steps viz                # http://127.0.0.1:3000
+next-steps viz --port 8080
+```
+
+From this repo, `bun src/cli.ts viz`. Press Ctrl+C to stop. Groups are drawn as
+labelled boxes, review nodes are marked, and every move shows its description and
+condition. Edit `viz/template.html` to change the styles.
+
+## Commands
+
+```
+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]
+```
+
+Pretty output is the default; `--json` is the stable, machine-readable form
+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.
+
+## Workflow format
+
+```json
+{
+  "id": "deploy",
+  "title": "Deploy a change",
+  "start": "build",
+  "nodes": [
+    {
+      "id": "build",
+      "title": "Build",
+      "description": "Run the build.",
+      "group": "Prepare",
+      "next": [{ "to": "review", "description": "The build is green." }]
+    },
+    {
+      "id": "review",
+      "title": "Review",
+      "description": "Read the change before it ships.",
+      "group": "Prepare",
+      "reviewRequired": true,
+      "next": [
+        { "to": "build", "description": "Fix the review notes." },
+        { "to": "END", "description": "Approved." }
+      ]
+    }
+  ]
+}
+```
+
+- `start` names the first step. Every node needs at least one move.
+- `next` holds the ways out of the node. `to` is a node id or `END`; a
+  `condition` adds prose the agent reads but nothing evaluates. The move the
+  agent actually logs is the audit trail, recorded as `from->to`.
+- `END` is a reserved target, not a node. A node whose only move is `END`
+  finishes the run as soon as it is logged, with no extra step.
+- `group` labels a region of the graph. It is rendering metadata: the viewer
+  draws it as a box, and the rest of the tool ignores it.
+- `reviewRequired` marks a node that needs an explicit yes before the work
+  starts. It is reported in `next` and `workflow show`, and never enforced.
+- Duplicate moves out of one node are rejected so the log is unambiguous, and at
+  least one move to `END` is required.
+- The graph is flat: there are no subgraphs and no cross-file references.
+
+Run `next-steps workflow check` after editing. It fails with exit 5 on structural
+problems and warns about unreachable nodes or nodes that cannot reach `END`.
+
+## Exit codes
+
+`0` ok · `2` usage / duplicate key / invalid key · `3` not found ·
+`4` invalid transition or unknown node · `5` invalid workflow file.
+
+Errors go to stderr. With `--json` they are
+`{ "error": { "code", "message", "details" } }`, and `details.legal` lists the
+moves the graph allows.
+
+## Publish
+
+```sh
+npm login
+npm publish
+```
+
+`prepublishOnly` runs lint, typecheck, tests, and knip. `prepack` builds
+`dist/cli.js` for Node with a `#!/usr/bin/env node` shebang; the tarball contains
+`dist/`, `README.md`, and `LICENSE`.
+
+Check the package before publishing:
+
+```sh
+npm pack --dry-run
+npx --yes ./wanbicoi-next-steps-<version>.tgz --help
+```
+
+## Development
+
+```sh
+bun run lint:fix     # Biome, formatting + safe fixes
+bun test             # graph, validation, CLI end-to-end
+bun run typecheck
+bun run knip         # unused files, exports, dependencies
+bun run build        # dist/cli.js, Node target
+```
+
+Hooks (Husky): `pre-commit` runs Biome on staged files, `commit-msg` runs
+commitlint (conventional commits), `pre-push` runs typecheck, tests, and knip.
+
+Layout:
+
+```
+src/cli.ts               argument parsing, dispatch, exit codes
+src/format.ts            pretty output
+src/commands/            one function per command
+src/workflow/            load, validate, pure graph logic
+src/runs/                session service, store, Bun/Node SQLite driver
+scripts/build.ts         Node bundle + shebang for dist/cli.js
+test/fixtures/<id>/      sample graphs, each in its own .next-steps/ directory
+test/                    pure, validation, end-to-end
+```
+
+`src/workflow/graph.ts` is pure: no I/O, no database, so the next computation is
+testable in milliseconds. `RunStore` is an interface over `src/runs/driver.ts`,
+which loads `bun:sqlite` under Bun and `node:sqlite` under Node. A state file from
+0.1.0 or earlier is replaced on first use, since those sessions name graphs that
+no longer exist.
+
+`docs/initial-plan.md` records the original design and the decisions behind it.