agentlane 0.4.1 → 0.5.1

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.
Files changed (75) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/dist/agents/claude-plugin.js +69 -8
  3. package/dist/agents/cli.js +11 -4
  4. package/dist/agents/hook-check.js +290 -0
  5. package/dist/agents/launcher.js +34 -6
  6. package/dist/agents/wiring-check.js +10 -4
  7. package/dist/agents/wiring.js +6 -33
  8. package/dist/browser/env.js +27 -7
  9. package/dist/browser/install.js +144 -6
  10. package/dist/browser/lane-browser.js +6 -3
  11. package/dist/browser/stop.js +2 -17
  12. package/dist/cache/key.js +23 -11
  13. package/dist/cli.js +63 -23
  14. package/dist/devices/backend.js +6 -0
  15. package/dist/devices/emulator.js +15 -5
  16. package/dist/devices/hygiene.js +20 -4
  17. package/dist/devices/simctl.js +15 -3
  18. package/dist/disk-limits.js +134 -0
  19. package/dist/driver/caller.js +21 -6
  20. package/dist/driver/client.js +9 -5
  21. package/dist/driver/engine.js +29 -14
  22. package/dist/driver/install.js +88 -36
  23. package/dist/driver/paths.js +15 -11
  24. package/dist/driver/session.js +4 -1
  25. package/dist/driver/superseded.js +378 -0
  26. package/dist/driver-cli.js +32 -23
  27. package/dist/evidence/device.js +4 -0
  28. package/dist/evidence/evidence.js +4 -2
  29. package/dist/evidence/files.js +68 -0
  30. package/dist/evidence/strays.js +107 -0
  31. package/dist/hooks/env.js +2 -1
  32. package/dist/mcp/server.js +15 -0
  33. package/dist/mcp/tools.js +9 -1
  34. package/dist/plugin/guard.js +30 -0
  35. package/dist/plugin/hook-cli.js +101 -6
  36. package/dist/plugin/hook-mark.js +73 -0
  37. package/dist/plugin/hook-once.js +78 -0
  38. package/dist/plugin/shell.js +109 -8
  39. package/dist/processes.js +52 -2
  40. package/dist/registry/config.js +12 -8
  41. package/dist/registry/holds.js +37 -0
  42. package/dist/registry/leases.js +109 -0
  43. package/dist/registry/owner-checks.js +55 -0
  44. package/dist/registry/owner.js +18 -0
  45. package/dist/registry/parks.js +60 -0
  46. package/dist/registry/paths.js +28 -4
  47. package/dist/registry/ports.js +5 -1
  48. package/dist/registry/prune.js +643 -24
  49. package/dist/registry/refusal.js +1 -0
  50. package/dist/registry/registry.js +1261 -236
  51. package/dist/registry/rows.js +18 -4
  52. package/dist/registry/status.js +51 -8
  53. package/dist/registry/store.js +65 -2
  54. package/dist/registry/touch.js +180 -0
  55. package/dist/registry-cli.js +197 -36
  56. package/dist/services/services.js +227 -56
  57. package/dist/services/system.js +2 -1
  58. package/dist/up/answers.js +124 -0
  59. package/dist/up/doctor.js +29 -4
  60. package/dist/up/exec.js +29 -4
  61. package/dist/up/lane-files.js +26 -8
  62. package/dist/up/lane-services.js +8 -3
  63. package/dist/up/park.js +146 -0
  64. package/dist/up/preflight.js +2 -10
  65. package/dist/up/release.js +20 -24
  66. package/dist/up/restart.js +9 -2
  67. package/dist/up/sweep.js +437 -0
  68. package/dist/up/up.js +38 -15
  69. package/dist/up/wake.js +124 -0
  70. package/dist/up/waker.js +49 -0
  71. package/dist/up-cli.js +6 -1
  72. package/package.json +2 -2
  73. package/skills/dev-loop/SKILL.md +7 -5
  74. package/skills/drive/SKILL.md +4 -0
  75. package/skills/setup/SKILL.md +2 -2
@@ -11,6 +11,7 @@ import { DriverError } from "./errors.js";
11
11
  import { runCommand, tail } from "./exec.js";
12
12
  import { tryLock, unlock } from "./lock.js";
13
13
  import { MAESTRO_RELEASE } from "./release.js";
