@macintacos/caret 0.14.0 → 1.0.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "0.14.0",
+  "version": "1.0.1",
   "description": "Review, annotate, and approve Claude Code plans in a local web UI.",
   "author": { "name": "macintacos" },
   "homepage": "https://github.com/macintacos/caret",
@@ -14,5 +14,12 @@
     "hooks",
     "approval",
     "annotation"
-  ]
+  ],
+  "mcpServers": {
+    "caret": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/bin/caret",
+      "args": ["mcp"],
+      "timeout": 3900000
+    }
+  }
 }

package/README.md

@@ -1,33 +1,27 @@
-# 🥕 caret
+# 🥕 `caret`
 
-> [!WARNING]
-> caret is an early prototype and may change substantially over the next little while —
-> interfaces, hooks, storage, and the install flow are all still settling. Expect rough
-> edges and breaking changes.
+`caret` is a plugin that replaces the terminal plan-approval prompt with a local web UI.
+When your agent presents a plan, `caret` opens it in your browser so you can read it as
+rendered HTML, **annotate passages inline** (Google-Docs style), and **approve** or
+**request changes**. Your feedback flows straight back to the agent. A single local daemon
+is shared across concurrent sessions, so several in-flight plans can be reviewed from one
+browser tab via a switcher.
 
-caret is a Claude Code (and OpenCode) plugin that replaces the terminal plan-approval
-prompt with a local web UI. When your agent presents a plan, caret opens it in your
-browser so you can read it as rendered HTML, **annotate passages inline** (Google-Docs
-style), and **approve** or **request changes** — your feedback flows straight back to the
-agent. A single local daemon is shared across concurrent sessions, so several in-flight
-plans can be reviewed from one browser tab via a switcher.
-
-Want to develop caret rather than use it? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
+Want to develop `caret` rather than use it? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Screenshots
 
