@macintacos/caret 1.0.1 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Review, annotate, and approve Claude Code plans in a local web UI.",
   "author": { "name": "macintacos" },
   "homepage": "https://github.com/macintacos/caret",

package/README.md

@@ -17,7 +17,9 @@ Want to develop `caret` rather than use it? Start with [CONTRIBUTING.md](CONTRIB
 
 ## Install
 
-`caret` needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle.
+```sh
+bunx --no-cache @macintacos/caret@latest install
+```
 
 > [!NOTE]
 > `caret` supports macOS and Linux, where the review UI can run as a long-lived login
@@ -25,10 +27,6 @@ Want to develop `caret` rather than use it? Start with [CONTRIBUTING.md](CONTRIB
 > [`doc/CONFIGURING.md`](doc/CONFIGURING.md#platform-support) for what differs on each
 > platform and what to fall back on.
 
-```sh
-bunx --no-cache @macintacos/caret@latest install
-```
-
 Assuming that you installed it as a long-lived service (the default), you can navigate to
 <http://caret.localhost:42718> to see the `caret` UI.
 
@@ -37,6 +35,8 @@ After installing:
 1. **Restart the agent.** OpenCode installs the plugin package on its next start.
 2. **Run `/caret:demo`.** It presents a short demo plan that points at files in the repo
    you run it from, so you can exercise the whole flow before a real one arrives.
+3. **Run `/caret:plan <what you want done>`** to plan a real change and review it in
+   `caret` before the agent implements it.
 
 ### Running `caret` yourself
 
@@ -61,7 +61,8 @@ bunx --no-cache @macintacos/caret@latest install --uninstall  # remove
 ```
 
 `caret`'s UI is designed to check for updates, at most once a day. When a newer `caret` is
-out, the review UI says so once: a toast on load, a mark on the settings button, and a
+out, the review UI says so once: a toast on load that opens **What's new** (the skipped
+release notes or trunk commits), a mark on the settings button, and a
 **Settings → Updates** pane naming the version and the exact command to take it.
 
 Turn the check off from that same pane, or by hand in
@@ -89,10 +90,12 @@ your browser instead of the terminal prompt. There you:
   and re-present.
 
 > [!TIP]
-> You don't have to wait to be intercepted: `caret` gives both agents a plan-review tool
-> they can call directly — `review_plan` in Claude Code (from the plugin's MCP server) and
-> `caret_review_plan` in OpenCode — so a skill of your own can route its plan through the
-> same review UI. The tool is for plans only; see
+> You don't have to wait to be intercepted: `/caret:plan <what you want done>` asks the
+> agent for a plan and routes it straight to the review UI. In OpenCode it runs on the
+> `plan` agent, so switch to `build` to implement once you approve. A skill of your own
+> can do the same with the plan-review tool `caret` gives both agents — `review_plan` in
+> Claude Code (from the plugin's MCP server) and `caret_review_plan` in OpenCode. The tool
+> is for plans only; see
 > [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md#calling-the-review-tool-from-your-own-skill).
 
 ## Configuration
@@ -116,10 +119,12 @@ Two more live at the repo root:
 
 ## Diagnostics
 
-- `/caret:discovery` prints a one-shot, read-only diagnostics snapshot of your install —
-  always redacted, and it never contains plan, prompt, or feedback bodies, nor any log
-  contents.
-- `/caret:debug` reviews the current session's plans and recent errors.
+- `/caret:doctor` runs `caret doctor`: a one-shot, read-only check of your install —
+  what's wrong, how to fix it, and the state it read that from. Always redacted, and it
+  never contains plan, prompt, or feedback bodies, nor any log message, error or stack
+  text.
+- `caret doctor --bundle` archives the raw logs and review records when a maintainer needs
+  them. That archive is **not** redacted, so caret asks before writing it.
 
 ## License
 

package/bin/caret

@@ -2,7 +2,7 @@
 #
 # caret plugin entrypoint shim (EXC-643). This is the ONE file Claude Code's
 # hooks invoke — `${CLAUDE_PLUGIN_ROOT}/bin/caret <subcommand>` (see
-# hooks/hooks.json and commands/discovery.md). It is committed and shipped in
+# hooks/hooks.json and commands/doctor.md). It is committed and shipped in
 # every install; it resolves the actual caret runtime from whatever the install
 # method placed beside it:
 #

package/commands/doctor.md

@@ -0,0 +1,139 @@
+---
+description: Diagnose this caret install — run caret doctor, relay each failing check's remedy, and present the report ready to share
+---
+
+caret's `doctor` subcommand renders a verdict over a one-shot, read-only snapshot of the
+local install: a `checks:` block naming what is wrong and how to fix it, then the state it
+read that from — running caret processes, daemon identity, lock/port state, effective
+settings, review counts, the agent adapter's install-state probe (plugin version, enabled
+state, and whether a manual hook sits in the agent's user settings), log sizes and error
+counts, recent failures grouped by review with their codes, install/runtime info, and
+system basics. The report is **always redacted** (home paths become `~`, usernames in
+foreign home paths are censored) and never contains plan, prompt, or feedback bodies, nor
+any log message, error or stack text — it exists to be shared.
+
+## 1. Run it
+
+First ask the user (via `AskUserQuestion`) which format they want:
+
+- **JSON** — for feeding to tooling.
+- **Human-readable** — for scanning in the conversation.
+
+Then run the matching invocation:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" doctor --json   # JSON
+"${CLAUDE_PLUGIN_ROOT}/bin/caret" doctor          # human-readable
+```
+
+The exit code is the verdict: `0` every check passed, `1` at least one failed, `2` no
+report — doctor could not produce one, or a `--bundle` run had no terminal to ask consent
+at and stopped before collecting anything. On `2`, present the exit code and stderr
+instead — and if the binary itself is missing (a source checkout that has never been
+built), say so and point at `mise run build` (or `mise run build --install`).
+
+## 2. Relay each failing check
+
+A failing check already carries the remedy that closes it; relay it rather than inventing
+one. What each id means:
+
+| id | what failed | relay |
+| --- | --- | --- |
+| `daemon-reachable` | a caret service is recorded but the daemon did not answer, or the effective port answers as something other than caret | the check's remedy verbatim, then offer to read any log it names |
+| `daemon-lock` | the lock names a dead pid, or a port caret is not configured to bind | the check's remedy verbatim |
+| `agent-install` | the agent the check names does not have caret enabled | `caret install` |
+| `log-errors` | a live log wrote an NDJSON error record in the last 24h; the detail names which log and when it last erred | step 4 |
+| `opencode-caret-version` | OpenCode would load a caret behind the published one | the check's remedy verbatim |
+
+An `unknown` check is not a failure: it names its own `reason` — no network, an unreadable
+config, or a report section that never collected, which also shows as `<name> error: …`
+(`"error": "…"` under `--json`) and leaves the check with no detail. A doctor run offline
+reaching one is the normal case; present it as-is rather than treating it as a failure of
+this command. A daemon that is simply not running is not one of these — it reports
+`reachable false` and *passes*, because an on-demand daemon idle-exits by design.
+
+## 3. Present the report
+
+End your output with the command's stdout **verbatim** in a fenced code block —
+` ```json ` for the JSON format, plain ` ``` ` for the human-readable one — so the user
+can copy it out in one piece. Add nothing inside the block and do not summarize away
+sections; the report is already redacted and complete.
+
+## 4. Debug a failing `log-errors`
+
+When `log-errors` failed and the `/systematic-debugging` skill is available, invoke it to
+drive root-cause investigation from the logs the check named. Otherwise read the last
+error records yourself and reason from the failing step, code, msg, cause, and stack.
+
+Read the report's `failures` first. Each group is one review's error records from both
+logs with their codes (a session's, when the failure came before a review id existed), so
+a hook-side record sits beside any daemon-side record from that review's own requests. A
+daemon-wide failure (a crash, a bind failure, a failed update check) carries no id and
+lands in `ungrouped`: read it alongside the group and correlate the two by `time`. Pull a
+group's full records from both logs (`.sessionId` for a session group):
+
+```bash
+dir="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+grep -h '^{' "$dir/logs/caret.log" "$dir/logs/daemon.log" | jq -c 'select(.reviewId == "<id>")'
+```
+
+For records outside any group or the report's window, fall back to the last error records
+of each log:
+
+```bash
+grep '^{' "$dir/logs/caret.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+grep '^{' "$dir/logs/daemon.log" | jq -s '[.[] | select(.level >= 50)] | .[-5:]'
+tail -n 40 "$dir/logs/daemon-stderr.log"
+```
+
+`log-errors` counts only NDJSON error records, so a crash that reached `daemon-stderr.log`
+alone leaves it passing — tail that file even when the check is green. It fails only on
+records from the last 24h, so a log that has settled passes while still reporting when it
+last erred; work from that time rather than from the count. If a failure predates the
+current live file, `gunzip -c` the segment you need from `logs/archive/` and rerun the
+recipe against the result.
+
+## 5. Review this session's plans
+
+The report counts reviews in aggregate; it does not say what happened in *this* session.
+When the user wants that timeline, reconstruct it from the records — identify the session
+by the most recently updated review whose `cwd` matches, then list every review in it,
+oldest first:
+
+```bash
+dir="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+sid=$(jq -rs --arg cwd "$PWD" '[.[] | select(.cwd == $cwd)] | sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+jq -s --arg sid "$sid" '[.[] | select(.sessionId == $sid)] | sort_by(.createdAt) | .[] | {id, title, status, versions: (.versions | length), decidedAt: .decision.decidedAt, feedback: .decision.feedback}' "$dir"/reviews/*.json
+```
+
+That field whitelist is deliberate: `versions[].plan` and `generalCommentDraft` hold full
+plan and draft bodies — never select or echo them.
+
+If `sid` comes back empty, no review matches the working directory. Say so, then fall back
+to the most recently updated session across all reviews and re-run the listing with it:
+
+```bash
+sid=$(jq -rs 'sort_by(.updatedAt) | last | .sessionId // empty' "$dir"/reviews/*.json)
+```
+
+If `$dir/reviews` is missing or empty the glob won't match and these commands error (shell
+or jq, depending on the shell) — that is "no reviews recorded", not a failure.
+
+Present the result grouped by status, each review with its id, title, and version count
+(the number of plan revisions):
+
+- **pending** — awaiting a decision in the browser.
+- **rejected** — changes requested; awaiting a revised plan. Include a short excerpt of
+  the decision `feedback`.
+- **approved** — plan accepted; terminal success.
+- **expired** — abandoned by its hook (timeout) or superseded by a resubmitted plan;
+  terminal, never reviewed.
+
+## 6. Sharing the raw logs
+
+If the report is not enough and the user wants to hand the raw material to a maintainer,
+`caret doctor --bundle` writes a zip of the live logs and review records to caret's state
+dir. Tell them plainly before suggesting it: that archive is **not** redacted — it holds
+their logs and full plan bodies — so it is written only after they confirm, and it should
+move over a channel they trust. caret asks at a terminal and your run has none, so carry
+their answer with `--yes` — never before they have given it.

package/commands/plan.md

@@ -0,0 +1,25 @@
+---
+description: Plan a change and route the plan through caret's review UI before implementing it
+argument-hint: [what you want done]
+---
+
+Plan this, then implement it once caret approves the plan:
+
+$ARGUMENTS
+
+If that is empty, plan whatever the user asked for earlier in this session.
+
+Call `EnterPlanMode` first: `ExitPlanMode` is refused outside plan mode. Research what the
+change needs — read the relevant code, trace the real flow — then write the plan to the
+file your plan-mode instructions name. Call `ExitPlanMode` with that same text as its
+`plan` argument — caret reviews the argument, so a call without it reaches the review UI
+empty.
+
+This triggers caret's `PermissionRequest`/`ExitPlanMode` hook, which opens the plan in a
+local browser UI for inline review. When the user approves or requests changes there, the
+decision flows back to you:
+
+- **Approved** → implement the plan.
+- **Changes requested** → the feedback arrives as the denial reason. Re-read the plan file
+  (caret rewrites it in its canonical shape, so the feedback's line numbers match it),
+  revise it, and call `ExitPlanMode` again with the revised text as its `plan` argument.