@ketchao/nextup 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# nextup (placeholder name)
 
-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.
+Next-step menu for coding agents. MVP: **Claude Code** and **Codex** (same hook protocol).
+
+> The name is a placeholder. The reference screenshot is from a product called "Then", so that name should not be used.
+
+After each substantial turn, it shows up to 4 contextual options (with a cost indicator). The user answers by typing the number in the normal Claude Code box.
+
+```
+◆ What's next?  Type a number · +1 2 = several
+                                                      cost ▾
+  1  Commit changes ★ suggested                       ■□□ low
+  2  Review my changes                                ■■□ medium
+  3  Write tests                                      ■■■ high
+  4  Leave it as is                                   □□□ none
+  5  Something else (free text)
+```
+
+## Try it (5 minutes)
+
+```bash
+npm install
+npm test                      # 103 tests
+npm run preview               # see the menu without Claude (iterate the design here)
+npm run preview -- --scenario failed --width 60
+npm run build
+
+# in a test repo, from the published package:
+npm install -g @ketchao/nextup
+nextup init --agent codex
+claude                        # ask for a small change and watch what happens when it finishes
+```
+
+`init --user` installs the hooks globally; `init --remove` removes them. The first time, it writes a `settings.json.nextup.bak` backup.
+
+Try a hook without Claude:
+
+```bash
+cat fixtures/stop.json | NEXTUP_ALWAYS=1 node dist/cli.js hook stop
+cat fixtures/prompt-submit.json | node dist/cli.js hook prompt-submit
+```
+
+## Try it with Codex (experimental)
+
+`hook stop` and `hook prompt-submit` read and write the same JSON format Codex uses, so there is no new adapter: only the registration path changes.
+
+```bash
+node dist/cli.js init --agent codex      # writes .codex/hooks.json (or --user for ~/.codex/hooks.json)
+codex                                    # then type /hooks and approve (trust) the 2 nextup hooks
+```
+
+Notes:
+- Codex ignores new or changed hooks until you review them with `/hooks`.
+- On native Windows (Codex CLI 0.166.0, cmd) the hooks **do run**. The `systemMessage` shows up as "Hook · ..." with ANSI colors and alignment intact.
+- The transcript reader (`transcript.ts`) is best effort and understands Claude Code and Codex formats. It only reads the current turn (the `UserPromptSubmit` hook marks where it starts). If something looks wrong, turn on `debug` and check `debug.jsonl`: the `stop-signals` entry shows the detected commands and exit codes, plus a summary of the lines read.
+- Codex runs hooks from a background server that **does not inherit your environment variables**: use `~/.nextup/config.json` (below) or start `codex --no-daemon`.
+
+## Configuration
+
+Environment variables **or** the file `~/.nextup/config.json` (environment variables win):
+
+```json
+{
+  "language": "en",
+  "suggestions": 4,
+  "showCustomOption": true,
+  "showTokenEstimation": true,
+  "autoSuggest": true,
+  "backgroundCheck": true,
+  "consumption": "measured",
+  "providers": { "claude": true, "codex": true, "opencode": true },
+  "debug": false,
+  "theme": "default"
+}
+```
+
+`suggestions` is the row cap, including "Leave it as is" (1–4). `showCustomOption` is the "Something else" row. `showTokenEstimation` is the cost column. `autoSuggest: false` stops new menus; a menu already on screen still accepts a number. `backgroundCheck` runs `npm test` (and `npm run lint` if it exists) before building the menu, with a short time cap: if 3 tests fail, the row says "3 tests failed, fix them". `false` turns that off. `consumption` is `measured` (real time: `1.5s`, or `—` if that action has not been measured yet) or `estimated` (low, medium, high, none). `providers` turns an agent off: Codex is recognized by a `.codex` path in the transcript. OpenCode has no adapter yet, so its flag is stored and does not cut anything off. `language` is the menu language when the prompt is not enough to tell (a number, an "ok", or a mix). The default is `en`. An existing `config.json` is not rewritten: switch it with `nextup config set language en`. A prompt that is a sentence in English shows the menu in English; a sentence in Spanish shows it in Spanish. `lang`, `mode`, `color`, `width`, `always`, and `disabled` still work. The environment overrides the file.
+
+To view or change it without editing the JSON:
+
+```
+nextup config
+nextup config set autoSuggest false
+nextup config set providers.codex false
+nextup config set showCustomOption true
+nextup config set suggestions 3
+nextup config set theme blue
+nextup config set language en
+nextup config set consumption estimated
+```
+
+Switches accept `true`/`false` (also `on`/`off` and `si`/`no`). In the agent box, without leaving Codex and without `nextup` on `PATH`:
+
+```
+nextup theme blue
+nextup config set consumption estimated
+```
+
+The change is saved and the agent does not run it. It shows up on the next menu. `color` and `default` paint each row by cost. `blue`, `green`, `amber`, `pink`, `teal`, and `violet` paint the whole menu one color. `mono` leaves it uncolored. `azul`, `ambar`, `rosa`, and `cian` are accepted aliases. `nextup init` creates the file with everything on if it does not exist yet, and does not overwrite one you already have.
+
+With `"debug": true`, each hook stores what it received and returned in `~/.nextup/state/debug.jsonl` (paths and text from your session; local only). Each menu also leaves a line in `~/.nextup/state/choices.jsonl`: whether you picked a number, left it as is, or typed something else. It does not store the sentence. If a row is offered three times on similar turns and you never pick it, it drops.
+
+## How it works
+
+1. **`Stop` hook**: reads the payload, gathers cheap signals (`git status` changes, `Bash` commands from the turn in the transcript, the final message), builds the menu, and shows it with `systemMessage`. Saves the pending menu in `~/.nextup/state/<session_id>.json`.
+2. The user types the row number (`2`) or several at once (`+2 4`, `1 3`, `1 y 3`). The `+` is optional.
+3. **`UserPromptSubmit` hook**: if a menu is pending and the reply is a selection, it injects the instructions as `additionalContext` (the hook cannot rewrite the prompt; Claude receives "3" plus the context that explains it). "Leave it as is" and "Something else" block the prompt and spend no tokens. Any other text discards the menu and passes through unchanged.
+
+Design decisions (from the critique of the mock):
+- **It does not suggest what already happened**: if the tests already passed, it does not offer to run them again.
+- **It does not repeat what you just picked** (only for the next menu) **and it does not offer to run tests if the repo has none configured**: it suggests the commit instead.
+- **0 to 4 options, and sometimes none**: no menu if nothing changed, or if the agent ended with a question.
+- **The suggested row is never outward**: the schema (`SuggestionSchema`) rejects `recommended` + `outward` (push, deploy, ...).
+- **The default menu paints the row**: green, amber, red, or gray by cost, and "Something else" in blue. The number sits on a lighter chip. `blue`, `green`, `amber`, `pink`, `teal`, and `violet` paint the whole menu one color. `mono` and `color: false` leave it plain text. The `☐` is not a checkbox: you pick with the number. In the agent box, with no slash: `nextup theme blue` (also `verde`, `azul`, `ambar`, `rosa`, `cian`). The slash command belongs to Codex and rejects `/nextup`.
+
+## Spike: what to verify first
+
+These four things are **not confirmed**; the design depends on them:
+
+| # | Question | How to test | If it fails |
+|---|----------|-------------|-------------|
+| 1 | Does a Stop `systemMessage` show without blocking? | Run `claude`, ask for a change, look when it finishes | Use `NEXTUP_MODE=block` |
+| 2 | Does it keep ANSI and line breaks? | Compare with `NEXTUP_COLOR=0` | Leave color off by default |
+| 3 | Does Claude act well on `"3"` plus injected context? | Pick options several times | Strengthen the `additionalContext` text |
+| 4 | Is the detected width correct? | Resize the terminal; try `NEXTUP_WIDTH` | Fixed or more compact width |
+
+Also measure real turn latency (the hook starts in ~60 ms; the rules are local, so there is no model call today) and try the VS Code/Cursor extension, whose UI may show hooks differently from the terminal.
+
+## Known limits
+
+- The menu only looks at files whose diff changed this turn (baseline saved in `UserPromptSubmit`). If that mark is missing, it falls back to the full `git status`.
+- The JSONL transcript is not a public contract: `transcript.ts` is best effort and degrades to "no signals".
+- Test detection uses commands and exit codes from the transcript (real Codex format checked with `fixtures/codex-rollout-sample.jsonl`). If the failure looks environmental (EPERM, "Access is denied", ...), it is treated as *blocked*, not as "tests broken": the suggestion becomes review the diff. With no exit code, it falls back to a heuristic on the final message.
+- No detection of headless runs (`claude -p`); if you later call `claude -p` from the hook, export `NEXTUP_INNER=1` on that call to avoid recursion.
+- Claude and Codex share the hook protocol (`systemMessage` / `additionalContext`). OpenCode needs its own presenter (append to the prompt).
+
+## Next steps
+
+1. Pass the spike (table above) and use it for a week; record which options get picked.
+2. `llm.ts`: 1 or 2 specific suggestions from a small model (API key or `claude -p`), keeping the deterministic rules as the base.
+3. Measured cost (real duration of the last test run) instead of a fixed value per action type.
+4. OpenCode presenter (append to the prompt). Claude and Codex already share `src/adapters/shared/`.
+
+## Layout
+
+```
+src/core/                 agent-independent: types (zod), rules, render, parser, state
+src/adapters/shared/      hook protocol: payloads, transcript, context, Stop and UserPromptSubmit
+src/adapters/claude/      install into .claude/settings.json
+src/adapters/codex/       install into .codex/hooks.json (timeoutSec)
+src/cli/                  preview, init, config, hook entry
+test/                     parse, suggest, render, hooks (temp git repo), adapters
+fixtures/                 sample payloads
+```