14
+ import { compareVersions, laneToolsOf, removeOlderVersions, systemCommandLines, } from "./superseded.js";
14
15
  /** A Maestro binary to use instead of the pinned build, such as a local build of `maestro/`. */
15
16
  export const MAESTRO_OVERRIDE_ENV = envName('MAESTRO');
16
17
  const JDK_FIX = `install JDK 17 ('brew install openjdk@17'), or set ${JAVA_HOME_ENV} to a JDK 17 home`;
@@ -20,9 +21,31 @@ export function dataDir(env) {
20
21
  const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(env.HOME ?? os.homedir(), '.local', 'share');
21
22
  return path.join(base, TOOL);
22
23
  }
24
+ /** The data folder when the environment names it, by XDG_DATA_HOME or HOME, rather than by the OS's idea of home. */
25
+ export function namedDataDir(env) {
26
+ const xdg = env.XDG_DATA_HOME;
27
+ return (xdg && path.isAbsolute(xdg)) || env.HOME ? dataDir(env) : undefined;
28
+ }
23
29
  export function maestroHome(env, release = MAESTRO_RELEASE) {
24
30
  return path.join(dataDir(env), 'maestro', release.version);
25
31
  }
32
+ function lockOf(base, version) {
33
+ return path.join(base, `.${version}.lock`);
34
+ }
35
+ /** The builds this toolkit installed beside the pinned one that are older than it. */
36
+ function olderBuilds(base, release) {
37
+ let names;
38
+ try {
39
+ names = fs.readdirSync(base);
40
+ }
41
+ catch {
42
+ return [];
43
+ }
44
+ return names
45
+ .filter(name => !name.startsWith('.') && compareVersions(name, release.version) < 0)
46
+ .filter(name => readMarker(path.join(base, name))?.version === name)
47
+ .map(name => ({ dir: path.join(base, name), lock: lockOf(base, name) }));
48
+ }
26
49
  function binaryIn(home) {
27
50
  return path.join(home, 'maestro', 'bin', 'maestro');
28
51
  }
@@ -63,43 +86,61 @@ async function javaSettings(home) {
63
86
  javaHome: /^\s*java\.home = (.+)$/m.exec(text)?.[1]?.trim(),
64
87
  };
65
88
  }
