agentlane 0.0.0 → 0.4.0-rc.2
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 +118 -0
- package/LICENSE +27 -0
- package/README.md +167 -2
- package/dist/agents/claude-plugin.js +79 -0
- package/dist/agents/cli.js +258 -0
- package/dist/agents/detect.js +88 -0
- package/dist/agents/init.js +251 -0
- package/dist/agents/launcher.js +32 -0
- package/dist/agents/package.js +119 -0
- package/dist/agents/skills.js +59 -0
- package/dist/agents/toml.js +325 -0
- package/dist/agents/wiring-check.js +117 -0
- package/dist/agents/wiring.js +374 -0
- package/dist/bench/host.js +104 -0
- package/dist/bench/live.js +511 -0
- package/dist/bench/mcp-client.js +91 -0
- package/dist/bench/model.js +15 -0
- package/dist/bench/report.js +162 -0
- package/dist/bench/run.js +121 -0
- package/dist/bench/schedule.js +140 -0
- package/dist/bench/stats.js +59 -0
- package/dist/bench-cli.js +167 -0
- package/dist/browser/aria.js +184 -0
- package/dist/browser/control.js +203 -0
- package/dist/browser/env.js +118 -0
- package/dist/browser/evidence.js +44 -0
- package/dist/browser/install.js +361 -0
- package/dist/browser/kinds.js +10 -0
- package/dist/browser/lane-browser.js +224 -0
- package/dist/browser/libraries.js +56 -0
- package/dist/browser/paths.js +29 -0
- package/dist/browser/release.js +121 -0
- package/dist/browser/screen.js +19 -0
- package/dist/browser/signin.js +154 -0
- package/dist/browser/stop.js +163 -0
- package/dist/browser/tools.js +25 -0
- package/dist/cache/build.js +154 -0
- package/dist/cache/config.js +186 -0
- package/dist/cache/index.js +4 -0
- package/dist/cache/key.js +196 -0
- package/dist/cache/store.js +303 -0
- package/dist/cli.js +178 -0
- package/dist/clock.js +4 -0
- package/dist/devices/adb.js +160 -0
- package/dist/devices/android.js +214 -0
- package/dist/devices/backend.js +7 -0
- package/dist/devices/bundler.js +46 -0
- package/dist/devices/common.js +51 -0
- package/dist/devices/controls.js +65 -0
- package/dist/devices/dial.js +56 -0
- package/dist/devices/emulator.js +396 -0
- package/dist/devices/hygiene.js +202 -0
- package/dist/devices/index.js +5 -0
- package/dist/devices/launch.js +76 -0
- package/dist/devices/simctl.js +119 -0
- package/dist/devices/tools.js +1 -0
- package/dist/devices/variant.js +99 -0
- package/dist/devices/xcrun.js +265 -0
- package/dist/driver/absence.js +54 -0
- package/dist/driver/caller.js +51 -0
- package/dist/driver/client.js +312 -0
- package/dist/driver/diff.js +180 -0
- package/dist/driver/elements.js +70 -0
- package/dist/driver/engine-main.js +13 -0
- package/dist/driver/engine.js +499 -0
- package/dist/driver/errors.js +11 -0
- package/dist/driver/exec.js +66 -0
- package/dist/driver/failure.js +156 -0
- package/dist/driver/flow.js +94 -0
- package/dist/driver/idle.js +100 -0
- package/dist/driver/images.js +68 -0
- package/dist/driver/install.js +272 -0
- package/dist/driver/lock.js +101 -0
- package/dist/driver/look.js +223 -0
- package/dist/driver/maestro-child.js +194 -0
- package/dist/driver/maestro-runs.js +46 -0
- package/dist/driver/paths.js +105 -0
- package/dist/driver/pixels.js +144 -0
- package/dist/driver/plan.js +108 -0
- package/dist/driver/release.js +7 -0
- package/dist/driver/runner.js +42 -0
- package/dist/driver/selector.js +91 -0
- package/dist/driver/session.js +474 -0
- package/dist/driver/suggest.js +86 -0
- package/dist/driver/supervisor.js +251 -0
- package/dist/driver/tree.js +426 -0
- package/dist/driver-cli.js +865 -0
- package/dist/evidence/device.js +177 -0
- package/dist/evidence/evidence.js +304 -0
- package/dist/evidence/files.js +92 -0
- package/dist/hooks/env.js +81 -0
- package/dist/hooks/run.js +101 -0
- package/dist/mcp/server.js +69 -0
- package/dist/mcp/tools.js +246 -0
- package/dist/name.js +22 -0
- package/dist/plugin/aims.js +465 -0
- package/dist/plugin/conventions.js +73 -0
- package/dist/plugin/guard.js +163 -0
- package/dist/plugin/hook-cli.js +216 -0
- package/dist/plugin/session-name.js +28 -0
- package/dist/plugin/shell.js +254 -0
- package/dist/processes.js +77 -0
- package/dist/project/config.js +316 -0
- package/dist/project/schema.js +335 -0
- package/dist/project/validate.js +224 -0
- package/dist/registry/config.js +142 -0
- package/dist/registry/format.js +22 -0
- package/dist/registry/owner.js +265 -0
- package/dist/registry/paths.js +50 -0
- package/dist/registry/ports.js +26 -0
- package/dist/registry/prune.js +160 -0
- package/dist/registry/refusal.js +53 -0
- package/dist/registry/registry.js +1027 -0
- package/dist/registry/resources.js +117 -0
- package/dist/registry/rows.js +115 -0
- package/dist/registry/status.js +85 -0
- package/dist/registry/store.js +274 -0
- package/dist/registry/types.js +1 -0
- package/dist/registry-cli.js +544 -0
- package/dist/services/services.js +268 -0
- package/dist/services/system.js +189 -0
- package/dist/up/deps.js +1 -0
- package/dist/up/doctor.js +424 -0
- package/dist/up/exec.js +133 -0
- package/dist/up/lane-files.js +75 -0
- package/dist/up/lane-services.js +38 -0
- package/dist/up/maestro-env.js +172 -0
- package/dist/up/preflight.js +232 -0
- package/dist/up/release.js +148 -0
- package/dist/up/resources.js +178 -0
- package/dist/up/restart.js +87 -0
- package/dist/up/setup.js +28 -0
- package/dist/up/up.js +610 -0
- package/dist/up-cli.js +258 -0
- package/dist/usage.js +16 -0
- package/package.json +58 -3
- package/schema/agentlane.schema.json +675 -0
- package/skills/create-verification-skill/LICENSE +21 -0
- package/skills/create-verification-skill/SKILL.md +88 -0
- package/skills/dev-loop/LICENSE +21 -0
- package/skills/dev-loop/SKILL.md +61 -0
- package/skills/device/SKILL.md +8 -0
- package/skills/drive/SKILL.md +64 -0
- package/skills/maintain-verification-skill/LICENSE +21 -0
- package/skills/maintain-verification-skill/SKILL.md +42 -0
- package/skills/setup/SKILL.md +80 -0
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
import { spawnSync } from 'node:child_process';
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { parseArgs } from 'node:util';
|
|
5
|
+
import { CLI, CONFIG_FILE, TOOL } from "../name.js";
|
|
6
|
+
import { findConfigFile } from "../project/config.js";
|
|
7
|
+
import { AGENTS } from "../registry/owner.js";
|
|
8
|
+
import { stateDir } from "../registry/paths.js";
|
|
9
|
+
import { UsageError } from "../registry/refusal.js";
|
|
10
|
+
import { resolveFolder } from "../registry-cli.js";
|
|
11
|
+
import { commandUsage, groupUsage } from "../usage.js";
|
|
12
|
+
import { describePluginSource } from "./claude-plugin.js";
|
|
13
|
+
import { chooseAgents, describeDetections, detectAgents } from "./detect.js";
|
|
14
|
+
import { applyInit, planInit } from "./init.js";
|
|
15
|
+
import { addCommand, installedVersion, listedRange, nearestPackage, PACKAGE_SPEC_ENV, packageManagerOf, shellLine, toolVersion, } from "./package.js";
|
|
16
|
+
import { listSkills, SKILLS_DIR } from "./skills.js";
|
|
17
|
+
export const AGENT_COMMANDS = ['init', 'skills'];
|
|
18
|
+
export const AGENT_HELP = {
|
|
19
|
+
title: 'Agents:',
|
|
20
|
+
entries: {
|
|
21
|
+
init: ` init [--agents <list> | --all] [--dir <folder>] [--check]
|
|
22
|
+
Write each agent's own project files from one source: the toolkit's skills in
|
|
23
|
+
.agents/skills (mirrored into .claude/skills for Claude Code), the MCP server,
|
|
24
|
+
and the device guard and session-end hooks. Agents: ${AGENTS.join(', ')}.
|
|
25
|
+
Without --agents or --all, init wires the agents whose files the project has
|
|
26
|
+
(CLAUDE.md, .codex/, .cursor/, ...) or whose session runs it, and in a terminal
|
|
27
|
+
asks you to confirm or change them.
|
|
28
|
+
Where the project's package.json doesn't list ${TOOL}, init adds it as a dev
|
|
29
|
+
dependency at its own version with the project's package manager, creating a
|
|
30
|
+
private package.json when there is none, because the hooks and the MCP server
|
|
31
|
+
run ${CLI}.
|
|
32
|
+
Where Claude Code loads the ${TOOL} plugin (the project's or your settings,
|
|
33
|
+
or the session running init), Claude Code is left to the plugin, and init
|
|
34
|
+
removes the copies of its skills and hooks an earlier init wrote.
|
|
35
|
+
A second run changes nothing; a changed file is backed up first, and a file
|
|
36
|
+
init can't parse is refused, with nothing written. --check writes and
|
|
37
|
+
installs nothing, and exits 1 when a file would change. The folder defaults
|
|
38
|
+
to the one with ${TOOL}.json, else the worktree.
|
|
39
|
+
`,
|
|
40
|
+
skills: ` skills list The toolkit's skills, each with what it is for.
|
|
41
|
+
skills get <name> Print a skill's content for this installed version; the skill files in a
|
|
42
|
+
project only point here.
|
|
43
|
+
`,
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
export const AGENT_USAGE = groupUsage(AGENT_HELP);
|
|
47
|
+
function throughPlugin(source) {
|
|
48
|
+
const done = `${describePluginSource(source)}, which brings the skills, the MCP server and the hooks, so init wrote none of them for Claude Code: it mirrored only the project's own skills and kept Claude Code from loading the .mcp.json server a second time`;
|
|
49
|
+
if (source.kind === 'project')
|
|
50
|
+
return done;
|
|
51
|
+
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`;
|
|
52
|
+
return source.kind === 'session'
|
|
53
|
+
? `${done}. ${others}, or run ${CLI} init again outside a session that loads the plugin`
|
|
54
|
+
: `${done}. ${others}`;
|
|
55
|
+
}
|
|
56
|
+
const NEXT = {
|
|
57
|
+
claude: plugin => (plugin ? throughPlugin(plugin) : 'Claude Code asks once to approve the MCP server in .mcp.json'),
|
|
58
|
+
codex: () => 'Codex reads .codex/ only in a trusted project, and runs each hook only after you review and trust it with /hooks, again whenever it changes',
|
|
59
|
+
cursor: () => 'Cursor runs .cursor/hooks.json in the app; its CLI runs hooks unreliably. Release at session end waits for the Cursor process to exit',
|
|
60
|
+
copilot: () => "Copilot CLI loads the MCP server and the hooks once you trust the folder; it also runs Claude Code's hooks from .claude/settings.json",
|
|
61
|
+
gemini: () => 'Gemini CLI warns when the project’s hooks change, and asks before it activates a skill',
|
|
62
|
+
antigravity: () => 'Antigravity has no session-end hook, so its lanes are freed once Antigravity exits and the next claim reaps them',
|
|
63
|
+
};
|
|
64
|
+
function parseAgents(raw, all) {
|
|
65
|
+
if (all)
|
|
66
|
+
throw new UsageError('--agents and --all both name the agents', 'pass one of them');
|
|
67
|
+
const names = raw
|
|
68
|
+
.split(',')
|
|
69
|
+
.map(name => name.trim())
|
|
70
|
+
.filter(name => name !== '');
|
|
71
|
+
const unknown = names.filter(name => !AGENTS.includes(name));
|
|
72
|
+
if (unknown.length > 0 || names.length === 0)
|
|
73
|
+
throw new UsageError(`'${unknown.join(',') || raw}' is not an agent`, `pass --agents with any of ${AGENTS.join(',')}`);
|
|
74
|
+
return AGENTS.filter(agent => names.includes(agent));
|
|
75
|
+
}
|
|
76
|
+
async function agentsToWire(values, root, deps) {
|
|
77
|
+
if (values.agents !== undefined)
|
|
78
|
+
return parseAgents(values.agents, values.all);
|
|
79
|
+
if (values.all)
|
|
80
|
+
return [...AGENTS];
|
|
81
|
+
const detected = detectAgents(root, deps.env);
|
|
82
|
+
const choose = `pass --agents with the ones you use (${AGENTS.join(',')}), or --all`;
|
|
83
|
+
if (deps.terminal) {
|
|
84
|
+
const chosen = await chooseAgents(detected, deps.terminal);
|
|
85
|
+
if (chosen === null)
|
|
86
|
+
throw new UsageError('no agents chosen, so init wrote nothing', choose);
|
|
87
|
+
return chosen;
|
|
88
|
+
}
|
|
89
|
+
if (detected.length === 0)
|
|
90
|
+
throw new UsageError(`found no agent's files in ${root} and no agent's variable in this shell, so init doesn't know which agents to wire`, choose);
|
|
91
|
+
deps.stdout(`${TOOL} init: found these agents (pass --agents to pick others):\n${describeDetections(detected)}`);
|
|
92
|
+
return detected.map(d => d.agent);
|
|
93
|
+
}
|
|
94
|
+
function ignoredByGit(dir, name) {
|
|
95
|
+
return spawnSync('git', ['-C', dir, 'check-ignore', '-q', name]).status === 0;
|
|
96
|
+
}
|
|
97
|
+
function provideToolkit(root, env, install) {
|
|
98
|
+
const top = resolveFolder(root).worktree;
|
|
99
|
+
const own = toolVersion();
|
|
100
|
+
const override = env[PACKAGE_SPEC_ENV];
|
|
101
|
+
const spec = override !== undefined && override !== '' ? override : `${TOOL}@${own}`;
|
|
102
|
+
const notes = [];
|
|
103
|
+
const found = nearestPackage(root, top);
|
|
104
|
+
const dir = found ?? root;
|
|
105
|
+
const manifest = path.relative(root, path.join(dir, 'package.json'));
|
|
106
|
+
const choice = packageManagerOf(dir, top, env);
|
|
107
|
+
const command = addCommand(choice, dir, spec);
|
|
108
|
+
if (found !== null) {
|
|
109
|
+
const range = listedRange(dir);
|
|
110
|
+
if (range !== null) {
|
|
111
|
+
const installed = installedVersion(dir);
|
|
112
|
+
if (installed === null)
|
|
113
|
+
notes.push(`${manifest} lists ${TOOL} ${range}, but it isn't installed: run ${choice.manager} install there, so ${CLI} exists.`);
|
|
114
|
+
else if (installed !== own)
|
|
115
|
+
notes.push(`${manifest} lists ${TOOL} ${range}, with ${installed} installed; init left it as it is. This init is ${own}: ${shellLine(addCommand(choice, dir, `${TOOL}@${own}`))} moves the project to it.`);
|
|
116
|
+
return { notes, failed: null };
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
fs.writeFileSync(path.join(dir, 'package.json'), '{\n "private": true\n}\n');
|
|
121
|
+
notes.push(`Created ${manifest}, private, to hold ${TOOL} as a dev dependency.`);
|
|
122
|
+
if (!ignoredByGit(dir, 'node_modules'))
|
|
123
|
+
notes.push('node_modules/ is not in .gitignore: add it before you commit.');
|
|
124
|
+
}
|
|
125
|
+
const result = install(command, dir);
|
|
126
|
+
if (!result.ok)
|
|
127
|
+
return { notes, failed: { command: shellLine(command), dir, problem: result.problem } };
|
|
128
|
+
notes.push(`Added ${spec} to ${manifest} as a dev dependency with ${choice.manager}, because ${choice.source}: ${shellLine(command)}`);
|
|
129
|
+
return { notes, failed: null };
|
|
130
|
+
}
|
|
131
|
+
function projectRoot(cwd, dir) {
|
|
132
|
+
if (dir !== undefined) {
|
|
133
|
+
const folder = path.resolve(cwd, dir);
|
|
134
|
+
if (!fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory())
|
|
135
|
+
throw new UsageError(`${folder} is not a folder`, 'pass --dir with the project folder');
|
|
136
|
+
return fs.realpathSync(folder);
|
|
137
|
+
}
|
|
138
|
+
const config = findConfigFile(cwd);
|
|
139
|
+
return config ? path.dirname(config) : resolveFolder(cwd).worktree;
|
|
140
|
+
}
|
|
141
|
+
function role(file) {
|
|
142
|
+
const parts = new Map();
|
|
143
|
+
for (const edit of file.edits) {
|
|
144
|
+
const who = edit.agent ?? 'every agent';
|
|
145
|
+
parts.set(edit.part, (parts.get(edit.part) ?? new Set()).add(who));
|
|
146
|
+
}
|
|
147
|
+
return [...parts].map(([part, who]) => `${part} (${[...who].join(', ')})`).join('; ');
|
|
148
|
+
}
|
|
149
|
+
const VERB = {
|
|
150
|
+
create: ['created', 'would create'],
|
|
151
|
+
update: ['updated', 'would update'],
|
|
152
|
+
remove: ['removed', 'would remove'],
|
|
153
|
+
unchanged: ['unchanged', 'unchanged'],
|
|
154
|
+
refused: ['REFUSED', 'REFUSED'],
|
|
155
|
+
};
|
|
156
|
+
function report(plan, check) {
|
|
157
|
+
const width = Math.max(...plan.files.map(f => f.file.length));
|
|
158
|
+
const lines = [`${TOOL} init in ${plan.root} for ${plan.agents.join(', ')}:`];
|
|
159
|
+
for (const file of plan.files)
|
|
160
|
+
lines.push(` ${VERB[file.status][check ? 1 : 0].padEnd(12)} ${file.file.padEnd(width)} ${role(file)}`);
|
|
161
|
+
return `${lines.join('\n')}\n`;
|
|
162
|
+
}
|
|
163
|
+
async function init(args, deps) {
|
|
164
|
+
const { values } = parseArgs({
|
|
165
|
+
args,
|
|
166
|
+
strict: true,
|
|
167
|
+
options: {
|
|
168
|
+
agents: { type: 'string' },
|
|
169
|
+
all: { type: 'boolean', default: false },
|
|
170
|
+
dir: { type: 'string' },
|
|
171
|
+
check: { type: 'boolean', default: false },
|
|
172
|
+
},
|
|
173
|
+
});
|
|
174
|
+
const root = projectRoot(deps.cwd, values.dir);
|
|
175
|
+
const agents = await agentsToWire(values, root, deps);
|
|
176
|
+
const plan = planInit(root, agents, listSkills(deps.skillsDir ?? SKILLS_DIR), deps.env);
|
|
177
|
+
deps.stdout(report(plan, values.check));
|
|
178
|
+
const refusals = plan.files.filter(f => f.status === 'refused');
|
|
179
|
+
if (refusals.length > 0) {
|
|
180
|
+
for (const file of refusals)
|
|
181
|
+
deps.stderr(`${TOOL} init: ${file.reason ?? file.file}\n`);
|
|
182
|
+
deps.stderr(`${TOOL} init: wrote nothing; fix ${refusals.length === 1 ? 'that file' : 'those files'} and run ${CLI} init again\n`);
|
|
183
|
+
return 1;
|
|
184
|
+
}
|
|
185
|
+
const changes = plan.files.filter(f => f.status === 'create' || f.status === 'update' || f.status === 'remove');
|
|
186
|
+
if (values.check) {
|
|
187
|
+
if (changes.length > 0)
|
|
188
|
+
deps.stderr(`${TOOL} init --check: ${String(changes.length)} file(s) would change\n`);
|
|
189
|
+
return changes.length > 0 ? 1 : 0;
|
|
190
|
+
}
|
|
191
|
+
const stamp = new Date((deps.now ?? Date.now)()).toISOString().replace(/[:.]/g, '-');
|
|
192
|
+
const { backups } = applyInit(plan, path.join(stateDir(deps.env), 'init-backups', `${stamp}-${path.basename(root)}`));
|
|
193
|
+
const toolkit = provideToolkit(root, deps.env, deps.install);
|
|
194
|
+
const out = [...toolkit.notes];
|
|
195
|
+
if (backups)
|
|
196
|
+
out.push(`Backed up the files it changed in ${backups}.`);
|
|
197
|
+
if (changes.length > 0)
|
|
198
|
+
out.push('Commit the files above: each agent reads them from the repository, and they hold no path or secret of this machine.');
|
|
199
|
+
else
|
|
200
|
+
out.push('Nothing to change.');
|
|
201
|
+
out.push('Next:');
|
|
202
|
+
for (const agent of agents)
|
|
203
|
+
out.push(` ${agent}: ${NEXT[agent](plan.claudePlugin)}.`);
|
|
204
|
+
if (findConfigFile(root) === null)
|
|
205
|
+
out.push(`Then ask your agent: "Set this project up with ${TOOL}." Its setup skill writes ${CONFIG_FILE}.`);
|
|
206
|
+
deps.stdout(`${out.join('\n')}\n`);
|
|
207
|
+
if (toolkit.failed === null)
|
|
208
|
+
return 0;
|
|
209
|
+
const { command, dir, problem } = toolkit.failed;
|
|
210
|
+
deps.stderr(`${TOOL} init: wrote the files above, but ${command} failed (${problem}), so ${CLI} is missing and the hooks and the MCP server can't start\nto fix: run ${command} in ${dir}\n`);
|
|
211
|
+
return 1;
|
|
212
|
+
}
|
|
213
|
+
function summary(description) {
|
|
214
|
+
const end = description.search(/\. |\s-\s/);
|
|
215
|
+
return end === -1 ? description : description.slice(0, end);
|
|
216
|
+
}
|
|
217
|
+
function skills(args, deps) {
|
|
218
|
+
const { positionals } = parseArgs({ args, strict: true, allowPositionals: true, options: {} });
|
|
219
|
+
const [verb, name, ...extra] = positionals;
|
|
220
|
+
const all = listSkills(deps.skillsDir ?? SKILLS_DIR);
|
|
221
|
+
if (verb === 'list' && name === undefined) {
|
|
222
|
+
const width = Math.max(...all.map(s => s.name.length));
|
|
223
|
+
for (const skill of all)
|
|
224
|
+
deps.stdout(`${skill.name.padEnd(width)} ${summary(skill.description)}\n`);
|
|
225
|
+
return 0;
|
|
226
|
+
}
|
|
227
|
+
if (verb === 'get' && name !== undefined && extra.length === 0) {
|
|
228
|
+
const skill = all.find(s => s.name === name);
|
|
229
|
+
if (!skill)
|
|
230
|
+
throw new UsageError(`there is no skill '${name}'`, `pass one of: ${all.map(s => s.name).join(', ')}`);
|
|
231
|
+
deps.stdout(skill.body);
|
|
232
|
+
return 0;
|
|
233
|
+
}
|
|
234
|
+
throw new UsageError(`'skills ${positionals.join(' ')}' is not a skills command`, `${CLI} skills list, or ${CLI} skills get <name>`);
|
|
235
|
+
}
|
|
236
|
+
export async function runAgentCommand(command, args, deps) {
|
|
237
|
+
try {
|
|
238
|
+
switch (command) {
|
|
239
|
+
case 'init':
|
|
240
|
+
return await init(args, deps);
|
|
241
|
+
case 'skills':
|
|
242
|
+
return skills(args, deps);
|
|
243
|
+
}
|
|
244
|
+
deps.stderr(`${TOOL}: '${command}' is not an agent command\n\n${AGENT_USAGE}`);
|
|
245
|
+
return 2;
|
|
246
|
+
}
|
|
247
|
+
catch (error) {
|
|
248
|
+
if (error instanceof UsageError) {
|
|
249
|
+
deps.stderr(`${TOOL} ${command}: ${error.message}\n`);
|
|
250
|
+
return 2;
|
|
251
|
+
}
|
|
252
|
+
if (error instanceof TypeError && error.code?.startsWith('ERR_PARSE_ARGS')) {
|
|
253
|
+
deps.stderr(`${TOOL} ${command}: ${error.message}\n\n${commandUsage(AGENT_HELP, command)}`);
|
|
254
|
+
return 2;
|
|
255
|
+
}
|
|
256
|
+
throw error;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { createInterface } from 'node:readline';
|
|
4
|
+
import { agentMarker, AGENTS } from "../registry/owner.js";
|
|
5
|
+
export const AGENT_NAMES = {
|
|
6
|
+
claude: 'Claude Code',
|
|
7
|
+
codex: 'Codex',
|
|
8
|
+
cursor: 'Cursor',
|
|
9
|
+
copilot: 'GitHub Copilot',
|
|
10
|
+
gemini: 'Gemini CLI',
|
|
11
|
+
antigravity: 'Antigravity',
|
|
12
|
+
};
|
|
13
|
+
export const AGENT_FILES = {
|
|
14
|
+
claude: ['CLAUDE.md', 'CLAUDE.local.md', '.claude'],
|
|
15
|
+
codex: ['.codex'],
|
|
16
|
+
cursor: ['.cursor', '.cursorrules'],
|
|
17
|
+
copilot: ['.github/copilot-instructions.md', '.github/instructions', '.github/copilot', '.github/hooks'],
|
|
18
|
+
gemini: ['GEMINI.md', '.gemini'],
|
|
19
|
+
antigravity: ['.agents/rules', '.agents/workflows', '.agents/mcp_config.json', '.agents/hooks.json', '.agent'],
|
|
20
|
+
};
|
|
21
|
+
function fileSignal(root, agent) {
|
|
22
|
+
for (const file of AGENT_FILES[agent]) {
|
|
23
|
+
const stat = fs.statSync(path.join(root, file), { throwIfNoEntry: false });
|
|
24
|
+
if (stat)
|
|
25
|
+
return stat.isDirectory() ? `${file}/` : file;
|
|
26
|
+
}
|
|
27
|
+
return null;
|
|
28
|
+
}
|
|
29
|
+
export function detectAgents(root, env) {
|
|
30
|
+
return AGENTS.flatMap((agent) => {
|
|
31
|
+
const variable = agentMarker(env, agent);
|
|
32
|
+
if (variable !== null)
|
|
33
|
+
return [{ agent, signal: `${variable} is set, so ${AGENT_NAMES[agent]} runs this command` }];
|
|
34
|
+
const file = fileSignal(root, agent);
|
|
35
|
+
return file === null ? [] : [{ agent, signal: file }];
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
export function describeDetections(detected) {
|
|
39
|
+
const width = Math.max(...detected.map(d => d.agent.length));
|
|
40
|
+
return detected.map(d => ` ${d.agent.padEnd(width)} ${d.signal}\n`).join('');
|
|
41
|
+
}
|
|
42
|
+
function menu(detected) {
|
|
43
|
+
const width = Math.max(...AGENTS.map(agent => agent.length));
|
|
44
|
+
const lines = AGENTS.map((agent, i) => {
|
|
45
|
+
const found = detected.find(d => d.agent === agent);
|
|
46
|
+
return ` ${String(i + 1)}. [${found ? 'x' : ' '}] ${agent.padEnd(width)} ${found?.signal ?? ''}`.trimEnd();
|
|
47
|
+
});
|
|
48
|
+
return `Which agents do you use in this project?\n${lines.join('\n')}\n`;
|
|
49
|
+
}
|
|
50
|
+
function question(detected) {
|
|
51
|
+
const example = '(such as 1,3 or claude,codex)';
|
|
52
|
+
return detected.length > 0
|
|
53
|
+
? `Press Enter to wire ${detected.map(d => d.agent).join(', ')}, or type the numbers or names to wire instead ${example}: `
|
|
54
|
+
: `Type the numbers or names of the agents to wire ${example}: `;
|
|
55
|
+
}
|
|
56
|
+
function parseChoice(line, detected) {
|
|
57
|
+
const words = line
|
|
58
|
+
.trim()
|
|
59
|
+
.split(/[\s,]+/)
|
|
60
|
+
.filter(word => word !== '');
|
|
61
|
+
if (words.length === 0)
|
|
62
|
+
return detected.length > 0 ? detected.map(d => d.agent) : 'Nothing is checked, so name at least one agent.';
|
|
63
|
+
const chosen = new Set();
|
|
64
|
+
for (const word of words) {
|
|
65
|
+
const agent = /^\d+$/.test(word) ? AGENTS[Number(word) - 1] : AGENTS.find(name => name === word.toLowerCase());
|
|
66
|
+
if (agent === undefined)
|
|
67
|
+
return `'${word}' is not one of the agents above.`;
|
|
68
|
+
chosen.add(agent);
|
|
69
|
+
}
|
|
70
|
+
return AGENTS.filter(agent => chosen.has(agent));
|
|
71
|
+
}
|
|
72
|
+
export async function chooseAgents(detected, terminal) {
|
|
73
|
+
const lines = createInterface({ input: terminal.input, terminal: false });
|
|
74
|
+
const answers = lines[Symbol.asyncIterator]();
|
|
75
|
+
try {
|
|
76
|
+
terminal.output.write(`${menu(detected)}${question(detected)}`);
|
|
77
|
+
for (let next = await answers.next(); next.done !== true; next = await answers.next()) {
|
|
78
|
+
const answer = parseChoice(next.value, detected);
|
|
79
|
+
if (typeof answer !== 'string')
|
|
80
|
+
return answer;
|
|
81
|
+
terminal.output.write(`${answer}\n${question(detected)}`);
|
|
82
|
+
}
|
|
83
|
+
return null;
|
|
84
|
+
}
|
|
85
|
+
finally {
|
|
86
|
+
lines.close();
|
|
87
|
+
}
|
|
88
|
+
}
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { CLI, TOOL } from "../name.js";
|
|
4
|
+
import { claudePluginSource, jsonObjectAt } from "./claude-plugin.js";
|
|
5
|
+
import { removeTable, upsertTable } from "./toml.js";
|
|
6
|
+
import { agentEdits, formerServerIn, mirrorEdit, SKILLS, stubEdits, unlinkEdit } from "./wiring.js";
|
|
7
|
+
import { isStubOf, parseSkill } from "./skills.js";
|
|
8
|
+
function readText(file) {
|
|
9
|
+
try {
|
|
10
|
+
return fs.readFileSync(file, 'utf8');
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
if (error.code === 'ENOENT')
|
|
14
|
+
return null;
|
|
15
|
+
throw error;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
function indentOf(text) {
|
|
19
|
+
const indented = /\n([ \t]+)\S/.exec(text);
|
|
20
|
+
const unit = indented?.[1];
|
|
21
|
+
if (unit === undefined)
|
|
22
|
+
return 2;
|
|
23
|
+
return unit.startsWith('\t') ? '\t' : unit.length;
|
|
24
|
+
}
|
|
25
|
+
function readJson(text) {
|
|
26
|
+
if (text === null || text.trim() === '')
|
|
27
|
+
return {};
|
|
28
|
+
let value;
|
|
29
|
+
try {
|
|
30
|
+
value = JSON.parse(text);
|
|
31
|
+
}
|
|
32
|
+
catch (error) {
|
|
33
|
+
return `it isn't valid JSON (${error.message})`;
|
|
34
|
+
}
|
|
35
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value))
|
|
36
|
+
return 'it holds JSON that is not an object';
|
|
37
|
+
return value;
|
|
38
|
+
}
|
|
39
|
+
function refused(file, edits, reason) {
|
|
40
|
+
return {
|
|
41
|
+
file,
|
|
42
|
+
status: 'refused',
|
|
43
|
+
reason: `${file}: ${reason}; init leaves a file it can't merge into untouched`,
|
|
44
|
+
desired: null,
|
|
45
|
+
edits,
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
function planJson(root, file, edits) {
|
|
49
|
+
const text = readText(path.join(root, file));
|
|
50
|
+
const doc = readJson(text);
|
|
51
|
+
if (typeof doc === 'string')
|
|
52
|
+
return refused(file, edits, doc);
|
|
53
|
+
const before = JSON.stringify(doc);
|
|
54
|
+
const next = structuredClone(doc);
|
|
55
|
+
for (const edit of edits) {
|
|
56
|
+
if (edit.kind !== 'json')
|
|
57
|
+
continue;
|
|
58
|
+
const problem = edit.apply(next);
|
|
59
|
+
if (problem !== null)
|
|
60
|
+
return refused(file, edits, problem);
|
|
61
|
+
}
|
|
62
|
+
if (text !== null && JSON.stringify(next) === before)
|
|
63
|
+
return { file, status: 'unchanged', reason: null, desired: null, edits };
|
|
64
|
+
if (edits.some(edit => edit.kind === 'json' && edit.emptied?.(next) === true)) {
|
|
65
|
+
return text === null
|
|
66
|
+
? { file, status: 'unchanged', reason: null, desired: null, edits }
|
|
67
|
+
: { file, status: 'remove', reason: null, desired: null, edits };
|
|
68
|
+
}
|
|
69
|
+
return {
|
|
70
|
+
file,
|
|
71
|
+
status: text === null ? 'create' : 'update',
|
|
72
|
+
reason: null,
|
|
73
|
+
desired: { kind: 'text', text: `${JSON.stringify(next, null, text === null ? 2 : indentOf(text))}\n` },
|
|
74
|
+
edits,
|
|
75
|
+
};
|
|
76
|
+
}
|
|
77
|
+
function planToml(root, file, edits) {
|
|
78
|
+
const text = readText(path.join(root, file));
|
|
79
|
+
let next = text ?? '';
|
|
80
|
+
let changed = text === null;
|
|
81
|
+
for (const edit of edits) {
|
|
82
|
+
if (edit.kind !== 'toml')
|
|
83
|
+
continue;
|
|
84
|
+
const result = edit.body === null ? removeTable(next, edit.table) : upsertTable(next, edit.table, edit.body);
|
|
85
|
+
if (result.kind === 'refused')
|
|
86
|
+
return refused(file, edits, result.reason);
|
|
87
|
+
if (result.kind === 'changed') {
|
|
88
|
+
next = result.text;
|
|
89
|
+
changed = true;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
if (!changed)
|
|
93
|
+
return { file, status: 'unchanged', reason: null, desired: null, edits };
|
|
94
|
+
return { file, status: text === null ? 'create' : 'update', reason: null, desired: { kind: 'text', text: next }, edits };
|
|
95
|
+
}
|
|
96
|
+
function planStub(root, edit) {
|
|
97
|
+
const text = readText(path.join(root, edit.file));
|
|
98
|
+
const desired = { kind: 'text', text: edit.content };
|
|
99
|
+
if (text === null)
|
|
100
|
+
return { file: edit.file, status: 'create', reason: null, desired, edits: [edit] };
|
|
101
|
+
if (text === edit.content)
|
|
102
|
+
return { file: edit.file, status: 'unchanged', reason: null, desired: null, edits: [edit] };
|
|
103
|
+
if (isStubOf(text, edit.skill))
|
|
104
|
+
return { file: edit.file, status: 'update', reason: null, desired, edits: [edit] };
|
|
105
|
+
return refused(edit.file, [edit], `it holds a different skill named ${edit.skill}; rename one of them`);
|
|
106
|
+
}
|
|
107
|
+
function onlySkillFile(dir) {
|
|
108
|
+
const entries = fs.readdirSync(dir);
|
|
109
|
+
if (entries.length !== 1 || entries[0] !== 'SKILL.md')
|
|
110
|
+
return null;
|
|
111
|
+
return readText(path.join(dir, 'SKILL.md'));
|
|
112
|
+
}
|
|
113
|
+
function planLink(root, edit) {
|
|
114
|
+
const at = path.join(root, edit.file);
|
|
115
|
+
const desired = { kind: 'link', target: edit.target };
|
|
116
|
+
let stat;
|
|
117
|
+
try {
|
|
118
|
+
stat = fs.lstatSync(at);
|
|
119
|
+
}
|
|
120
|
+
catch {
|
|
121
|
+
return { file: edit.file, status: 'create', reason: null, desired, edits: [edit] };
|
|
122
|
+
}
|
|
123
|
+
if (stat.isSymbolicLink()) {
|
|
124
|
+
const target = fs.readlinkSync(at);
|
|
125
|
+
if (target === edit.target)
|
|
126
|
+
return { file: edit.file, status: 'unchanged', reason: null, desired: null, edits: [edit] };
|
|
127
|
+
return refused(edit.file, [edit], `it is a link to ${target}, not to ${edit.target}`);
|
|
128
|
+
}
|
|
129
|
+
const copy = stat.isDirectory() ? onlySkillFile(at) : null;
|
|
130
|
+
if (copy !== null && (copy === edit.source || isStubOf(copy, edit.skill)))
|
|
131
|
+
return { file: edit.file, status: 'update', reason: null, desired, edits: [edit] };
|
|
132
|
+
return refused(edit.file, [edit], `it holds its own copy of the ${edit.skill} skill; keep one copy, in ${SKILLS}/${edit.skill}/, and run ${CLI} init again`);
|
|
133
|
+
}
|
|
134
|
+
function planUnlink(root, edit) {
|
|
135
|
+
const at = path.join(root, edit.file);
|
|
136
|
+
let stat;
|
|
137
|
+
try {
|
|
138
|
+
stat = fs.lstatSync(at);
|
|
139
|
+
}
|
|
140
|
+
catch {
|
|
141
|
+
return null;
|
|
142
|
+
}
|
|
143
|
+
const ours = stat.isSymbolicLink()
|
|
144
|
+
? fs.readlinkSync(at) === edit.target
|
|
145
|
+
: stat.isDirectory() && isStubOf(onlySkillFile(at) ?? '', edit.skill);
|
|
146
|
+
return ours ? { file: edit.file, status: 'remove', reason: null, desired: null, edits: [edit] } : null;
|
|
147
|
+
}
|
|
148
|
+
function projectSkills(root, toolkit) {
|
|
149
|
+
const dir = path.join(root, SKILLS);
|
|
150
|
+
let names;
|
|
151
|
+
try {
|
|
152
|
+
names = fs.readdirSync(dir).sort();
|
|
153
|
+
}
|
|
154
|
+
catch {
|
|
155
|
+
return [];
|
|
156
|
+
}
|
|
157
|
+
return names.flatMap(name => {
|
|
158
|
+
if (toolkit.has(name))
|
|
159
|
+
return [];
|
|
160
|
+
const source = readText(path.join(dir, name, 'SKILL.md'));
|
|
161
|
+
if (source === null)
|
|
162
|
+
return [];
|
|
163
|
+
try {
|
|
164
|
+
parseSkill(source, name);
|
|
165
|
+
}
|
|
166
|
+
catch {
|
|
167
|
+
return [];
|
|
168
|
+
}
|
|
169
|
+
return [{ name, source }];
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
function mcpServerIn(root) {
|
|
173
|
+
const servers = jsonObjectAt(path.join(root, '.mcp.json'))?.mcpServers;
|
|
174
|
+
return (typeof servers === 'object' && servers !== null && TOOL in servers) || formerServerIn(servers);
|
|
175
|
+
}
|
|
176
|
+
export function planInit(root, agents, skills, env) {
|
|
177
|
+
const claudePlugin = agents.includes('claude') ? claudePluginSource(root, env) : null;
|
|
178
|
+
const stubs = agents.some(agent => agent !== 'claude') || claudePlugin === null ? stubEdits(skills) : [];
|
|
179
|
+
const disableServer = claudePlugin !== null && (claudePlugin.kind !== 'project' || agents.includes('copilot') || mcpServerIn(root));
|
|
180
|
+
const edits = [...stubs, ...agents.flatMap(agent => agentEdits(agent, claudePlugin !== null, disableServer))];
|
|
181
|
+
if (agents.includes('claude')) {
|
|
182
|
+
if (claudePlugin)
|
|
183
|
+
for (const skill of skills)
|
|
184
|
+
edits.push(unlinkEdit(skill.name));
|
|
185
|
+
else
|
|
186
|
+
for (const stub of stubs)
|
|
187
|
+
if (stub.kind === 'stub')
|
|
188
|
+
edits.push(mirrorEdit(stub.skill, stub.content));
|
|
189
|
+
for (const own of projectSkills(root, new Set(skills.map(s => s.name))))
|
|
190
|
+
edits.push(mirrorEdit(own.name, own.source));
|
|
191
|
+
}
|
|
192
|
+
const byFile = new Map();
|
|
193
|
+
for (const edit of edits)
|
|
194
|
+
byFile.set(edit.file, [...(byFile.get(edit.file) ?? []), edit]);
|
|
195
|
+
const files = [...byFile].flatMap(([file, group]) => {
|
|
196
|
+
const [first] = group;
|
|
197
|
+
if (first?.kind === 'stub')
|
|
198
|
+
return [planStub(root, first)];
|
|
199
|
+
if (first?.kind === 'link')
|
|
200
|
+
return [planLink(root, first)];
|
|
201
|
+
if (first?.kind === 'unlink') {
|
|
202
|
+
const removal = planUnlink(root, first);
|
|
203
|
+
return removal ? [removal] : [];
|
|
204
|
+
}
|
|
205
|
+
if (first?.kind === 'toml')
|
|
206
|
+
return [planToml(root, file, group)];
|
|
207
|
+
const plan = planJson(root, file, group);
|
|
208
|
+
const cleanupOnly = group.every(edit => edit.kind === 'json' && edit.cleanup === true);
|
|
209
|
+
return cleanupOnly && plan.status === 'unchanged' ? [] : [plan];
|
|
210
|
+
});
|
|
211
|
+
return { root, agents: [...agents], claudePlugin, files };
|
|
212
|
+
}
|
|
213
|
+
function backup(root, file, into) {
|
|
214
|
+
const from = path.join(root, file);
|
|
215
|
+
try {
|
|
216
|
+
fs.lstatSync(from);
|
|
217
|
+
}
|
|
218
|
+
catch {
|
|
219
|
+
return;
|
|
220
|
+
}
|
|
221
|
+
const to = path.join(into, file);
|
|
222
|
+
fs.mkdirSync(path.dirname(to), { recursive: true });
|
|
223
|
+
fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true });
|
|
224
|
+
}
|
|
225
|
+
export function applyInit(plan, backupDir) {
|
|
226
|
+
if (plan.files.some(f => f.status === 'refused'))
|
|
227
|
+
throw new Error('a refused plan is never applied');
|
|
228
|
+
const written = plan.files.filter(f => f.status === 'create' || f.status === 'update' || f.status === 'remove');
|
|
229
|
+
let backed = false;
|
|
230
|
+
for (const file of written) {
|
|
231
|
+
if (file.status !== 'create') {
|
|
232
|
+
backup(plan.root, file.file, backupDir);
|
|
233
|
+
backed = true;
|
|
234
|
+
}
|
|
235
|
+
const at = path.join(plan.root, file.file);
|
|
236
|
+
if (file.status === 'remove') {
|
|
237
|
+
fs.rmSync(at, { recursive: true, force: true });
|
|
238
|
+
continue;
|
|
239
|
+
}
|
|
240
|
+
fs.mkdirSync(path.dirname(at), { recursive: true });
|
|
241
|
+
const desired = file.desired;
|
|
242
|
+
if (desired?.kind === 'link') {
|
|
243
|
+
fs.rmSync(at, { recursive: true, force: true });
|
|
244
|
+
fs.symlinkSync(desired.target, at);
|
|
245
|
+
}
|
|
246
|
+
else if (desired?.kind === 'text') {
|
|
247
|
+
fs.writeFileSync(at, desired.text);
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
return { written, backups: backed ? backupDir : null };
|
|
251
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { CLI, FORMER, TOOL } from "../name.js";
|
|
2
|
+
/**
|
|
3
|
+
* Gemini CLI replaces the literal text `$GEMINI_PROJECT_DIR` and `$CLAUDE_PROJECT_DIR` in a hook command with a quoted
|
|
4
|
+
* path before it runs, so a launcher meant for Gemini starts from `$PWD`, which Gemini sets to the project.
|
|
5
|
+
*/
|
|
6
|
+
const START = {
|
|
7
|
+
claude: '${CLAUDE_PROJECT_DIR:-$PWD}',
|
|
8
|
+
codex: '$PWD',
|
|
9
|
+
cursor: '${CURSOR_PROJECT_DIR:-$PWD}',
|
|
10
|
+
copilot: '$PWD',
|
|
11
|
+
gemini: '$PWD',
|
|
12
|
+
antigravity: '$PWD',
|
|
13
|
+
};
|
|
14
|
+
function launch(start, args, missing) {
|
|
15
|
+
return `d="${start}"; while [ ! -x "$d/${CLI}" ] && [ "$d" != / ]; do d=$(dirname "$d"); done; if [ -x "$d/${CLI}" ]; then exec "$d/${CLI}" ${args}; fi; ${missing}`;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* The command an agent's hook runs: the project's own toolkit, found from the folder the hook runs in upwards. Without
|
|
19
|
+
* a toolkit it allows and exits 0, because Copilot denies the tool call on any other exit and Gemini on exit 2 or
|
|
20
|
+
* more, and Cursor needs a JSON answer.
|
|
21
|
+
*/
|
|
22
|
+
export function hookCommand(agent, event) {
|
|
23
|
+
const allow = agent === 'cursor' && event === 'pre-tool-use' ? `echo '{"permission":"allow"}'` : 'exit 0';
|
|
24
|
+
return launch(START[agent], `hook ${event} --agent ${agent}`, allow);
|
|
25
|
+
}
|
|
26
|
+
export function mcpLaunch() {
|
|
27
|
+
const missing = `echo "${TOOL}: no ${CLI} in $PWD or the folders above it; add the toolkit to this project" >&2; exit 1`;
|
|
28
|
+
return { command: 'sh', args: ['-c', launch('$PWD', 'mcp', missing)] };
|
|
29
|
+
}
|
|
30
|
+
export function isToolkitHook(command) {
|
|
31
|
+
return typeof command === 'string' && [CLI, FORMER.cli].some(cli => command.includes(`/${cli}" hook `));
|
|
32
|
+
}
|