@wanbicoi/next-steps 0.0.0-stage → 0.1.0

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,204 @@
-# 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 lives in
+`workflows/*.json`; the tool records one session per task and always answers the
+same question: **what can I do next?**
+
+```
+$ next-steps create --workflow feature-work
+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)
+scope: feature-work   status: running
+
+next:
+  1. e1 -> implement  Implement
+     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.
+
+## 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).
+There are no path flags: the tool uses the directory it is run from, so run it
+from the project root. Workflow definitions are read from `./workflows/`.
+
+This repo keeps its sample graphs under `test/fixtures/workflows/`. To try the
+commands from the repo root:
+
+```sh
+mkdir -p workflows && cp test/fixtures/workflows/*.json workflows/
+```
+
+## Visualize workflows
+
+`next-steps viz` serves an interactive Cytoscape viewer for the workflows in
+`./workflows/`:
+
+```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. The viewer shows
+every graph with node/edge labels, conditions, and subgraph drill-down; edit
+`viz/template.html` to change the styles.
+
+## Commands
+
+```
+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]
+```
+
+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 a workflow — use `workflow new` for that.
+
+## Workflow format
+
+```json
+{
+  "id": "deploy",
+  "title": "Deploy a change",
+  "start": "build",
+  "nodes": [
+    { "id": "build", "type": "node", "title": "Build", "description": "Run the build." },
+    {
+      "id": "review",
+      "type": "subgraph",
+      "workflow": "code-review",
+      "title": "Review",
+      "description": "Run the review workflow."
+    }
+  ],
+  "edges": [
+    { "id": "e1", "from": "build", "to": "review", "description": "Build is green." },
+    { "id": "e2", "from": "review", "to": "END", "description": "Review done." }
+  ]
+}
+```
+
+- `start` names the first step.
+- `END` is a reserved target, not a node. It means "this scope is finished".
+- A conditional edge adds `"condition": "the tests failed"`. Conditions are prose
+  for the agent; nothing evaluates them. The edge the agent actually logged is
+  the audit trail.
+- A `subgraph` node references another workflow by id. Entering it pushes a
+  scope; reaching `END` inside it pops back and continues at the node after the
+  subgraph.
+- Every node needs an outgoing edge, every workflow needs an edge to `END`, and
+  a node whose only edge is `END` finishes its scope with no extra step.
+- Duplicate `from -> to` pairs are rejected so edge inference is unambiguous.
+
+Run `next-steps workflow check` after editing. It fails with exit 5 on structural
+problems and warns about unreachable nodes.
+
+## 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
+steps 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/workflows/ sample graphs (test fixtures)
+test/                    pure, validation, end-to-end
+```
+
+`src/workflow/graph.ts` is pure: no I/O, no database, so the tricky scope logic
+is testable in milliseconds. `RunStore` is an interface over `src/runs/driver.ts`,
+which loads `bun:sqlite` under Bun and `node:sqlite` under Node.
+
+`docs/initial-plan.md` records the design and the decisions behind it.