agentlane 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -0
- package/dist/agents/claude-plugin.js +54 -8
- package/dist/agents/cli.js +11 -4
- package/dist/agents/hook-check.js +290 -0
- package/dist/agents/launcher.js +34 -6
- package/dist/agents/wiring-check.js +10 -4
- package/dist/agents/wiring.js +6 -33
- package/dist/browser/env.js +27 -7
- package/dist/browser/install.js +144 -6
- package/dist/browser/lane-browser.js +6 -3
- package/dist/browser/stop.js +2 -17
- package/dist/cache/key.js +23 -11
- package/dist/cli.js +63 -23
- package/dist/devices/backend.js +6 -0
- package/dist/devices/emulator.js +15 -5
- package/dist/devices/simctl.js +15 -3
- package/dist/disk-limits.js +134 -0
- package/dist/driver/caller.js +21 -6
- package/dist/driver/client.js +9 -5
- package/dist/driver/engine.js +29 -14
- package/dist/driver/install.js +88 -36
- package/dist/driver/paths.js +15 -11
- package/dist/driver/session.js +4 -1
- package/dist/driver/superseded.js +378 -0
- package/dist/driver-cli.js +32 -23
- package/dist/evidence/device.js +4 -0
- package/dist/evidence/evidence.js +4 -2
- package/dist/evidence/files.js +68 -0
- package/dist/evidence/strays.js +107 -0
- package/dist/hooks/env.js +2 -1
- package/dist/mcp/server.js +15 -0
- package/dist/mcp/tools.js +9 -1
- package/dist/plugin/guard.js +30 -0
- package/dist/plugin/hook-cli.js +101 -6
- package/dist/plugin/hook-mark.js +73 -0
- package/dist/plugin/hook-once.js +78 -0
- package/dist/plugin/shell.js +109 -8
- package/dist/processes.js +52 -2
- package/dist/registry/config.js +12 -8
- package/dist/registry/holds.js +37 -0
- package/dist/registry/leases.js +109 -0
- package/dist/registry/owner-checks.js +55 -0
- package/dist/registry/owner.js +18 -0
- package/dist/registry/parks.js +60 -0
- package/dist/registry/paths.js +28 -4
- package/dist/registry/ports.js +5 -1
- package/dist/registry/prune.js +643 -24
- package/dist/registry/refusal.js +1 -0
- package/dist/registry/registry.js +1258 -235
- package/dist/registry/rows.js +18 -4
- package/dist/registry/status.js +51 -8
- package/dist/registry/store.js +63 -1
- package/dist/registry/touch.js +180 -0
- package/dist/registry-cli.js +197 -36
- package/dist/services/services.js +223 -54
- package/dist/services/system.js +2 -1
- package/dist/up/answers.js +124 -0
- package/dist/up/doctor.js +27 -3
- package/dist/up/exec.js +29 -4
- package/dist/up/lane-files.js +26 -8
- package/dist/up/lane-services.js +8 -3
- package/dist/up/park.js +146 -0
- package/dist/up/preflight.js +2 -10
- package/dist/up/release.js +20 -24
- package/dist/up/restart.js +9 -2
- package/dist/up/sweep.js +437 -0
- package/dist/up/up.js +33 -12
- package/dist/up/wake.js +124 -0
- package/dist/up/waker.js +49 -0
- package/dist/up-cli.js +6 -1
- package/package.json +2 -2
- package/skills/dev-loop/SKILL.md +7 -5
- package/skills/drive/SKILL.md +4 -0
- package/skills/setup/SKILL.md +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,82 @@
|
|
|
2
2
|
|
|
3
3
|
Newest first.
|
|
4
4
|
|
|
5
|
+
## 0.5.0
|
|
6
|
+
|
|
7
|
+
A lane now gives its simulator or emulator back when nobody uses it, and ends on its own once its session is gone, whether or not the session ran `release` or its session-end hook fired. The hooks move into every agent's project settings, plugin or not, and `doctor` proves they run. `prune` and the tool installs leave less on disk. This version runs beside 0.4.1 on the same Mac; "Sharing a Mac with 0.4.1" lists what 0.4.1 still does differently.
|
|
8
|
+
|
|
9
|
+
### Moving from 0.4.1
|
|
10
|
+
|
|
11
|
+
1. **Run `init` again in each project, and commit what it changes.** `node_modules/.bin/agentlane init`, with the agents the project uses, rewrites the guard and session-end hooks in each agent's project settings. The new hooks start the toolkit only for commands that name a device or browser tool, find the toolkit in another worktree of the repository, and read names split by quotes, backslashes, line continuations, `$"…"` or brace expansion. Until then, `doctor` warns that the hooks are stale. Codex asks you to trust the changed hooks again with `/hooks`. The Claude Code plugin's own hooks update with the plugin.
|
|
12
|
+
2. **Projects that leave Claude Code's hooks to the plugin need that run too.** A project whose `.claude/settings.json` enables `agentlane@agentlane` or `agent-env@agent-env` and has no hooks of its own gets them from `init`, which renames the 0.2.x plugin key as before. Until then, `doctor` fails `hooks claude` on a Mac where the plugin isn't installed, because no hook runs there.
|
|
13
|
+
3. **Hold the lanes a person looks at.** A lane now parks 30 minutes after its last call, so a simulator left up for someone to look at shuts down. The `dev-loop` and `drive` skills tell agents to run `agentlane keep`, and a script that leaves an app up for a person runs it too.
|
|
14
|
+
4. **Leave `config.json`'s `idleHours` until 0.4.1 is gone.** This version accepts it and ignores it, because no lane takes over another any more. Remove it once no project on the Mac runs 0.4.1 or earlier. Don't set `parkMinutes` while one does: those versions refuse a `config.json` with a setting they don't know.
|
|
15
|
+
5. **Update scripts that read the JSON.** `claim --json` drops `tookOver` and `freed`. `prune --json` drops `unrecorded`: read `orphans`, and `kept` for the devices kept with a reason. `lanes --json` and `status --json` add `park`, `hold` and `ownerGone` to each lane, and `state` (`running`, `gone` or `unknown`) and `aliveAt` to its processes.
|
|
16
|
+
6. **Run `prune` with your state variables.** If a project or shell sets `AGENTLANE_STATE_DIR` or `AGENT_ENV_STATE_DIR`, run `prune` with the same variables that project's agentlane runs with. `prune --yes` now deletes a shut-down device named like a pool device that no registry it reads records, so a device whose lane is in a registry it doesn't read is deleted.
|
|
17
|
+
7. **To get 0.2.x's disk back, release its lanes first.** `prune --yes` deletes 0.2.x's downloads and build cache only while no registry 0.2.x may use has a lane or a waiting claim. Where agentlane shares 0.2.x's state folder, that counts every lane, so release them all (`agentlane status` lists none), then run `prune --yes` from each project that ran 0.2.x, so its build cache is covered.
|
|
18
|
+
8. **Delete old init backups by hand.** `init` now keeps its five newest backups per project. It never removes the ones earlier versions named without the project hash (`<state dir>/init-backups/<stamp>-<folder>`).
|
|
19
|
+
|
|
20
|
+
### Sharing a Mac with 0.4.1
|
|
21
|
+
|
|
22
|
+
- **One registry, still format 1.** This version adds tables 0.4.1 doesn't read (`parks`, `holds`, `owner_checks`, `device_leases`, `process_alive`) and keeps the format version 0.4.1 checks. When 0.4.1 ends a lane, its park, hold and checks go with it.
|
|
23
|
+
- **A parked lane is a live lane to 0.4.1.** 0.4.1 sees it alive, with its ports held, and sees its device as free.
|
|
24
|
+
- **0.4.1 still ends a gone owner's lane at once.** Its own claims end such a lane as soon as they find it, and judge a Claude Code owner by its pid. So the 30-minute window in which a returning session takes its lane back holds once every project on the Mac has upgraded.
|
|
25
|
+
- **0.4.1 can still take over a parked or held lane.** Once a lane's last call is over 2 hours old (its `idleHours`), a 0.4.1 claim short of ports or devices can take the lane and end it, teardowns included. Nothing is handed to two lanes, but a lane of this version can end that way. A `keep` counts as a call, so it puts that off.
|
|
26
|
+
- **0.4.1 refuses a `config.json` that sets `parkMinutes`**, with "unknown setting 'parkMinutes'".
|
|
27
|
+
- **A device shutdown cut short.** If a process of this version is killed while it shuts a device down, and only 0.4.1 processes run afterwards, that device's slot and memory stay held until a process of this version claims or releases, or the Mac restarts. Meanwhile, 0.4.1 claims that need the slot are refused `pool-busy`, naming "a process claiming a lane (pid 1)". No second device is made.
|
|
28
|
+
- **A pool over its size.** If a Mac restart with 0.4.1 in use leaves the pool with more devices than its size, this version deletes the extra device once its shutdown or delete ends, with a note. If that delete fails, the device stays until `agentlane prune`.
|
|
29
|
+
- **Tool versions.** A lane of 0.4.1 runs agent-browser without naming its browser, so while one does, every older browser stays. A project still on 0.4.1 downloads its tools again the next time it needs them, if nothing used them when they were removed.
|
|
30
|
+
|
|
31
|
+
### New
|
|
32
|
+
|
|
33
|
+
- **Parking.** While its owner is alive, a lane parks 30 minutes after its last call. Its dev servers, browser, driver and Maestro stop, its recordings end, its simulator or emulator shuts down and goes back to the pool, and its bundler pin, dial defaults and `adb reverse` rules are removed. It keeps its ports, its resources, its browser's saved login and its record. The next call brings it all back before it runs: `exec`, `restart`, `up`, any MCP tool, and the CLI's `look`, `run`, `screenshot`, `record`, `driver start`, `evidence` and `device`. With the pool full, that call waits for a device as `up` does. A call that comes while the lane is being parked or brought back waits up to 30 minutes, then is refused with the new code `lane-busy`. `status` shows `parked since …; its next call brings back …`, `lanes --json` has a `park` field, and `doctor` warns `parked`. The window is `parkMinutes` in `config.json`, 30 by default.
|
|
34
|
+
- **`agentlane keep --for <time> --reason <text>`** holds this session's lane for its folder up past the park window, while a person looks at the running app. `--for` takes minutes or hours (`45m`, `2h`, `1h30m`), 1 hour when left out and 24 hours at most; a longer or malformed time is refused with exit 2. `--reason` is required. A second `keep` replaces the first. `keep` counts as a call, and on a parked lane it doesn't wake anything: the next call brings the lane back and the hold keeps it up. `release` ends the hold with the lane, and so does the owner being found gone. `status` shows `held until <time> (<left> left): <reason>`, and `lanes --json` has a `hold` field. No setting holds lanes by default.
|
|
35
|
+
- **A lane whose owner is gone ends on its own.** An owner is gone when its process has exited, its pid belongs to another process, or the lane's folder was deleted. The sweep finds such a lane within 5 minutes while any agentlane MCP server runs, and otherwise at the next agentlane command. It parks the lane at once, and 30 minutes later ends it with everything `release` does. In that window, the owner's Claude Code session (by `CLAUDE_CODE_SESSION_ID`) or Codex thread takes the lane back, with its ports and resources, by calling on it from its folder; the next call wakes it. No other session gets the lane. `status` shows an `owner gone` line with when the lane ends and which session can take it back, and `lanes --json` has `ownerGone`. A session-end hook still releases at once.
|
|
36
|
+
- **The sweep.** There is no daemon. Every agentlane command checks, from one registry read, whether the sweep has work, and when it does starts it in a detached process and carries on. Each running MCP server does the same every minute. The sweep parks lanes past the window, checks the owners no call has shown alive in the last few minutes, ends lanes whose window has passed, stops a screen recording an ended lane left running (only after `ps` proves the pid is that recorder), and removes an ended lane's folder, evidence included, seven days after the lane ended. It logs to `sweep.log` in the state folder.
|
|
37
|
+
- **`agentlane reap [--json]`** runs the sweep now and prints what it did, for running from cron or launchd.
|
|
38
|
+
- **The guard counts as a call.** A `simctl`, `adb`, `playwright-cli` or `agent-browser` command the guard lets through on the session's own device or browser counts as a call on that lane, so a lane an agent drives by hand isn't parked.
|
|
39
|
+
- **`doctor` proves the hooks run.** A `hooks <agent>` line per wired agent reads the mark the hook left the last time it reached the toolkit. When the mark is missing, over a day old, from another toolkit or older than the hook file, the toolkit's files or the Node the hook ran on, doctor runs the guard hook on a harmless command. The line fails with a fix when the hook can't run: no toolkit, a dangling `node_modules/.bin/agentlane`, a broken command, a missing hook script, or a Claude Code plugin that the project leaves the hooks to and that isn't installed. When the toolkit is older than doctor, it says to update it. `doctor` also warns when the project enables the plugin and Claude Code hasn't installed it.
|
|
40
|
+
- **`status` checks the processes it lists.** Each process a lane started shows as running, gone or can't tell. A pid another process has taken counts as gone.
|
|
41
|
+
- **`prune` finds lost devices and what 0.2.x left.** It lists the simulators and emulators named like pool devices (`agentlane-pool-*`, `agentlane-emu-*`, `agent-env-pool-*`, `agent-env-emu-*`) that no registry it reads records, each with its size, and `prune --yes` deletes them, only while simctl or adb lists them as shut down. It reads the registries in `$AGENTLANE_STATE_DIR` and `$AGENT_ENV_STATE_DIR` when set, and in the `agentlane` and `agent-env` folders of `$XDG_STATE_HOME` and `~/.local/state`. Before each deletion it locks them all and checks again. This reverses 0.3.0's promise that a device the registry has no record of is never deleted; 0.3.0 kept them because a registry in another state folder might hold them, which is still true of a folder none of those variables names. prune also lists 0.2.x's downloads in `~/.local/share/agent-env` and its build cache in `.git/agent-env`, in this repository and every repository a registry names, and deletes them only while no registry 0.2.x may use has a lane or a waiting claim. It refuses a folder whose real path isn't 0.2.x's own. Before deleting one it renames it to `<path>.removing-<time>-<hex>`, so a second prune can't give it back to a 0.2.x lane; if a 0.2.x lane appears while prune works, prune puts back what it moved, and the next `prune --yes` finishes or undoes a run that stopped partway.
|
|
42
|
+
- **Older tool versions go.** Once agentlane has installed and checked a newer pin of its patched Maestro, playwright-core, Chrome for Testing, the headless shell, ffmpeg or agent-browser, it removes the older versions it installed itself in `~/.local/share/agentlane`. A version stays while a running process names it, a lane's files in this version's registry or 0.2.x's name it, another process is installing it, a kept version runs it, or, for a browser, a link in the browsers folder's `.links` names it, such as the one a project's own `npx playwright install` writes. If `ps` or a registry can't be read, nothing is removed. It never removes newer versions, folders without its install marker, or `~/.local/share/agent-env`. agent-browser lanes now name their browsers in `bin/.browsers`, and the lane's `agent-browser` sets `AGENT_BROWSER_EXECUTABLE_PATH` to its headless shell. A Maestro from an earlier pin, such as `2.11.0-agentenv.3`, goes at the first install of the current one unless something uses it.
|
|
43
|
+
- **agentlane's own files have limits.** A lane's recorded steps (`<state>/driver/<id>.steps.jsonl`) keep the newest 512 KiB of runs once they pass 1 MiB, so in a very long session the oldest steps drop out of `record save`. Each run records when it ran, and a device trace that spans a cut holds only the runs after `evidence trace start`. `<state>/emulators/<avd>.log` moves to `<name>.1` when it passes 5 MiB at a boot, and `session-end.log` and `sweep.log` when they pass 1 MiB. `init` names its backups `<stamp>-<folder>-<hash of the project's path>` and keeps the five newest per project. Evidence folders are never cut.
|
|
44
|
+
- **A Postgres recipe.** The resources page shows how to clone each lane's database from a template built once per migrations fingerprint, with `examples/expo-app/scripts/lane-pg.sh`.
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
|
|
48
|
+
- **No lane takes over another.** At any idle age, a claim short of a device waits in the queue, and a claim short of ports is refused, naming the lanes that hold them.
|
|
49
|
+
- **A claim no longer ends other sessions' lanes.** It records a gone owner and leaves the lane to the sweep.
|
|
50
|
+
- **The hooks always go in each agent's project settings.** `init` writes Claude Code's guard and session-end hooks into `.claude/settings.json` even when the project enables the plugin, which still brings the skills and the MCP server. There the session-end hook gets its declared 10 seconds; Claude Code gives a plugin's session-end hook 1.5 seconds whatever it declares, so the plugin's hook only starts the release. Where both copies run, both guards answer the same and one release runs. The hooks look for the toolkit from the hook's folder upwards, then in the repository's other worktrees.
|
|
51
|
+
- **The hooks start Node only for device and browser commands.** The hooks `init` writes check in the shell that the command names `simctl`, `adb`, `emulator`, `avdmanager`, `playwright-cli`, `@playwright/cli` or `agent-browser` before they start the toolkit, as the plugin's hook already did. Both read names split by quotes, backslashes, line continuations (in Copilot's hook input too), `$"…"` or brace expansion, and a command with braces that names none of them, such as `mkdir -p src/{a,b}`, starts no Node.
|
|
52
|
+
- **The guard reads `$"…"` quoting and brace expansion.** It judges `a$"db" shell`, `a{d,}b shell`, `e{nv,mulator} -avd …` and `adb -s emulator-55{54,60} …` as the commands bash runs.
|
|
53
|
+
- **Every call on a lane counts as its last use.** `driver stop`, `doctor`, `keep` and `touch` count, and so do evidence commands and device controls that fail. `driver status` and `evidence list` don't. A long `exec` command, `up` hook or tool call counts once a minute while it runs. When the registry is busy, a driving command records its use in the lane's folder (`last-call.json`) and carries on, instead of waiting up to 120 seconds and failing.
|
|
54
|
+
- **Slow device work runs outside the registry's lock.** A claim, an `up`, a release and the driver's last-used updates no longer wait while another lane creates a simulator or AVD, lists devices or shuts one down. While a pool device is being shut down or deleted, `status` lists it as `<device name>.shutdown.<hex>` (or `.delete.`) in state `creating`, a `pool-busy` refusal names "a process shutting down <device> (pid N)", and `prune` keeps it with that pid. Where `ps` can't read pid 1, as in some sandboxes, shutdowns and deletes still run inside the lock. A claim that keeps seeing lanes end while it lists devices looks again while its `--timeout` lasts, then is refused `pool-busy`, naming the lanes that ended.
|
|
55
|
+
- **An interrupted release finishes later.** If a release is stopped while it shuts its device down, the next claim or release finishes the shutdown and puts the device back in the pool shut down, where a recovering release used to put it back booted.
|
|
56
|
+
- **Stopping a service whose leader has exited.** `release`, `restart`, a park and a reap stop the processes a service started that outlive its leader, where they used to refuse with a `kill` hint. They stop the processes left in the service's group that started with its leader or before agentlane last saw the leader running, which covers the workers of an `exec`-style dev server (expo, vite, a node API) whose main process died first. agentlane records that sighting when the service passes its ready check, and the sweep records it again at most every 10 minutes. Without that proof they still refuse, with the hint. After the grace, SIGKILL goes to the whole group, so helpers started after SIGTERM end too. If `ps` can't list the processes a service started outside its group, they ask once more and then stop the group anyway, reporting those processes as not found, or as left alone with a `kill` command.
|
|
57
|
+
- **Stop messages say who got what.** `stopped api (…) with SIGKILL to process group 4242, which SIGTERM did not end` replaces `… with SIGKILL after SIGTERM was ignored`, and a stop that can't prove what is left says what it sent. When a process can't be checked, `release`, `restart`, `doctor` and `up` name the read that failed (`ps could not read when it started`, `its working directory could not be read`) instead of "ps or lsof failed".
|
|
58
|
+
- **`up` asks each question once.** It runs `xcrun simctl list runtimes`, `xcodebuild -version` and the Java 17 search once per `up` and hands the driver the JDK it found, reads the simulator's state once before booting and once after, no longer lists devices just to prune lane files, and reuses each cache input's hash after the build.
|
|
59
|
+
- **Ended lanes' folders go seven days after the lane ended.** `up`, `claim` and the sweep count from the end the registry records, where they used to count from the folder's last write, which could remove a week-old lane's evidence as soon as it ended.
|
|
60
|
+
- **`prune` needs `HOME`**, and exits 2 without it.
|
|
61
|
+
|
|
62
|
+
### Fixed
|
|
63
|
+
|
|
64
|
+
- A browser lane driven only through the MCP tools counts as in use. Its last use never moved, so another lane could take it over while it was in use.
|
|
65
|
+
- A reap does everything a release does. 0.4.1's reap of a dead owner's lane skipped its recordings, the bundler pin, the dial defaults, the `adb reverse` rules and the project's teardown hook.
|
|
66
|
+
- A service that fails to start and can't be stopped afterwards stays in the lane's record, and the failure says so. The lane used to forget a process that may still have been running.
|
|
67
|
+
- A dev server that has exited but whose parent hasn't collected it yet is reported stopped, not as having survived SIGKILL.
|
|
68
|
+
- An invalid `config.json` no longer shuts down a lane's warm driver. The driver, and a long command's once-a-minute count, try the last-used update again until the file reads.
|
|
69
|
+
- A claim no longer refuses a free port as "held by processes the registry did not start" when the process probing it was busy for over half a second.
|
|
70
|
+
- `up`'s preflight, the driver and `maestro/build.sh` ask `java_home` for JDK 17 with `-F`, so a Mac with JDK 21 registered and an unregistered JDK 17, such as Homebrew's `openjdk@17`, finds Homebrew's.
|
|
71
|
+
- The driver looks past a `JAVA_HOME` that names a JDK other than 17 for one that is, as `up` does, so a driver `up` started restarts after an idle stop or a crash. A non-17 `AGENTLANE_JAVA_HOME` is still refused.
|
|
72
|
+
- `prune` shuts down a free pool simulator that simctl lists as booting or shutting down before it deletes it, and lists it as "starting or stopping, so it is shut down first" (`"state": "changing"` in `--json`).
|
|
73
|
+
- `prune --yes` reports what happened when its registry lock fails to commit after a step: a 0.2.x folder it took for removal is deleted and reported deleted, and one it put back for a 0.2.x lane is reported put back.
|
|
74
|
+
- On Linux, a reap or release stops the services of a lane whose worktree folder was deleted. It used to leave them running, with `pid N is no longer in <folder>`, because Linux names a deleted working folder with ` (deleted)` after it.
|
|
75
|
+
|
|
76
|
+
### Known issues
|
|
77
|
+
|
|
78
|
+
- **An interactive Codex session's lane ends only through Codex's session-end hook.** Codex runs a thread's commands under its shared `codex app-server`, so the lane records no process for its owner (`codex thread <id> (no process recorded)`) and the sweep can't tell when the thread is gone. The hook `init` writes into `.codex/hooks.json` releases the lane when the app server unloads the thread. When that hook doesn't run, for example because the project's hooks aren't trusted, the lane parks once it goes unused and stays parked, and `status` shows `left alone: its owner can't be judged`. To free it, run `agentlane release` in the lane's folder from the Codex thread that holds it, or `agentlane release --lane <id> --force` from any shell.
|
|
79
|
+
- **A Codex app server restart releases the lanes of Codex sessions that are still open.** When the app server stops or restarts, through `codex app-server daemon restart` or its own updater, it runs the session-end hook for every thread it has loaded, and the hook releases each thread's lane at once. 0.4.1 does the same. The session's next `up` or `claim` gives it a new lane.
|
|
80
|
+
|
|
5
81
|
## 0.4.1
|
|
6
82
|
|
|
7
83
|
### Changed
|
|
@@ -38,6 +38,15 @@ function sessionPluginDir(env) {
|
|
|
38
38
|
* settings count under 0.2.x's plugin name too, because init renames it there.
|
|
39
39
|
*/
|
|
40
40
|
export function claudePluginSources(root, env) {
|
|
41
|
+
const enabled = enabledPlugins(root, env);
|
|
42
|
+
const order = ['project', 'local', 'user'];
|
|
43
|
+
const sources = [...new Set(enabled.map(e => e.source))].sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
|
|
44
|
+
const dir = sessionPluginDir(env);
|
|
45
|
+
if (dir !== null)
|
|
46
|
+
sources.push({ kind: 'session', dir });
|
|
47
|
+
return sources;
|
|
48
|
+
}
|
|
49
|
+
function enabledPlugins(root, env) {
|
|
41
50
|
const scopes = [
|
|
42
51
|
{ source: { kind: 'local', file: CLAUDE_LOCAL_SETTINGS }, at: path.join(root, CLAUDE_LOCAL_SETTINGS), names: [TOOL] },
|
|
43
52
|
{ source: { kind: 'project', file: CLAUDE_SETTINGS }, at: path.join(root, CLAUDE_SETTINGS), names: [TOOL, FORMER.tool] },
|
|
@@ -45,22 +54,59 @@ export function claudePluginSources(root, env) {
|
|
|
45
54
|
const user = path.join(claudeConfigDir(env), 'settings.json');
|
|
46
55
|
scopes.push({ source: { kind: 'user', file: user }, at: user, names: [TOOL] });
|
|
47
56
|
const decided = new Set();
|
|
48
|
-
const
|
|
57
|
+
const enabled = [];
|
|
49
58
|
for (const { source, at, names } of scopes) {
|
|
50
59
|
for (const [key, on] of toolkitEntries(jsonObjectAt(at), names)) {
|
|
51
60
|
if (decided.has(key))
|
|
52
61
|
continue;
|
|
53
62
|
decided.add(key);
|
|
54
63
|
if (on)
|
|
55
|
-
|
|
64
|
+
enabled.push({ source, key });
|
|
56
65
|
}
|
|
57
66
|
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
if (
|
|
62
|
-
|
|
63
|
-
|
|
67
|
+
return enabled;
|
|
68
|
+
}
|
|
69
|
+
function sameDir(a, b) {
|
|
70
|
+
if (typeof a !== 'string')
|
|
71
|
+
return false;
|
|
72
|
+
try {
|
|
73
|
+
return fs.realpathSync(a) === fs.realpathSync(b);
|
|
74
|
+
}
|
|
75
|
+
catch {
|
|
76
|
+
return path.resolve(a) === path.resolve(b);
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Where Claude Code loads the enabled plugin from on this Mac. Claude Code records what it installed in
|
|
81
|
+
* `plugins/installed_plugins.json` under its config folder: format 2 maps `<plugin>@<marketplace>` to a list of
|
|
82
|
+
* installs, each with a `scope`, a `projectPath` for project and local scopes, and an `installPath`.
|
|
83
|
+
*/
|
|
84
|
+
export function claudePluginInstall(root, env) {
|
|
85
|
+
const session = sessionPluginDir(env);
|
|
86
|
+
if (session !== null)
|
|
87
|
+
return { kind: 'loaded', dir: session };
|
|
88
|
+
const keys = enabledPlugins(root, env).map(e => e.key);
|
|
89
|
+
if (keys.length === 0)
|
|
90
|
+
return null;
|
|
91
|
+
const file = path.join(claudeConfigDir(env), 'plugins', 'installed_plugins.json');
|
|
92
|
+
if (!fs.existsSync(file))
|
|
93
|
+
return { kind: 'not-installed', keys };
|
|
94
|
+
const plugins = jsonObjectAt(file)?.plugins;
|
|
95
|
+
if (typeof plugins !== 'object' || plugins === null)
|
|
96
|
+
return { kind: 'unknown' };
|
|
97
|
+
for (const key of keys) {
|
|
98
|
+
const listed = plugins[key];
|
|
99
|
+
const installs = Array.isArray(listed) ? listed : listed === undefined ? [] : [listed];
|
|
100
|
+
for (const install of installs) {
|
|
101
|
+
if (typeof install !== 'object' || install === null)
|
|
102
|
+
continue;
|
|
103
|
+
const { scope, projectPath, installPath } = install;
|
|
104
|
+
const here = scope === undefined || scope === 'user' || sameDir(projectPath, root);
|
|
105
|
+
if (here && typeof installPath === 'string')
|
|
106
|
+
return { kind: 'loaded', dir: installPath };
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return { kind: 'not-installed', keys };
|
|
64
110
|
}
|
|
65
111
|
export function claudePluginSource(root, env) {
|
|
66
112
|
return claudePluginSources(root, env)[0] ?? null;
|
package/dist/agents/cli.js
CHANGED
|
@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
|
|
|
2
2
|
import fs from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { parseArgs } from 'node:util';
|
|
5
|
+
import { backupProject, keepNewestBackups } from "../disk-limits.js";
|
|
5
6
|
import { CLI, CONFIG_FILE, TOOL } from "../name.js";
|
|
6
7
|
import { findConfigFile } from "../project/config.js";
|
|
7
8
|
import { AGENTS } from "../registry/owner.js";
|
|
@@ -16,6 +17,7 @@ import { terminalScreen } from "./init-screen.js";
|
|
|
16
17
|
import { addCommand, installedVersion, listedRange, nearestPackage, PACKAGE_SPEC_ENV, packageManagerOf, shellLine, toolVersion, } from "./package.js";
|
|
17
18
|
import { listSkills, SKILLS_DIR } from "./skills.js";
|
|
18
19
|
export const AGENT_COMMANDS = ['init', 'skills'];
|
|
20
|
+
export const INIT_BACKUPS_KEPT = 5;
|
|
19
21
|
export const AGENT_HELP = {
|
|
20
22
|
title: 'Agents:',
|
|
21
23
|
entries: {
|
|
@@ -31,8 +33,9 @@ export const AGENT_HELP = {
|
|
|
31
33
|
private package.json when there is none, because the hooks and the MCP server
|
|
32
34
|
run ${CLI}.
|
|
33
35
|
Where Claude Code loads the ${TOOL} plugin (the project's or your settings,
|
|
34
|
-
or the session running init),
|
|
35
|
-
removes the copies of its skills
|
|
36
|
+
or the session running init), the plugin brings Claude Code's skills and MCP
|
|
37
|
+
server, and init removes the copies of its skills an earlier init wrote. The
|
|
38
|
+
hooks always go in each agent's project settings, plugin or not.
|
|
36
39
|
A second run changes nothing; a changed file is backed up first, and a file
|
|
37
40
|
init can't parse is refused, with nothing written. --check writes and
|
|
38
41
|
installs nothing, and exits 1 when a file would change. The folder defaults
|
|
@@ -46,7 +49,7 @@ export const AGENT_HELP = {
|
|
|
46
49
|
};
|
|
47
50
|
export const AGENT_USAGE = groupUsage(AGENT_HELP);
|
|
48
51
|
function throughPlugin(source) {
|
|
49
|
-
const done = `${describePluginSource(source)}, which brings the skills
|
|
52
|
+
const done = `${describePluginSource(source)}, which brings the skills and the MCP server, so init wrote neither for Claude Code: it mirrored only the project's own skills and kept Claude Code from loading the .mcp.json server a second time. It wrote the hooks into .claude/settings.json, where Claude Code runs them whether or not the plugin loads and gives the session-end hook its full timeout. Where the plugin's hooks run too, both guards give the same answer and the session's lanes are released once`;
|
|
50
53
|
if (source.kind === 'project')
|
|
51
54
|
return done;
|
|
52
55
|
const others = `Claude Code without the plugin gets none of them from this project's files; to wire it the same for everyone, enable the plugin in the project's .claude/settings.json`;
|
|
@@ -205,7 +208,11 @@ async function init(args, deps) {
|
|
|
205
208
|
return changes.length > 0 ? 1 : 0;
|
|
206
209
|
}
|
|
207
210
|
const stamp = new Date((deps.now ?? Date.now)()).toISOString().replace(/[:.]/g, '-');
|
|
208
|
-
const
|
|
211
|
+
const backupsDir = path.join(stateDir(deps.env), 'init-backups');
|
|
212
|
+
const project = backupProject(root);
|
|
213
|
+
const backup = `${stamp}-${project}`;
|
|
214
|
+
const { backups } = applyInit(plan, path.join(backupsDir, backup));
|
|
215
|
+
keepNewestBackups(backupsDir, project, INIT_BACKUPS_KEPT, backup);
|
|
209
216
|
const toolkit = await provideToolkit(root, deps.env, deps.install, screen ? step => screen.install(step) : step => step.run(deps.stderr));
|
|
210
217
|
const askForSetup = findConfigFile(root) === null;
|
|
211
218
|
if (screen) {
|
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import crypto from 'node:crypto';
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { CLI, TOOL } from "../name.js";
|
|
6
|
+
import { HOOK_PROBE_ENV, readHookMark } from "../plugin/hook-mark.js";
|
|
7
|
+
import { stateDir } from "../registry/paths.js";
|
|
8
|
+
import { claudePluginInstall } from "./claude-plugin.js";
|
|
9
|
+
import { isToolkitHook } from "./launcher.js";
|
|
10
|
+
import { listedRange, nearestPackage, toolVersion } from "./package.js";
|
|
11
|
+
import { agentEdits } from "./wiring.js";
|
|
12
|
+
export const PROBE_COMMAND = `echo ${TOOL} doctor checks that the simctl guard runs`;
|
|
13
|
+
const PROBE_TIMEOUT_MS = 10_000;
|
|
14
|
+
export const MARK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
|
|
15
|
+
function guardFile(agent) {
|
|
16
|
+
const edit = agentEdits(agent, false).find(e => e.part === 'guard hook' && e.kind === 'json' && e.cleanup !== true);
|
|
17
|
+
if (!edit)
|
|
18
|
+
throw new Error(`${agent} has no guard hook file`);
|
|
19
|
+
return edit.file;
|
|
20
|
+
}
|
|
21
|
+
function guardCommands(value) {
|
|
22
|
+
if (typeof value === 'string')
|
|
23
|
+
return isToolkitHook(value) && value.includes(' hook pre-tool-use') ? [value] : [];
|
|
24
|
+
if (Array.isArray(value))
|
|
25
|
+
return value.flatMap(guardCommands);
|
|
26
|
+
if (typeof value === 'object' && value !== null)
|
|
27
|
+
return Object.values(value).flatMap(guardCommands);
|
|
28
|
+
return [];
|
|
29
|
+
}
|
|
30
|
+
function settingsCommand(root, file) {
|
|
31
|
+
try {
|
|
32
|
+
return guardCommands(JSON.parse(fs.readFileSync(path.join(root, file), 'utf8')))[0] ?? null;
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function modified(file) {
|
|
39
|
+
try {
|
|
40
|
+
return fs.statSync(file).mtimeMs;
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
return Number.POSITIVE_INFINITY;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
function newestUnder(dir) {
|
|
47
|
+
let entries;
|
|
48
|
+
try {
|
|
49
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
return Number.POSITIVE_INFINITY;
|
|
53
|
+
}
|
|
54
|
+
return entries.reduce((newest, entry) => {
|
|
55
|
+
const at = path.join(dir, entry.name);
|
|
56
|
+
return Math.max(newest, entry.isDirectory() ? newestUnder(at) : modified(at));
|
|
57
|
+
}, modified(dir));
|
|
58
|
+
}
|
|
59
|
+
function real(file) {
|
|
60
|
+
try {
|
|
61
|
+
return fs.realpathSync(file);
|
|
62
|
+
}
|
|
63
|
+
catch {
|
|
64
|
+
return null;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
function manifestAt(file) {
|
|
68
|
+
try {
|
|
69
|
+
const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
|
|
70
|
+
if (manifest.name !== TOOL || typeof manifest.version !== 'string')
|
|
71
|
+
return null;
|
|
72
|
+
const at = fs.realpathSync(file);
|
|
73
|
+
const { bin } = manifest;
|
|
74
|
+
const named = typeof bin === 'string' ? bin : typeof bin === 'object' && bin !== null ? bin[TOOL] : null;
|
|
75
|
+
const entry = typeof named === 'string' ? path.resolve(path.dirname(at), named) : null;
|
|
76
|
+
return { manifest: at, version: manifest.version, entry: entry === null ? null : (real(entry) ?? entry) };
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
function toolkitManifest(bin) {
|
|
83
|
+
const beside = manifestAt(path.join(path.dirname(path.dirname(bin)), TOOL, 'package.json'));
|
|
84
|
+
if (beside)
|
|
85
|
+
return beside;
|
|
86
|
+
const target = real(bin);
|
|
87
|
+
if (target === null || target === bin)
|
|
88
|
+
return null;
|
|
89
|
+
for (let dir = path.dirname(target); path.dirname(dir) !== dir; dir = path.dirname(dir)) {
|
|
90
|
+
const found = manifestAt(path.join(dir, 'package.json'));
|
|
91
|
+
if (found)
|
|
92
|
+
return found;
|
|
93
|
+
}
|
|
94
|
+
return null;
|
|
95
|
+
}
|
|
96
|
+
function markHolds(mark, bin, hookFile, now) {
|
|
97
|
+
const toolkit = toolkitManifest(bin);
|
|
98
|
+
if (!toolkit?.entry || real(mark.toolkit) !== toolkit.entry)
|
|
99
|
+
return false;
|
|
100
|
+
return (mark.version === toolkit.version &&
|
|
101
|
+
mark.at >= modified(hookFile) &&
|
|
102
|
+
mark.node !== null &&
|
|
103
|
+
[bin, toolkit.manifest, toolkit.entry, mark.node].every(file => mark.at > modified(file)) &&
|
|
104
|
+
mark.at > newestUnder(path.dirname(toolkit.entry)) &&
|
|
105
|
+
now - mark.at <= MARK_MAX_AGE_MS);
|
|
106
|
+
}
|
|
107
|
+
function executable(file) {
|
|
108
|
+
try {
|
|
109
|
+
fs.accessSync(file, fs.constants.X_OK);
|
|
110
|
+
return true;
|
|
111
|
+
}
|
|
112
|
+
catch {
|
|
113
|
+
return false;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
function worktrees(root) {
|
|
117
|
+
const listed = spawnSync('git', ['-C', root, 'worktree', 'list', '--porcelain'], { encoding: 'utf8' });
|
|
118
|
+
if (listed.status !== 0)
|
|
119
|
+
return [];
|
|
120
|
+
return listed.stdout.split('\n').flatMap(line => (line.startsWith('worktree ') ? [line.slice('worktree '.length)] : []));
|
|
121
|
+
}
|
|
122
|
+
/** The toolkit the hooks `init` writes would run: the first above the project, else in another of its worktrees. */
|
|
123
|
+
function toolkitFor(root) {
|
|
124
|
+
for (let dir = root;; dir = path.dirname(dir)) {
|
|
125
|
+
if (executable(path.join(dir, CLI)))
|
|
126
|
+
return path.join(dir, CLI);
|
|
127
|
+
if (path.dirname(dir) === dir)
|
|
128
|
+
break;
|
|
129
|
+
}
|
|
130
|
+
return (worktrees(root)
|
|
131
|
+
.map(dir => path.join(dir, CLI))
|
|
132
|
+
.find(executable) ?? null);
|
|
133
|
+
}
|
|
134
|
+
function installFix(root, agent) {
|
|
135
|
+
const listed = nearestPackage(root, root);
|
|
136
|
+
const range = listed ? listedRange(listed) : null;
|
|
137
|
+
return range !== null
|
|
138
|
+
? `install the project's dependencies, so ${CLI} exists (package.json lists ${TOOL}${range ? ` ${range}` : ''}), then ${CLI} doctor`
|
|
139
|
+
: `run npx ${TOOL} init --agents ${agent}, which adds ${TOOL} as a dev dependency, then ${CLI} doctor`;
|
|
140
|
+
}
|
|
141
|
+
function ran(mark, how) {
|
|
142
|
+
return `${how} reached ${mark.toolkit} (${mark.version}) at ${new Date(mark.at).toISOString()}`;
|
|
143
|
+
}
|
|
144
|
+
function firstLine(text) {
|
|
145
|
+
return text.trim().split('\n', 1)[0] ?? '';
|
|
146
|
+
}
|
|
147
|
+
// spawnSync reports EPIPE when the child exits before taking all its input, and still sets the status or signal it waited for.
|
|
148
|
+
function wasWaitedFor(result) {
|
|
149
|
+
const code = result.error?.code;
|
|
150
|
+
return code === 'EPIPE' && (result.status !== null || result.signal !== null);
|
|
151
|
+
}
|
|
152
|
+
export function hookExit(result) {
|
|
153
|
+
if (result.error && !wasWaitedFor(result))
|
|
154
|
+
return `failed to run: ${result.error.message}`;
|
|
155
|
+
if (result.status === null)
|
|
156
|
+
return `was stopped by ${String(result.signal)}`;
|
|
157
|
+
return `exited ${String(result.status)}${result.stderr.trim() ? `: ${firstLine(result.stderr)}` : ''}`;
|
|
158
|
+
}
|
|
159
|
+
function probe(root, agent, route, bin, env) {
|
|
160
|
+
const name = `hooks ${agent}`;
|
|
161
|
+
const token = crypto.randomBytes(8).toString('hex');
|
|
162
|
+
const result = spawnSync('/bin/sh', ['-c', route.command], {
|
|
163
|
+
cwd: root,
|
|
164
|
+
env: { ...env, CLAUDE_PROJECT_DIR: root, CURSOR_PROJECT_DIR: root, ...route.env, [HOOK_PROBE_ENV]: token },
|
|
165
|
+
input: JSON.stringify({ cwd: root, tool_input: { command: PROBE_COMMAND } }),
|
|
166
|
+
encoding: 'utf8',
|
|
167
|
+
timeout: PROBE_TIMEOUT_MS,
|
|
168
|
+
});
|
|
169
|
+
const last = readHookMark(stateDir(env), agent, root);
|
|
170
|
+
const mark = last?.probe === token ? last : null;
|
|
171
|
+
const how = `doctor ran the guard hook in ${route.where} on a command it allows, and it`;
|
|
172
|
+
const exit = hookExit(result);
|
|
173
|
+
if (mark && result.status === 0)
|
|
174
|
+
return { name, ok: true, detail: ran(mark, how), fix: '' };
|
|
175
|
+
const toolkit = toolkitManifest(bin);
|
|
176
|
+
const fix = missingFix(route, toolkit, agent) ?? `${CLI} init --agents ${agent}, then ${CLI} doctor`;
|
|
177
|
+
if (mark)
|
|
178
|
+
return { name, ok: false, detail: `${ran(mark, how)}, then ${exit}`, fix };
|
|
179
|
+
if (result.status === 0 && toolkit && older(toolkit.version, toolVersion()))
|
|
180
|
+
return {
|
|
181
|
+
name,
|
|
182
|
+
ok: false,
|
|
183
|
+
detail: `${how} exited 0 without leaving a mark: the toolkit it runs, ${bin}, is ${TOOL} ${toolkit.version}, which leaves none (doctor is ${toolVersion()})`,
|
|
184
|
+
fix: `update the toolkit at ${bin} to ${TOOL} ${toolVersion()}, then ${CLI} doctor`,
|
|
185
|
+
};
|
|
186
|
+
if (result.status === 0)
|
|
187
|
+
return {
|
|
188
|
+
name,
|
|
189
|
+
ok: false,
|
|
190
|
+
detail: `${how} exited 0 without reaching the toolkit at ${bin}: its command found no toolkit to run, or predates the one init writes`,
|
|
191
|
+
fix,
|
|
192
|
+
};
|
|
193
|
+
return { name, ok: false, detail: `${how} never reached the toolkit: it ${exit}`, fix };
|
|
194
|
+
}
|
|
195
|
+
function older(version, than) {
|
|
196
|
+
const parts = (v) => v.split(/[-+]/, 1)[0]?.split('.').map(Number) ?? [];
|
|
197
|
+
const [a, b] = [parts(version), parts(than)];
|
|
198
|
+
for (let i = 0; i < Math.max(a.length, b.length); i++) {
|
|
199
|
+
const [x, y] = [a[i] ?? 0, b[i] ?? 0];
|
|
200
|
+
if (Number.isNaN(x) || Number.isNaN(y))
|
|
201
|
+
return false;
|
|
202
|
+
if (x !== y)
|
|
203
|
+
return x < y;
|
|
204
|
+
}
|
|
205
|
+
return false;
|
|
206
|
+
}
|
|
207
|
+
function missingFix(route, toolkit, agent) {
|
|
208
|
+
if (!fs.existsSync(route.file))
|
|
209
|
+
return route.plugin
|
|
210
|
+
? `${route.file} is missing, so the plugin's hooks can't run: reinstall the ${TOOL} plugin in Claude Code, or run ${CLI} init --agents ${agent} to write the hooks into ${guardFile(agent)}`
|
|
211
|
+
: `${route.file} is missing: ${CLI} init --agents ${agent} writes it`;
|
|
212
|
+
if (toolkit?.entry && !fs.existsSync(toolkit.entry))
|
|
213
|
+
return `${toolkit.entry}, the file ${toolkit.manifest} runs, is missing: install the project's dependencies again, or build the linked ${TOOL} checkout, then ${CLI} doctor`;
|
|
214
|
+
return null;
|
|
215
|
+
}
|
|
216
|
+
function hookCheck(root, agent, env, now) {
|
|
217
|
+
const name = `hooks ${agent}`;
|
|
218
|
+
const file = guardFile(agent);
|
|
219
|
+
const command = settingsCommand(root, file);
|
|
220
|
+
let route = command ? { where: file, plugin: false, file: path.join(root, file), command, env: {} } : null;
|
|
221
|
+
if (route === null && agent === 'claude') {
|
|
222
|
+
const install = claudePluginInstall(root, env);
|
|
223
|
+
if (install?.kind === 'loaded') {
|
|
224
|
+
const script = path.join(install.dir, 'scripts', 'hook.sh');
|
|
225
|
+
route = {
|
|
226
|
+
where: `the plugin in ${install.dir}`,
|
|
227
|
+
plugin: true,
|
|
228
|
+
file: script,
|
|
229
|
+
command: `"${script}" pre-tool-use`,
|
|
230
|
+
env: { CLAUDE_PLUGIN_ROOT: install.dir },
|
|
231
|
+
};
|
|
232
|
+
}
|
|
233
|
+
else if (install?.kind === 'not-installed')
|
|
234
|
+
return {
|
|
235
|
+
name,
|
|
236
|
+
ok: false,
|
|
237
|
+
detail: `no ${TOOL} hook runs in Claude Code here: ${file} has none, and the plugin it leaves them to (${install.keys.join(', ')}) is enabled but not installed on this Mac`,
|
|
238
|
+
fix: `${CLI} init --agents claude writes the hooks into ${file}`,
|
|
239
|
+
};
|
|
240
|
+
else if (install?.kind === 'unknown')
|
|
241
|
+
return {
|
|
242
|
+
name,
|
|
243
|
+
ok: true,
|
|
244
|
+
warning: true,
|
|
245
|
+
detail: `${file} has no ${TOOL} hooks, and doctor can't read which plugins Claude Code installed, so it can't tell whether the plugin's hooks run`,
|
|
246
|
+
fix: `${CLI} init --agents claude writes the hooks into ${file}`,
|
|
247
|
+
};
|
|
248
|
+
}
|
|
249
|
+
if (route === null)
|
|
250
|
+
return {
|
|
251
|
+
name,
|
|
252
|
+
ok: false,
|
|
253
|
+
detail: `${file} has no ${TOOL} guard hook, so no ${TOOL} hook runs in ${agent}`,
|
|
254
|
+
fix: `${CLI} init --agents ${agent}`,
|
|
255
|
+
};
|
|
256
|
+
const bin = toolkitFor(root);
|
|
257
|
+
if (bin === null)
|
|
258
|
+
return {
|
|
259
|
+
name,
|
|
260
|
+
ok: false,
|
|
261
|
+
detail: `the hooks in ${route.where} find no ${CLI} in ${root}, the folders above it or this repository's other worktrees, so they never run ${TOOL}`,
|
|
262
|
+
fix: installFix(root, agent),
|
|
263
|
+
};
|
|
264
|
+
const mark = readHookMark(stateDir(env), agent, root);
|
|
265
|
+
if (mark && markHolds(mark, bin, route.file, now))
|
|
266
|
+
return { name, ok: true, detail: ran(mark, `the ${mark.event} hook in ${route.where}`), fix: '' };
|
|
267
|
+
return probe(root, agent, route, bin, env);
|
|
268
|
+
}
|
|
269
|
+
/**
|
|
270
|
+
* One line per agent: whether its hooks run. The mark the hook left for this project folder answers while it names the
|
|
271
|
+
* file this project's toolkit runs, is newer than the hook, the toolkit's manifest, everything in that file's folder and
|
|
272
|
+
* the node the hook ran on, names the toolkit's version and is under a day old; otherwise doctor runs the guard hook on
|
|
273
|
+
* a command it allows.
|
|
274
|
+
*/
|
|
275
|
+
export function agentHookChecks(root, agents, env, now = Date.now()) {
|
|
276
|
+
return agents.map(agent => {
|
|
277
|
+
try {
|
|
278
|
+
return hookCheck(root, agent, env, now);
|
|
279
|
+
}
|
|
280
|
+
catch (error) {
|
|
281
|
+
return {
|
|
282
|
+
name: `hooks ${agent}`,
|
|
283
|
+
ok: true,
|
|
284
|
+
warning: true,
|
|
285
|
+
detail: `could not check the hooks: ${error.message}`,
|
|
286
|
+
fix: `${CLI} init --check`,
|
|
287
|
+
};
|
|
288
|
+
}
|
|
289
|
+
});
|
|
290
|
+
}
|
package/dist/agents/launcher.js
CHANGED
|
@@ -11,17 +11,45 @@ const START = {
|
|
|
11
11
|
gemini: '$PWD',
|
|
12
12
|
antigravity: '$PWD',
|
|
13
13
|
};
|
|
14
|
+
export const GUARDED_WORDS = [
|
|
15
|
+
'simctl',
|
|
16
|
+
'adb',
|
|
17
|
+
'emulator',
|
|
18
|
+
'avdmanager',
|
|
19
|
+
'playwright-cli',
|
|
20
|
+
'@playwright/cli',
|
|
21
|
+
'agent-browser',
|
|
22
|
+
];
|
|
23
|
+
/**
|
|
24
|
+
* The hook's input arrives as JSON, which writes a backslash as `\\` and a newline as `\n`, and Copilot's `toolArgs` is
|
|
25
|
+
* JSON inside that JSON, which doubles each of those backslashes again. Bash and zsh run `a{d,}b` as `adb ab` and
|
|
26
|
+
* `a{d..d}b` as `adb`.
|
|
27
|
+
*/
|
|
28
|
+
export const UNSPLIT_SED = String.raw `sed -e h -e 's/\\\\//g' -e 's/\\n//g' -e x -e 's/\\\\\\\\//g' -e 's/\\\\n//g' -e G -e 's/\\//g' -e "s/[\$'\"]//g" -e p -e :x -e h -e 's/{\([-+0-9A-Za-z]*\)\.\.[-+0-9A-Za-z.]*}/\1/g' -e 's/{\([^{},]*\)\(,[^{},]*\)\{0,8\}}/\1/g' -e p -e g -e ty -e :y -e 's/{[^{},]*,\([^{},]*\(,[^{},]*\)\{0,7\}\)}/{\1}/g' -e tx -e d`;
|
|
29
|
+
const UNSPLIT_INPUT = `$(printf %s "$i" | ${UNSPLIT_SED})`;
|
|
30
|
+
function walkUp(start) {
|
|
31
|
+
return `d="${start}"; while [ ! -x "$d/${CLI}" ] && [ "$d" != / ]; do d=$(dirname "$d"); done`;
|
|
32
|
+
}
|
|
14
33
|
function launch(start, args, missing) {
|
|
15
|
-
return
|
|
34
|
+
return `${walkUp(start)}; if [ -x "$d/${CLI}" ]; then exec "$d/${CLI}" ${args}; fi; ${missing}`;
|
|
35
|
+
}
|
|
36
|
+
function worktreeFallback() {
|
|
37
|
+
return `if [ ! -x "$d/${CLI}" ]; then d=$(git -C "$s" worktree list --porcelain 2>/dev/null | while IFS= read -r l; do w=\${l#worktree }; if [ "$w" != "$l" ] && [ -x "$w/${CLI}" ]; then printf %s "$w"; break; fi; done); fi`;
|
|
16
38
|
}
|
|
17
39
|
/**
|
|
18
|
-
* The command an agent's hook runs: the project's own toolkit, found from the folder the hook runs in upwards
|
|
19
|
-
*
|
|
20
|
-
*
|
|
40
|
+
* The command an agent's hook runs: the project's own toolkit, found from the folder the hook runs in upwards, else in
|
|
41
|
+
* the first worktree of the same repository that has one. The guard starts the toolkit only for a command that names
|
|
42
|
+
* a device or browser tool. Without a toolkit it allows and exits 0, because Copilot denies the tool call on any other
|
|
43
|
+
* exit and Gemini on exit 2 or more, and Cursor needs a JSON answer.
|
|
21
44
|
*/
|
|
22
45
|
export function hookCommand(agent, event) {
|
|
23
|
-
const allow = agent === 'cursor' && event === 'pre-tool-use' ? `echo '{"permission":"allow"}'` : 'exit 0';
|
|
24
|
-
|
|
46
|
+
const allow = agent === 'cursor' && event === 'pre-tool-use' ? `echo '{"permission":"allow"}'; exit 0` : 'exit 0';
|
|
47
|
+
const find = `s="${START[agent]}"; ${walkUp('$s')}; ${worktreeFallback()}`;
|
|
48
|
+
const args = `hook ${event} --agent ${agent}`;
|
|
49
|
+
if (event === 'session-end')
|
|
50
|
+
return `${find}; if [ -x "$d/${CLI}" ]; then exec "$d/${CLI}" ${args}; fi; ${allow}`;
|
|
51
|
+
const words = GUARDED_WORDS.map(word => `*${word}*`).join('|');
|
|
52
|
+
return `i=$(cat); case ${UNSPLIT_INPUT} in ${words}) ;; *) ${allow};; esac; ${find}; if [ -x "$d/${CLI}" ]; then printf '%s' "$i" | "$d/${CLI}" ${args}; exit; fi; ${allow}`;
|
|
25
53
|
}
|
|
26
54
|
export function mcpLaunch() {
|
|
27
55
|
const missing = `echo "${TOOL}: no ${CLI} in $PWD or the folders above it; add the toolkit to this project" >&2; exit 1`;
|
|
@@ -2,10 +2,10 @@ import fs from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { CLI, TOOL } from "../name.js";
|
|
4
4
|
import { AGENTS } from "../registry/owner.js";
|
|
5
|
-
import { CLAUDE_SETTINGS, describePluginSource, jsonObjectAt } from "./claude-plugin.js";
|
|
5
|
+
import { CLAUDE_SETTINGS, claudePluginInstall, describePluginSource, jsonObjectAt } from "./claude-plugin.js";
|
|
6
6
|
import { planInit } from "./init.js";
|
|
7
7
|
import { listSkills, SKILLS_DIR } from "./skills.js";
|
|
8
|
-
import { agentEdits, disablesOurServer,
|
|
8
|
+
import { agentEdits, disablesOurServer, pluginEnabled } from "./wiring.js";
|
|
9
9
|
const SHARED = new Set(['.mcp.json']);
|
|
10
10
|
function holds(root, edit) {
|
|
11
11
|
if (edit.part === 'skills' || SHARED.has(edit.file))
|
|
@@ -57,8 +57,6 @@ function claudeCopies(root, claude) {
|
|
|
57
57
|
const servers = jsonObjectAt(path.join(root, '.mcp.json'))?.mcpServers;
|
|
58
58
|
if (typeof servers === 'object' && servers !== null && TOOL in servers && !(settings && disablesOurServer(settings)))
|
|
59
59
|
copies.push('MCP server in .mcp.json');
|
|
60
|
-
if (settings !== null && hasClaudeHooks(settings))
|
|
61
|
-
copies.push(`hooks in ${CLAUDE_SETTINGS}`);
|
|
62
60
|
const links = claude.filter(f => f.status === 'remove').length;
|
|
63
61
|
if (links > 0)
|
|
64
62
|
copies.push(`${String(links)} toolkit skill${links === 1 ? '' : 's'} in .claude/skills`);
|
|
@@ -90,8 +88,16 @@ export function agentWiringChecks(root, env, skills = listSkills(SKILLS_DIR)) {
|
|
|
90
88
|
const fine = plugin ? `through the plugin: ${describePluginSource(plugin)}` : 'MCP server and hooks in place';
|
|
91
89
|
const line = check(`wiring ${agent}`, mine, fine, `${CLI} init --agents ${agent}`);
|
|
92
90
|
const copies = plugin ? claudeCopies(root, mine) : [];
|
|
91
|
+
const install = plugin ? claudePluginInstall(root, env) : null;
|
|
93
92
|
if (plugin && copies.length > 0)
|
|
94
93
|
checks.push({ ...line, detail: bothWired(plugin, copies) });
|
|
94
|
+
else if (plugin && install?.kind === 'not-installed')
|
|
95
|
+
checks.push({
|
|
96
|
+
...line,
|
|
97
|
+
warning: true,
|
|
98
|
+
detail: `${describePluginSource(plugin)}, but Claude Code hasn't installed it on this Mac (${install.keys.join(', ')}), so its MCP server and skills don't load${line.warning ? `; and ${line.detail}` : ''}`,
|
|
99
|
+
fix: `in Claude Code, /plugin install ${install.keys[0] ?? TOOL} (add its marketplace with /plugin marketplace add first if /plugin doesn't list it)${line.warning ? `, then ${line.fix}` : ''}`,
|
|
100
|
+
});
|
|
95
101
|
else if (agent === 'claude' && !plugin && line.warning && leftToAbsentPlugin(root))
|
|
96
102
|
checks.push({
|
|
97
103
|
...line,
|