-![caret review UI with an inline annotation, stitched across four themes](doc/assets/caret-review-ui.png)
+[Check out a short demo here!](https://youtu.be/zesv5AunUW4)
 
-[Watch a short review](https://github.com/user-attachments/assets/992b63b6-ed73-409a-a12a-bc14fd4c7d53)
-— comment on a line, send the plan back, approve the revision, and the agent picks up
-where you left it.
+![caret review UI with an inline annotation, stitched across four themes](doc/assets/caret-review-ui.png)
 
 ## Install
 
-caret needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle.
+`caret` needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle.
 
 > [!NOTE]
-> caret is **macOS-first**; Linux and Windows are best-effort. See
+> `caret` supports macOS and Linux, where the review UI can run as a long-lived login
+> service. Windows is best-effort and runs `caret` on demand only. See
 > [`doc/CONFIGURING.md`](doc/CONFIGURING.md#platform-support) for what differs on each
 > platform and what to fall back on.
 
@@ -35,25 +29,27 @@ caret needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bund
 bunx --no-cache @macintacos/caret@latest install
 ```
 
-That is the whole install — no `git clone`, no compile step. It detects which agents you
-have — [Claude Code](https://claude.com/claude-code), [OpenCode](https://opencode.ai), or
-both — asks which of them to install into, and registers the _published_ caret with each:
-prebuilt artifacts, the `/caret:*` slash commands, and the [rumdl](https://rumdl.dev/)
-plan formatter. Where it can't ask — off a terminal — it installs into every agent it
-detected.
+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.
 
-Two steps finish the job:
+After installing:
 
 1. **Restart the agent.** OpenCode installs the plugin package on its next start.
-2. **Run `/caret:demo`.** It presents a short fake plan, so you can exercise the whole
-   flow before a real one arrives.
+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.
+
+### Running `caret` yourself
+
+If you'd rather `caret` not start at login, answer **I'll run it myself** when
+`caret install` asks. That removes the service if one is registered. Then, whenever you
+want the review UI up, run:
+
+```sh
+bunx @macintacos/caret@latest serve
+```
 
-| Flag                | What it does                                                      |
-| ------------------- | ----------------------------------------------------------------- |
-| `--target <agents>` | Skip the chooser: `claude`, `opencode`, or both, comma-separated. |
-| `--dry-run`         | Preview the run without changing anything.                        |
-| `--refresh`         | Update an existing install.                                       |
-| `--uninstall`       | Remove caret, offering the same agent chooser.                    |
+This will keep the UI up at `http://caret.localhost:42718` until the process is
+terminated.
 
 ### Updating and uninstalling
 
@@ -64,34 +60,27 @@ bunx --no-cache @macintacos/caret@latest install --refresh    # update
 bunx --no-cache @macintacos/caret@latest install --uninstall  # remove
 ```
 
-`--target` pins the agents on both, exactly as it does on a fresh install. Restarting each
-agent applies an update. In OpenCode, caret toasts you at startup when a newer release is
-out; a plain `install` at a terminal runs its own check against npm and asks before taking
-it.
-
-caret's daemon runs the same check for itself, at most once a day. The call is
-unauthenticated and sends nothing about you — just a request to npm or GitHub, depending
-on how caret was installed, for the newest published version. When a newer caret is out,
-the review UI says so once: a toast on load, a mark on the settings button, and a
+`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
 **Settings → Updates** pane naming the version and the exact command to take it.
 
-Turn the check off from that same pane, or by setting `updates.check` to `false` in
-`prefs.json` (`~/.local/state/caret/prefs.json`, or under `$XDG_STATE_HOME/caret`):
+Turn the check off from that same pane, or by hand in
+[`config.toml`](doc/CONFIGURING.md#the-updates-table):
 
-```json
-{ "updates": { "check": false } }
+```toml
+[updates]
+check = false
 ```
 
 See [the OpenCode adapter](doc/ARCHITECTURE.md#the-opencode-adapter) for the by-hand
 equivalents, for pinning a version in OpenCode's `plugin` array, and for what each agent's
 install touches; [the Claude Code adapter](doc/ARCHITECTURE.md#the-claude-code-adapter)
-covers the hooks caret registers there.
+covers the hooks `caret` registers there.
 
-## Using caret
+## Using `caret`
 
-Whenever your agent presents a plan — Claude Code's `ExitPlanMode`, or the Plan agent in
-OpenCode — caret intercepts it and opens it in your browser instead of the terminal
-prompt. There you:
+Whenever your agent presents a plan, `caret` should intercept it and opens the plan in
+your browser instead of the terminal prompt. There you:
 
 - **Read** the plan as rendered HTML.
 - **Annotate** — select any passage to attach an inline comment.
@@ -100,29 +89,19 @@ prompt. There you:
   and re-present.
 
 > [!TIP]
-> **In OpenCode**, you don't have to wait to be intercepted: caret registers a
-> `caret_review_plan` tool your agent can call directly, so a skill of your own can route
-> its approval step through the same review UI. Claude Code has no equivalent — see
+> 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
 > [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md#calling-the-review-tool-from-your-own-skill).
 
 ## Configuration
 
-caret runs with sensible defaults and needs no configuration. To tune it — the daemon
+`caret` runs with sensible defaults and needs no configuration. To tune it — the daemon
 port, the review timeout, the log level — it reads an optional `config.toml` and `CARET_*`
 environment variables. Every key, every variable, and their defaults are in
 [`doc/CONFIGURING.md`](doc/CONFIGURING.md).
 
-## 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.
-
-Logs are written raw by default. `caret redact` writes scrubbed `*.redacted.log` copies
-alongside them — paste one of those into a chat, a gist, or an AI assistant, never the
-original. [`doc/RUNNING.md`](doc/RUNNING.md#logging--debugging) says where they live.
-
 ## Documentation
 
 [`doc/README.md`](doc/README.md) maps the `doc/` directory — start there and it routes you
@@ -130,11 +109,18 @@ to the reference page that answers your question.
 
 Two more live at the repo root:
 
-- [CONTRIBUTING.md](CONTRIBUTING.md) — develop caret locally: setup, the `mise` workflow,
-  and where tests live.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — develop `caret` locally: setup, the `mise`
+  workflow, and where tests live.
 - [CLAUDE.md](CLAUDE.md) — for coding agents: routes a change to the rules-of-the-road
   that govern it.
 
+## 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.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Vendored third-party assets (the Lucide icons) are itemized

package/bin/caret-launcher

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+#
+# The stable launcher a launchd plist or systemd unit names (EXC-1160). Those
+# units must name an absolute executable path, but caret's runtime lives at a
+# versioned path that changes on every upgrade — and both Claude Code and
+# OpenCode replace their copy on their own schedule, without running
+# `caret install`. So the unit names this file, which caret owns at
+# $XDG_STATE_HOME/caret/bin/caret, and resolution happens here at exec time.
+#
+# Bash rather than TypeScript for the same reason bin/caret is: it has to locate
+# `bun` before any TypeScript can run.
+#
+# Three single-value records under $XDG_STATE_HOME/caret/launcher/ steer it, each
+# one line, each optional — a missing record degrades to the search path, to no
+# pin, and to skipping service teardown:
+#
+#   bun-path     absolute `bun`, recorded at service-install time
+#   pinned-root  a caret root to prefer over the highest installed version
+#   service      the launchd label WITHOUT `.plist` on macOS; the full unit name
+#                WITH `.service` on Linux. Only macOS appends a suffix below.
+#
+# Each record must end with a newline: `read -r` reports EOF on a file without
+# one, and the read is what decides the record exists.
+
+set -euo pipefail
+
+state="${XDG_STATE_HOME:-$HOME/.local/state}/caret"
+records="$state/launcher"
+claude_roots="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/caret/caret"
+opencode_roots="${XDG_CACHE_HOME:-$HOME/.cache}/opencode/packages/@macintacos"
+
+# The units name no log destination, so nothing opens this before caret does:
+# openDaemonStderr's 0700/0600 guarantee (src/daemon/lifecycle.ts) happens here for a
+# supervised daemon instead. Both modes are set at create time, so a chmod the
+# filesystem refuses cannot leave a umask-derived 0755/0644 pair behind (EXC-539).
+# Best-effort throughout: exiting under `set -e` would be a restart loop under
+# Restart=always / KeepAlive, so an unwritable state dir degrades to the supervisor's
+# own stream.
+open_daemon_log() {
+  # One literal, not "$dir/daemon-stderr.log": test/structure/service-log-path.test.ts
+  # matches the path daemonStderrLogFile() resolves as a substring of this file.
+  local file="$state/logs/daemon-stderr.log"
+  local dir="${file%/*}"
+  (
+    umask 077
+    mkdir -p "$dir"
+  ) 2>/dev/null || return 0
+  chmod 700 "$state" "$dir" 2>/dev/null || true
+  # The probe is what keeps the unguarded exec below from exiting the shell.
+  (
+    umask 077
+    : >>"$file"
+  ) 2>/dev/null || return 0
+  chmod 600 "$file" 2>/dev/null || true
+  exec >>"$file" 2>&1
+}
+
+read_record() {
+  local value
+  [ -f "$1" ] && read -r value <"$1" && [ -n "$value" ] && printf '%s' "$value"
+}
+
+# Highest of the `<version><TAB><path>` lines on stdin. A numeric field sort
+# rather than `sort -V`, which BSD sort does not carry everywhere. Ceiling: on an
+# equal numeric prefix the whole-line tiebreak puts a prerelease ABOVE the stable
+# release, so 0.15.0-rc.1 would beat 0.15.0. caret publishes no prereleases.
+highest() { sort -t. -k1,1n -k2,2n -k3,3n | tail -1 | cut -f2-; }
+
+# A candidate is a caret when it ships an executable bin/caret — the one file
+# every install method carries, tested the way it is used, since a non-executable
+# one would exec-fail at 126 and the supervisor would respawn into it forever.
+# Version comes from package.json, never the directory name: OpenCode names its
+# dir after the verbatim `plugin` specifier. The key is anchored so a minified
+# manifest yields nothing rather than a later key's value — a miss falls into the
+# branch that names the directory, a wrong version picks the wrong caret.
+candidate_version() {
+  [ -x "$1/bin/caret" ] || return 1
+  sed -n 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1/package.json" 2>/dev/null | head -1
+}
+
+# Every dir either cache offers, runnable caret or not — the difference between
+# a broken install (terminal) and an empty cache (eviction). The OpenCode entry
+# is a two-line npm project, not a caret root; the root is one level down.
+candidate_dirs() {
+  local dir
+  for dir in "$claude_roots"/* "$opencode_roots"/caret*/node_modules/@macintacos/caret; do
+    if [ -d "$dir" ]; then printf '%s\n' "$dir"; fi
+  done
+}
+
+candidates() {
+  local dir version
+  candidate_dirs | while read -r dir; do
+    version="$(candidate_version "$dir" || true)"
+    if [ -n "$version" ]; then printf '%s\t%s\n' "$version" "$dir"; fi
+  done
+}
+
+resolve_root() {
+  local pin
+  pin="$(read_record "$records/pinned-root" || true)"
+  if [ -n "$pin" ] && [ -x "$pin/bin/caret" ]; then
+    printf '%s' "$pin"
+    return 0
+  fi
+  candidates | highest
+}
+
+# The newest mise-managed bun, for a machine whose mise shims are not on the
+# supervisor's PATH.
+mise_bun_dir() {
+  local dir
+  for dir in "$1"/mise/installs/bun/*/bin; do
+    if [ -x "$dir/bun" ]; then printf '%s\t%s\n' "$(basename "$(dirname "$dir")")" "$dir"; fi
+  done | highest
+}
+
+find_bun() {
+  local recorded dir dirs data="${XDG_DATA_HOME:-$HOME/.local/share}"
+  recorded="$(read_record "$records/bun-path" || true)"
+  # A record naming something other than bun falls through to the search rather
+  # than short-circuiting it: an install running as the compiled binary records
+  # its own execPath, which is caret, not bun.
+  if [ -x "$recorded" ] && [ "$(basename "$recorded")" = bun ]; then
+    printf '%s' "$recorded"
+    return 0
+  fi
+  dirs=("$HOME/.bun/bin" /opt/homebrew/bin /usr/local/bin "$data/mise/shims"
+    "$(mise_bun_dir "$data")" "$HOME/.asdf/shims")
+  for dir in "${dirs[@]}"; do
+    if [ -n "$dir" ] && [ -x "$dir/bun" ]; then
+      printf '%s' "$dir/bun"
+      return 0
+    fi
+  done
+  printf 'caret-launcher: no bun (record %s: %s); searched %s\n' \
+    "$records/bun-path" "${recorded:-unset}" "${dirs[*]}" >&2
+  printf 'caret-launcher: install bun (https://bun.sh), then run: caret install\n' >&2
+  return 1
+}
+
+# launchd carries no per-status restart allowlist, so a launcher that cannot run
+# stops its own agent rather than being respawned into the same failure. The unit
+# file stays for a later `caret install`; systemd honours 78 on its own.
+stop_agent() {
+  local service
+  [ "$(uname)" = Darwin ] || return 0
+  service="$(read_record "$records/service" || true)"
+  if [ -n "$service" ]; then launchctl bootout "gui/$(id -u)/$service" || true; fi
+}
+
+# caret cannot outlive its own install: with no caret left anywhere, the launcher
+# tears its service down and deletes itself. Returns non-zero without touching
+# anything when there is no `service` record — nothing here installed a
+# supervisor, so this launcher cannot know what still names it, and deleting
+# itself would leave whatever does respawning on ENOENT. Deleting only bin/ and
+# the records leaves review state for a reinstall.
+evict() {
+  local service unit
+  service="$(read_record "$records/service" || true)"
+  [ -n "$service" ] || return 1
+  if [ "$(uname)" = Darwin ]; then
+    launchctl bootout "gui/$(id -u)/$service" || true
+    unit="$HOME/Library/LaunchAgents/$service.plist"
+  else
+    systemctl --user disable --now "$service" || true
+    unit="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/$service"
+  fi
+  printf 'caret-launcher: no caret installed anywhere; removing %s and %s.\n' \
+    "$unit" "$state/bin" >&2
+  rm -f "$unit"
+  rm -rf "${state:?}/bin" "${state:?}/launcher"
+  exit 0
+}
+
+# Only under a supervisor: a hand-run launcher keeps its diagnostics on the terminal.
+if [ "${CARET_SUPERVISED:-}" = 1 ]; then open_daemon_log; fi
+
+# Only a total miss re-probes. A populated version dir with no runnable bin/caret
+# is far more likely a bad install than an extraction caught mid-flight, and that
+# path is recoverable with `caret install`; an empty cache is the one whose branch
+# deletes things, so it is the one worth waiting on.
+root="$(resolve_root)"
+for _ in 1 2; do
+  if [ -n "$root" ] || [ -n "$(candidate_dirs)" ]; then break; fi
+  sleep 5
+  root="$(resolve_root)"
+done
+
+if [ -z "$root" ]; then
+  found="$(candidate_dirs)"
+  if [ -z "$found" ]; then evict || true; fi
+  printf 'caret-launcher: no runnable bin/caret under any of:\n%s\n' \
+    "${found:-(no install directories at all)}" >&2
+  printf 'caret-launcher: run: caret install — to restore the service.\n' >&2
+  stop_agent
+  exit 78
+fi
+
+bun="$(find_bun || true)"
+if [ -z "$bun" ]; then
+  stop_agent
+  exit 78
+fi
+
+# bun's directory and nothing else — no CARET_*, and in particular never
+# BUN_FEATURE_FLAG_NO_ORPHANS.
+PATH="$(dirname "$bun"):$PATH" exec "$root/bin/caret" "$@"

package/commands/demo.md

@@ -1,14 +1,14 @@
 ---
-description: Demo caret by presenting a short fake plan via ExitPlanMode
+description: Demo caret by presenting a short plan about this repo via ExitPlanMode
 ---
 
-Read the short demo-plan fixture at `${CLAUDE_PLUGIN_ROOT}/scripts/tasks/dev/demo-plan.md`
-and present its contents **verbatim** to the user by calling `ExitPlanMode` with that
-markdown as the `plan` argument. This is a small, self-contained plan meant only to show
-off the review flow — `mise run dev` seeds a different, larger fixture. Do **not** do any
-real work, research, or file edits — this is only to exercise the review flow. If the
-fixture can't be read, fall back to inventing a short, plausible-but-fake plan (a Context
-section, an Approach section, and a couple of Steps).
+Call `EnterPlanMode` first: `ExitPlanMode` is refused outside plan mode. Then read
+`${CLAUDE_PLUGIN_ROOT}/templates/demo.md` and follow its leading HTML comment exactly to
+fill the slots. Write everything after that comment to the plan file your plan-mode
+instructions name, then call `ExitPlanMode` with that same text as its `plan` argument —
+caret reviews the argument, so a call without it reaches the review UI empty. Do **no**
+other research and edit **no** file but the plan file — this is only to exercise the
+review flow.
 
 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
@@ -17,5 +17,6 @@ decision flows back to you:
 - **Approved** → proceed (this is just a demo, so simply acknowledge that caret approved
   the plan and stop).
 - **Changes requested** → the feedback arrives as the denial reason. Revise the plan
-  accordingly and present it again via `ExitPlanMode` (caret captures it as a new
-  version).
+  accordingly, keeping it about the same size, update the plan file, and call
+  `ExitPlanMode` again with the revised text as its `plan` argument (caret captures it as
+  a new version).