66
- /** Finds JDK 17: AGENTLANE_JAVA_HOME, then the way maestro/build.sh does, JAVA_HOME, java_home -v 17 and Homebrew's openjdk@17. */
67
- export async function findJdk17(env) {
68
- let candidate;
69
- let origin;
70
- const named = env[JAVA_HOME_ENV] ? JAVA_HOME_ENV : env.JAVA_HOME ? 'JAVA_HOME' : undefined;
71
- if (named) {
72
- candidate = env[named];
73
- origin = `${named}=${candidate ?? ''}`;
89
+ export const JAVA_HOME_TOOL = '/usr/libexec/java_home';
90
+ /** The JDK 17 macOS has registered. Without -F, java_home prints the default JDK when none matches. */
91
+ export async function registeredJdk17(tool = JAVA_HOME_TOOL) {
92
+ const found = await runCommand(tool, ['-F', '-v', '17'], { timeoutMs: 10_000 });
93
+ return found.code === 0 && found.stdout.trim() ? found.stdout.trim() : undefined;
94
+ }
95
+ /** The way maestro/build.sh looks: java_home -F -v 17, then Homebrew's openjdk@17. */
96
+ export const systemJdk17 = async () => {
97
+ const registered = await registeredJdk17();
98
+ if (registered !== undefined)
99
+ return { home: registered, origin: `${JAVA_HOME_TOOL} -F -v 17` };
100
+ const prefixes = ['/opt/homebrew/opt/openjdk@17', '/usr/local/opt/openjdk@17'];
101
+ if (!prefixes.some(prefix => isExecutable(path.join(prefix, 'bin', 'java')))) {
102
+ const brew = await runCommand('brew', ['--prefix', 'openjdk@17'], { timeoutMs: 10_000 });
103
+ if (brew.code === 0 && brew.stdout.trim())
104
+ prefixes.unshift(brew.stdout.trim());
74
105
  }
75
- else {
76
- const javaHome = await runCommand('/usr/libexec/java_home', ['-v', '17'], { timeoutMs: 10_000 });
77
- if (javaHome.code === 0 && javaHome.stdout.trim()) {
78
- candidate = javaHome.stdout.trim();
79
- origin = '/usr/libexec/java_home -v 17';
80
- }
81
- else {
82
- const prefixes = ['/opt/homebrew/opt/openjdk@17', '/usr/local/opt/openjdk@17'];
83
- if (!prefixes.some(prefix => isExecutable(path.join(prefix, 'bin', 'java')))) {
84
- const brew = await runCommand('brew', ['--prefix', 'openjdk@17'], { timeoutMs: 10_000 });
85
- if (brew.code === 0 && brew.stdout.trim())
86
- prefixes.unshift(brew.stdout.trim());
87
- }
88
- candidate = prefixes.find(prefix => isExecutable(path.join(prefix, 'bin', 'java')));
89
- origin = `Homebrew's openjdk@17 (${candidate ?? 'not installed'})`;
106
+ const home = prefixes.find(prefix => isExecutable(path.join(prefix, 'bin', 'java')));
107
+ return home === undefined ? undefined : { home, origin: `Homebrew's openjdk@17 (${home})` };
108
+ };
109
+ function javaProblem(origin, spec) {
110
+ if (spec === undefined)
111
+ return `${origin} has no working bin/java`;
112
+ if (spec !== '17')
113
+ return `${origin} is Java ${spec}`;
114
+ return undefined;
115
+ }
116
+ export async function findJdk17(env, search = systemJdk17) {
117
+ const pinned = env[JAVA_HOME_ENV];
118
+ if (pinned) {
119
+ const origin = `${JAVA_HOME_ENV}=${pinned}`;
120
+ const settings = await javaSettings(pinned);
121
+ const problem = javaProblem(origin, settings.spec);
122
+ if (problem !== undefined) {
123
+ throw new DriverError(`${problem}, and Maestro runs on JDK 17`, `${JDK_FIX}, or unset ${JAVA_HOME_ENV} so ${TOOL} finds one`);
90
124
  }
125
+ return { javaHome: settings.javaHome ?? pinned, origin };
91
126
  }
92
- if (!candidate)
93
- throw new DriverError('no JDK 17 found; Maestro runs on JDK 17', JDK_FIX);
94
- const fix = named ? `${JDK_FIX}, or unset ${named} so ${TOOL} finds one` : JDK_FIX;
95
- const settings = await javaSettings(candidate);
96
- if (settings.spec === undefined) {
97
- throw new DriverError(`${origin} has no working bin/java`, fix);
98
- }
99
- if (settings.spec !== '17') {
100
- throw new DriverError(`${origin} is Java ${settings.spec}, and Maestro runs on JDK 17`, fix);
127
+ let skipped;
128
+ if (env.JAVA_HOME) {
129
+ const origin = `JAVA_HOME=${env.JAVA_HOME}`;
130
+ const settings = await javaSettings(env.JAVA_HOME);
131
+ skipped = javaProblem(origin, settings.spec);
132
+ if (skipped === undefined)
133
+ return { javaHome: settings.javaHome ?? env.JAVA_HOME, origin };
101
134
  }
102
- return { javaHome: settings.javaHome ?? candidate, origin };
135
+ const found = await search();
136
+ const passedOver = skipped === undefined ? '' : ` (${skipped})`;
137
+ if (!found)
138
+ throw new DriverError(`no JDK 17 found${passedOver}; Maestro runs on JDK 17`, JDK_FIX);
139
+ const settings = await javaSettings(found.home);
140
+ const problem = javaProblem(found.origin, settings.spec);
141
+ if (problem !== undefined)
142
+ throw new DriverError(`${problem}${passedOver}, and Maestro runs on JDK 17`, JDK_FIX);
143
+ return { javaHome: settings.javaHome ?? found.home, origin: found.origin };
103
144
  }
104
145
  export async function sha256Of(file) {
105
146
  const hash = crypto.createHash('sha256');
@@ -172,7 +213,10 @@ async function unpack(release, zip, into, jdk) {
172
213
  throw new DriverError(`the unpacked Maestro prints '${printed ?? ''}' for --version (exit ${String(version.code)}), not ${release.version}: ${tail(version.stderr, 5)}`, `check that ${jdk.origin} is a working JDK 17, then retry '${CLI} driver install'`);
173
214
  }
174
215
  }
175
- /** Installs the pinned Maestro build on first use: download, check against the pinned sha256, unpack, check --version. */
216
+ /**
217
+ * Installs the pinned Maestro build on first use: download, check against the pinned sha256, unpack, check --version.
218
+ * Then removes the older builds it installed that no running process or lane uses.
219
+ */
176
220
  export async function ensureMaestro(options) {
177
221
  const release = options.release ?? MAESTRO_RELEASE;
178
222
  const ready = installedMaestro(options.env, release);
@@ -180,7 +224,7 @@ export async function ensureMaestro(options) {
180
224
  return ready;
181
225
  const started = Date.now();
182
226
  const log = options.log ?? (() => undefined);
183
- const jdk = await findJdk17(options.env);
227
+ const jdk = await findJdk17(options.env, options.searchJdk17);
184
228
  const home = maestroHome(options.env, release);
185
229
  const base = path.dirname(home);
186
230
  fs.mkdirSync(base, { recursive: true, mode: 0o700 });
@@ -188,7 +232,7 @@ export async function ensureMaestro(options) {
188
232
  const me = identityOf(processes, process.pid);
189
233
  if (!me)
190
234
  throw new Error(`ps could not read this process's start time (pid ${String(process.pid)})`);
191
- const lock = path.join(base, `.${release.version}.lock`);
235
+ const lock = lockOf(base, release.version);
192
236
  const deadline = Date.now() + (options.lockWaitMs ?? INSTALL_LOCK_WAIT_MS);
193
237
  let announced = false;
194
238
  for (;;) {
@@ -225,6 +269,14 @@ export async function ensureMaestro(options) {
225
269
  fs.renameSync(home, path.join(work, 'previous'));
226
270
  fs.renameSync(unpacked, home);
227
271
  log(`installed Maestro ${release.version} in ${home}`);
272
+ removeOlderVersions(olderBuilds(base, release), {
273
+ root: namedDataDir(options.env),
274
+ me,
275
+ processes,
276
+ commandLines: options.commandLines ?? systemCommandLines,
277
+ laneTools: options.laneTools ?? laneToolsOf(options.env),
278
+ log,
279
+ });
228
280
  return { home, binary: binaryIn(home), version: release.version, installedNow: true, ms: Date.now() - started };
229
281
  }
230
282
  finally {
@@ -2,25 +2,29 @@ import { spawnSync } from 'node:child_process';
2
2
  import crypto from 'node:crypto';
3
3
  import fs from 'node:fs';
4
4
  import path from 'node:path';
5
+ import { envName } from "../name.js";
5
6
  import { diskNames, lanesRoot } from "../registry/paths.js";
6
7
  import { DriverError } from "./errors.js";
7
8
  import { isAlive } from "./exec.js";
8
9
  import { lockHolder } from "./lock.js";
9
10
  // sockaddr_un.sun_path holds 104 bytes on macOS and 108 on Linux, terminator included.
10
11
  export const SUN_PATH_LIMIT = 100;
12
+ export const USER_TEMP_ENV = envName('USER_TEMP');
11
13
  let cachedTemp;
14
+ function findPerUserTemp() {
15
+ const override = process.env[USER_TEMP_ENV];
16
+ if (override && path.isAbsolute(override))
17
+ return override;
18
+ if (process.platform !== 'darwin')
19
+ return '/tmp';
20
+ const result = spawnSync('getconf', ['DARWIN_USER_TEMP_DIR'], { encoding: 'utf8' });
21
+ const found = result.status === 0 ? result.stdout.trim() : '';
22
+ return found || '/tmp';
23
+ }
24
+ /** The folder for sockets whose path in the state dir would be too long: macOS's per-user temp folder, or /tmp. */
12
25
  export function perUserTemp() {
13
- if (cachedTemp !== undefined)
14
- return cachedTemp;
15
- let dir = '/tmp';
16
- if (process.platform === 'darwin') {
17
- const result = spawnSync('getconf', ['DARWIN_USER_TEMP_DIR'], { encoding: 'utf8' });
18
- const found = result.status === 0 ? result.stdout.trim() : '';
19
- if (found)
20
- dir = found;
21
- }
22
- cachedTemp = dir;
23
- return dir;
26
+ cachedTemp ??= findPerUserTemp();
27
+ return cachedTemp;
24
28
  }
25
29
  export function ensurePrivateDir(dir) {
26
30
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -1,5 +1,6 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
+ import { keepNewestLinesAsSoleWriter } from "../disk-limits.js";
3
4
  import { checkAbsent, readIn, treeBound } from "./absence.js";
4
5
  import { diffScreens, renderDiff, volatileBetween } from "./diff.js";
5
6
  import { messageOf } from "./errors.js";
@@ -16,6 +17,7 @@ import { parseInspectScreen } from "./tree.js";
16
17
  export const PIXEL_CHECK_WIDTH = 200;
17
18
  const VOLATILE_TTL_MS = 5 * 60_000;
18
19
  const RECENT_READ_MS = 5000;
20
+ export const RECORDED_STEPS_LIMIT = { maxBytes: 1024 * 1024, keepBytes: 512 * 1024 };
19
21
  const RESPAWN_NOTE = "Maestro's session was rebuilt for this call";
20
22
  /** Turns a `run` reply into its error text: per-flow errors from a file run, the plain message from inline YAML. */
21
23
  export function flowError(reply) {
@@ -337,7 +339,8 @@ export class DriverSession {
337
339
  if (run.passed === 0)
338
340
  return;
339
341
  fs.mkdirSync(path.dirname(this.stepsFile), { recursive: true, mode: 0o700 });
340
- fs.appendFileSync(this.stepsFile, `${JSON.stringify(run)}\n`);
342
+ fs.appendFileSync(this.stepsFile, `${JSON.stringify({ ...run, at: Date.now() })}\n`);
343
+ keepNewestLinesAsSoleWriter(this.stepsFile, RECORDED_STEPS_LIMIT);
341
344
  }
342
345
  async run(args) {
343
346
  const started = Date.now();
@@ -0,0 +1,378 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import fs from 'node:fs';
3
+ import os from 'node:os';
4
+ import path from 'node:path';
5
+ import { DatabaseSync } from 'node:sqlite';
6
+ import { FORMER, TOOL } from "../name.js";
7
+ import { environmentOf } from "../processes.js";
8
+ import { databasePath, lanesRoot, STATE_DIR_ENV } from "../registry/paths.js";
9
+ import { bestEffort, tryLock, unlock } from "./lock.js";
10
+ /**
11
+ * The processes in `ps -o pid=,args=` output; undefined unless it shows pid 1's arguments, so it can't see every
12
+ * process. macOS ps prints a process's name in parentheses in place of arguments it may not read.
13
+ */
14
+ export function commandLinesOf(output) {
15
+ const rows = output
16
+ .split('\n')
17
+ .map(line => /^\s*(\d+)\s?(.*)$/.exec(line))
18
+ .filter(row => row !== null);
19
+ if (!rows.some(([, pid, args = '']) => pid === '1' && args.startsWith('/')))
20
+ return undefined;
21
+ return rows.map(([, pid = '', args = '']) => ({ pid: Number(pid), args })).filter(row => row.args.trim() !== '');
22
+ }
23
+ export const systemCommandLines = () => {
24
+ const result = spawnSync('ps', ['-A', '-ww', '-o', 'pid=,args='], {
25
+ encoding: 'utf8',
26
+ env: { PATH: '/bin:/usr/bin', LC_ALL: 'C' },
27
+ timeout: 10_000,
28
+ maxBuffer: 64 * 1024 * 1024,
29
+ });
30
+ if (result.error || result.status !== 0)
31
+ return undefined;
32
+ return commandLinesOf(result.stdout)?.map(({ pid, args }) => ({ args, environment: () => environmentOf(pid) }));
33
+ };
34
+ function registryDirs(env) {
35
+ const xdg = env.XDG_STATE_HOME;
36
+ const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(env.HOME ?? os.homedir(), '.local', 'state');
37
+ const override = env[STATE_DIR_ENV];
38
+ return [...new Set([...(override ? [path.resolve(override)] : []), path.join(base, TOOL), path.join(base, FORMER.tool)])];
39
+ }
40
+ function recordedLaneIds(dir) {
41
+ if (!fs.existsSync(databasePath(dir)))
42
+ return [];
43
+ try {
44
+ const db = new DatabaseSync(databasePath(dir), { readOnly: true, timeout: 1000 });
45
+ try {
46
+ return db
47
+ .prepare('SELECT id FROM claims')
48
+ .all()
49
+ .map(row => String(row.id));
50
+ }
51
+ finally {
52
+ db.close();
53
+ }
54
+ }
55
+ catch {
56
+ return undefined;
57
+ }
58
+ }
59
+ function absent(error) {
60
+ const code = error.code;
61
+ return code === 'ENOENT' || code === 'ENOTDIR';
62
+ }
63
+ function linkTarget(link) {
64
+ try {
65
+ return path.resolve(path.dirname(link), fs.readlinkSync(link));
66
+ }
67
+ catch (error) {
68
+ if (absent(error) || error.code === 'EINVAL')
69
+ return undefined;
70
+ throw error;
71
+ }
72
+ }
73
+ function realPath(file) {
74
+ try {
75
+ return fs.realpathSync(file);
76
+ }
77
+ catch (error) {
78
+ if (absent(error))
79
+ return undefined;
80
+ throw error;
81
+ }
82
+ }
83
+ function targetsOf(file) {
84
+ return [linkTarget(file), realPath(file)].filter(target => target !== undefined);
85
+ }
86
+ function laneFiles(lane) {
87
+ const bin = path.join(lane, 'bin');
88
+ let names = [];
89
+ try {
90
+ names = fs.readdirSync(bin);
91
+ }
92
+ catch (error) {
93
+ if (!absent(error))
94
+ throw error;
95
+ }
96
+ const files = names.map(name => {
97
+ const file = path.join(bin, name);
98
+ const texts = targetsOf(file);
99
+ try {
100
+ texts.push(fs.readFileSync(file, 'utf8'));
101
+ }
102
+ catch (error) {
103
+ if (!absent(error))
104
+ throw error;
105
+ }
106
+ return texts;
107
+ });
108
+ return [...files, targetsOf(path.join(lane, 'browser', 'ffmpeg', 'ffmpeg'))];
109
+ }
110
+ /**
111
+ * What every lane recorded in this version's registry or 0.2.x's runs. Each registry is opened read-only, which never
112
+ * changes its data, though SQLite creates the database's `-shm` and `-wal` files beside it when they are missing.
113
+ */
114
+ export function laneToolsOf(env) {
115
+ return () => {
116
+ const files = [];
117
+ for (const dir of registryDirs(env)) {
118
+ const ids = recordedLaneIds(dir);
119
+ if (ids === undefined)
120
+ return undefined;
121
+ for (const id of ids) {
122
+ try {
123
+ files.push(...laneFiles(path.join(lanesRoot(dir), id)));
124
+ }
125
+ catch {
126
+ return undefined;
127
+ }
128
+ }
129
+ }
130
+ return files;
131
+ };
132
+ }
133
+ const BUILD_TAGS = [FORMER.tool.replaceAll('-', ''), TOOL];
134
+ function parseVersion(version) {
135
+ const [plain = ''] = version.split('+');
136
+ const tagged = new RegExp(`^(.*)-(${BUILD_TAGS.join('|')})\\.([0-9A-Za-z-]+)$`).exec(plain);
137
+ const core = tagged?.[1] ?? plain;
138
+ const dash = core.indexOf('-');
139
+ return {
140
+ release: (dash === -1 ? core : core.slice(0, dash)).split('.'),
141
+ prerelease: dash === -1 ? undefined : core.slice(dash + 1).split('.'),
142
+ build: tagged ? [BUILD_TAGS.indexOf(tagged[2] ?? ''), tagged[3] ?? ''] : undefined,
143
+ };
144
+ }
145
+ function compareParts(x, y) {
146
+ const numeric = /^\d+$/;
147
+ if (numeric.test(x) && numeric.test(y))
148
+ return Number(x) - Number(y);
149
+ if (numeric.test(x))
150
+ return -1;
151
+ if (numeric.test(y))
152
+ return 1;
153
+ return x === y ? 0 : x < y ? -1 : 1;
154
+ }
155
+ function compareLists(left, right) {
156
+ for (let i = 0; i < Math.max(left.length, right.length); i++) {
157
+ const x = left[i];
158
+ const y = right[i];
159
+ if (x === y)
160
+ continue;
161
+ if (x === undefined)
162
+ return -1;
163
+ if (y === undefined)
164
+ return 1;
165
+ const order = compareParts(x, y);
166
+ if (order !== 0)
167
+ return order;
168
+ }
169
+ return 0;
170
+ }
171
+ /**
172
+ * Orders versions as semver does, a prerelease before its release, with this toolkit's own builds of a release after
173
+ * it: 1.65.0-alpha < 1.65.0 < 1.65.0-agentenv.3 < 1.65.0-agentlane.1 < 1.65.0-agentlane.2 < 1.66.0.
174
+ */
175
+ export function compareVersions(a, b) {
176
+ const left = parseVersion(a);
177
+ const right = parseVersion(b);
178
+ const release = compareLists(left.release, right.release);
179
+ if (release !== 0)
180
+ return release;
181
+ if (left.prerelease === undefined || right.prerelease === undefined) {
182
+ if (left.prerelease !== right.prerelease)
183
+ return left.prerelease === undefined ? 1 : -1;
184
+ }
185
+ else {
186
+ const prerelease = compareLists(left.prerelease, right.prerelease);
187
+ if (prerelease !== 0)
188
+ return prerelease;
189
+ }
190
+ if (left.build === undefined || right.build === undefined) {
191
+ return left.build === right.build ? 0 : left.build === undefined ? -1 : 1;
192
+ }
193
+ return left.build[0] - right.build[0] || compareParts(left.build[1], right.build[1]);
194
+ }
195
+ const REMOVING = '.removing-';
196
+ /** The ways a file can spell a folder: as given, by its real path, and each as a single-quoted shell word quotes it. */
197
+ function spellingsOf(dir) {
198
+ const names = [dir];
199
+ bestEffort(() => {
200
+ names.push(fs.realpathSync(dir));
201
+ });
202
+ return [...new Set(names.flatMap(name => [name, name.replaceAll("'", "'\\''")]))];
203
+ }
204
+ function mentions(spellings, texts) {
205
+ return texts.some(text => spellings.some(name => text.includes(`${name}${path.sep}`) || text.endsWith(name)));
206
+ }
207
+ function inUse(dir, texts) {
208
+ return mentions(spellingsOf(dir), texts);
209
+ }
210
+ /** Whether an environment, as ps or /proc shows it, sets a variable to a path inside one of a folder's spellings. */
211
+ function setsInside(environment, variable, spellings) {
212
+ return spellings.some(name => ` ${environment}`.includes(` ${variable}=${name}${path.sep}`));
213
+ }
214
+ /**
215
+ * What the launchers' users keep, with why: what a running process's environment says it launches and what the
216
+ * launcher puts on its PATH, and everything a launcher needs while a process or lane file runs it without naming what it
217
+ * launches. Each process and each file is judged on its own.
218
+ */
219
+ function launched(launchers, commands, files) {
220
+ const needed = new Map();
221
+ for (const launcher of launchers) {
222
+ const name = path.basename(launcher.dir);
223
+ const tool = spellingsOf(launcher.dir);
224
+ const launches = launcher.launches.map(dir => ({ dir, spellings: spellingsOf(dir) }));
225
+ const names = (texts) => launches.some(launch => mentions(launch.spellings, texts));
226
+ let unnamed = files.some(file => mentions(tool, file) && !names(file));
227
+ for (const command of commands) {
228
+ if (!mentions(tool, [command.args]) || names([command.args]))
229
+ continue;
230
+ const environment = command.environment();
231
+ const chosen = environment === undefined ? [] : launches.filter(launch => setsInside(environment, launcher.variable, launch.spellings));
232
+ if (chosen.length === 0)
233
+ unnamed = true;
234
+ for (const launch of chosen)
235
+ needed.set(launch.dir, `which a running ${name} launches`);
236
+ for (const dir of chosen.length > 0 ? (launcher.onPath ?? []) : [])
237
+ needed.set(dir, `which a running ${name} may run from PATH`);
238
+ }
239
+ if (unnamed)
240
+ for (const dir of launcher.needs)
241
+ needed.set(dir, `which ${name} may run`);
242
+ }
243
+ return needed;
244
+ }
245
+ /** Folders a removal was interrupted in, under the folders the versions sit in. */
246
+ function sweepInterrupted(parents) {
247
+ for (const parent of parents) {
248
+ let names;
249
+ try {
250
+ names = fs.readdirSync(parent);
251
+ }
252
+ catch {
253
+ continue;
254
+ }
255
+ for (const name of names.filter(n => n.startsWith(REMOVING))) {
256
+ bestEffort(() => {
257
+ fs.rmSync(path.join(parent, name), { recursive: true, force: true });
258
+ });
259
+ }
260
+ }
261
+ }
262
+ function lockFor(lock, options) {
263
+ try {
264
+ return tryLock(lock, options.me, options.processes).acquired;
265
+ }
266
+ catch {
267
+ return false;
268
+ }
269
+ }
270
+ export function realOrResolved(file) {
271
+ try {
272
+ return fs.realpathSync(file);
273
+ }
274
+ catch {
275
+ return path.resolve(file);
276
+ }
277
+ }
278
+ function inside(root, dir) {
279
+ return [
280
+ [path.resolve(root), path.resolve(dir)],
281
+ [realOrResolved(root), realOrResolved(dir)],
282
+ ].every(([r = '', d = '']) => {
283
+ const relative = path.relative(r, d);
284
+ return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
285
+ });
286
+ }
287
+ /**
288
+ * Removes the older versions that no running process names on its command line, no recorded lane's files name,
289
+ * no other process is installing, no kept version needs, no launcher may run and no folder that stays holds. Returns the
290
+ * folders removed.
291
+ */
292
+ export function removeOlderVersions(candidates, options) {
293
+ if (candidates.length === 0)
294
+ return [];
295
+ const { root } = options;
296
+ if (root === undefined) {
297
+ options.log(`kept ${candidates.map(v => v.dir).join(', ')}: neither HOME nor XDG_DATA_HOME is set`);
298
+ return [];
299
+ }
300
+ const older = candidates.filter(version => inside(root, version.dir));
301
+ sweepInterrupted(new Set(older.map(version => path.dirname(version.dir))));
302
+ if (older.length === 0)
303
+ return [];
304
+ const commands = options.commandLines();
305
+ if (commands === undefined) {
306
+ options.log(`kept ${older.map(v => v.dir).join(', ')}: ps could not say whether a running process uses them`);
307
+ return [];
308
+ }
309
+ const lanes = options.laneTools();
310
+ if (lanes === undefined) {
311
+ options.log(`kept ${older.map(v => v.dir).join(', ')}: a registry could not say whether a lane uses them`);
312
+ return [];
313
+ }
314
+ const needed = launched(options.launchers ?? [], commands, lanes);
315
+ const neededBy = (version) => {
316
+ for (const dir of version.needs ?? [])
317
+ needed.set(dir, 'which a kept version runs');
318
+ };
319
+ const keep = (version, why) => {
320
+ neededBy(version);
321
+ options.log(`kept ${version.dir}, ${why}`);
322
+ };
323
+ const commandTexts = commands.map(command => command.args);
324
+ const laneTexts = lanes.flat();
325
+ const removed = [];
326
+ const remove = (version) => {
327
+ if (version.lock !== undefined && !lockFor(version.lock, options)) {
328
+ keep(version, 'which another process is installing');
329
+ return;
330
+ }
331
+ const aside = path.join(path.dirname(version.dir), `${REMOVING}${path.basename(version.dir)}-${String(process.pid)}`);
332
+ const moved = bestEffort(() => {
333
+ fs.renameSync(version.dir, aside);
334
+ });
335
+ if (version.lock !== undefined)
336
+ unlock(version.lock, options.me);
337
+ if (!moved) {
338
+ neededBy(version);
339
+ return;
340
+ }
341
+ bestEffort(() => {
342
+ fs.rmSync(aside, { recursive: true, force: true });
343
+ });
344
+ removed.push(version.dir);
345
+ options.log(`removed ${version.dir}, which this version supersedes`);
346
+ };
347
+ const held = [];
348
+ for (const version of [...older.filter(v => v.needs), ...older.filter(v => !v.needs)]) {
349
+ const why = needed.get(version.dir);
350
+ if (why !== undefined) {
351
+ options.log(`kept ${version.dir}, ${why}`);
352
+ continue;
353
+ }
354
+ if (inUse(version.dir, commandTexts)) {
355
+ keep(version, 'which a running process uses');
356
+ continue;
357
+ }
358
+ if (inUse(version.dir, laneTexts)) {
359
+ keep(version, 'which a lane that is up runs');
360
+ continue;
361
+ }
362
+ if ((version.heldBy ?? []).length > 0)
363
+ held.push(version);
364
+ else
365
+ remove(version);
366
+ }
367
+ for (const version of held) {
368
+ const why = needed.get(version.dir);
369
+ const holder = version.heldBy?.find(dir => fs.existsSync(dir));
370
+ if (why !== undefined)
371
+ options.log(`kept ${version.dir}, ${why}`);
372
+ else if (holder !== undefined)
373
+ options.log(`kept ${version.dir}, since ${holder} stays`);
374
+ else
375
+ remove(version);
376
+ }
377
+ return removed;
378
+ }