@macintacos/caret 0.14.0 → 1.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "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,10 +1,5 @@
 # 🥕 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 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
@@ -18,16 +13,15 @@ Want to develop caret rather than use it? Start with [CONTRIBUTING.md](CONTRIBUT
 
 ![caret review UI with an inline annotation, stitched across four themes](doc/assets/caret-review-ui.png)
 
-[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.
+[Check out a short demo here!](https://youtu.be/zesv5AunUW4)
 
 ## Install
 
 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 login service (launchd
+> or systemd). 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.
 
@@ -42,18 +36,45 @@ prebuilt artifacts, the `/caret:*` slash commands, and the [rumdl](https://rumdl
 plan formatter. Where it can't ask — off a terminal — it installs into every agent it
 detected.
 
+Every install at a terminal also asks whether to keep caret's review UI running all the
+time, and doesn't remember the answer. Keeping it running registers a service that starts
+at login and serves the UI at `http://caret.localhost:42718`; the other answer is
+[running caret yourself](#running-caret-yourself). Off a terminal it doesn't ask, and
+leaves the service however it finds it. To turn the service off later, run `caret install`
+and answer **I'll run it myself**, or use `--uninstall` — see
+[turning caret off](doc/RUNNING.md#turning-caret-off) and
+[the caret service](doc/RUNNING.md#the-caret-service).
+
 Two steps finish the job:
 
 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.
+
+| Flag          | What it does                                          |
+| ------------- | ----------------------------------------------------- |
+| `--dry-run`   | Preview the run without changing anything.            |
+| `--refresh`   | Update an existing install.                           |
+| `--uninstall` | Remove caret from every agent, and from this machine. |
+
+### 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 --no-cache @macintacos/caret@latest serve
+```
+
+It keeps the UI up at `http://caret.localhost:42718` until you press Ctrl+C. If caret
+already started on demand, `serve` stops that copy and takes the port; if caret's service
+still holds it, `serve` says so and exits. Without `serve`, caret still works: it starts
+when your agent submits a plan, and stops about a minute after the last review is
+resolved.
 
-| 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.                    |
+After updating caret, run `caret serve` again yourself: the first plan from the new
+version stops the old one, and nothing brings it back.
 
 ### Updating and uninstalling
 
@@ -64,10 +85,12 @@ 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.
+An update picks its agents exactly as a fresh install does — the chooser at a terminal,
+detection otherwise — and at a terminal asks the review-UI question again; an uninstall
+takes every agent. Where caret's service stays registered, `--refresh` also cycles it onto
+the new version, and restarting each agent loads that agent's own updated copy. 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
@@ -100,9 +123,10 @@ 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

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 prefs and 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).