@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/builds/gc.js

@@ -0,0 +1,245 @@
+/**
+ * Adapter build GC (spec 2026-10-11 §6.3 "GC", analysis D §2.4; Task 24).
+ *
+ * A build is collected only when every one of these holds:
+ *
+ * 1. it is not any agent's `current` build;
+ * 2. no adapter process references it — every keeper-acp generation that runs is listed (spawn labels carry `agentId`/`buildId`),
+ *    and the local fallback's processes too; a keeper-acp that cannot be listed means **no GC at all** (nothing proves the build is
+ *    unused);
+ * 3. the daemon holds no lease on it (an open between resolving and spawning, a switch — both its builds —, a short-lived
+ *    connection: those count as "seen" until they can no longer run);
+ * 4. it was last referenced more than {@link BUILD_GC_GRACE_MS} ago (a build never seen referenced in this daemon's life counts
+ *    from the daemon's start; the build the pointer left counts from the move);
+ * 5. it is not the agent's one rollback build (the `previous` pointer, else the newest other build).
+ *
+ * Each agent is collected under its agent lock (install / switch / GC are serialised per agent). A record is removed from
+ * `builds.json` first, then its tree goes to `.trash/` — and only when no remaining record of any agent shares it (npm version
+ * directories can be shared; a version directory goes once nothing of it is recorded).
+ *
+ * ## What an older CLI left ({@link collectLegacy})
+ *
+ * The 15c binary migration left a symlink at each old `acp-adapters/<agent>/<version>` path; the pre-build patcher left
+ * `acp-adapters/patched-npm/`; a legacy version directory that could not be moved stays where it was. They are removed only when
+ * nothing references them: no build record points inside them and no running process's command line names them (the processes an
+ * older CLI started) — and a legacy version directory only once its agent has a build of its own (its migration ran). Symlinks are removed with `lstat` + `unlink` — never followed; directories go through `.trash/` (a rename moves
+ * the directory entry itself). `~/.npm/_npx` is npm's, never touched.
+ */
+import { execFile } from 'node:child_process';
+import { lstat, readdir, rmdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { processCommand } from '../../keepers/kit/lock.js';
+import { RESERVED_ROOT_NAMES } from './migrate.js';
+import { inside } from './model.js';
+/** Spec §14: a build last referenced this long ago may go (one rollback build is kept per agent). */
+export const BUILD_GC_GRACE_MS = 10 * 60_000;
+export const buildKey = (agentId, buildId) => `${agentId}\u0000${buildId}`;
+/** The rollback build GC keeps for an agent: the one its pointer left, else the most recently installed other one. */
+export function rollbackBuildOf(entry) {
+    if (entry.previous !== undefined && entry.previous !== entry.current && Object.hasOwn(entry.builds, entry.previous))
+        return entry.previous;
+    const others = Object.values(entry.builds).filter((build) => build.buildId !== entry.current)
+        .sort((a, b) => (a.installedAt < b.installedAt ? 1 : a.installedAt > b.installedAt ? -1 : 0));
+    return others[0]?.buildId;
+}
+/** The directory that goes with a removed record once nothing else is recorded inside it: an npm build's whole version directory. */
+function ownedDirOf(build) {
+    if (build.kind === 'npm' || build.kind === 'npm-patched') {
+        const parts = build.dir.split('/');
+        // npm/<sha16>/<version>/(pristine | patched/<digest>)
+        if (parts[0] === 'npm' && parts.length >= 4)
+            return parts.slice(0, 3).join('/');
+    }
+    return build.dir;
+}
+const within = (dir, candidate) => candidate === dir || candidate.startsWith(`${dir}/`);
+export async function collectBuilds(inputs) {
+    const { store, now } = inputs;
+    const grace = inputs.graceMs ?? BUILD_GC_GRACE_MS;
+    const log = inputs.log ?? ((line) => console.info(line));
+    const report = { removed: [], discarded: [], kept: [], legacyRemoved: [] };
+    if (inputs.running === undefined)
+        return { ...report, skipped: 'keeper-acp could not be listed' };
+    const running = new Set(inputs.running.map((ref) => buildKey(ref.agentId, ref.buildId)));
+    const leased = new Set(inputs.leased.map((ref) => buildKey(ref.agentId, ref.buildId)));
+    const seen = (key) => inputs.lastSeen.get(key) ?? inputs.seenByDefault;
+    for (const agentId of Object.keys((await store.read()).agents)) {
+        await store.withAgentLock(agentId, async () => {
+            const entry = (await store.read()).agents[agentId];
+            if (!entry)
+                return;
+            const rollback = rollbackBuildOf(entry);
+            const collectable = [];
+            for (const build of Object.values(entry.builds)) {
+                const key = buildKey(agentId, build.buildId);
+                // The build the pointer left was referenced (as current) until the move.
+                if (build.buildId === entry.previous && entry.currentSetAt) {
+                    const movedAt = Date.parse(entry.currentSetAt);
+                    if (Number.isFinite(movedAt) && movedAt > seen(key))
+                        inputs.lastSeen.set(key, movedAt);
+                }
+                let why;
+                if (build.buildId === entry.current)
+                    why = 'current';
+                else if (running.has(key))
+                    why = 'running';
+                else if (leased.has(key))
+                    why = 'leased';
+                if (why !== undefined) {
+                    inputs.lastSeen.set(key, Math.max(now, seen(key)));
+                    report.kept.push({ agentId, buildId: build.buildId, why });
+                    continue;
+                }
+                if (now - seen(key) < grace) {
+                    report.kept.push({ agentId, buildId: build.buildId, why: 'grace' });
+                    continue;
+                }
+                if (build.buildId === rollback) {
+                    report.kept.push({ agentId, buildId: build.buildId, why: 'rollback' });
+                    continue;
+                }
+                collectable.push(build.buildId);
+            }
+            if (collectable.length === 0)
+                return;
+            const removed = await store.removeBuilds(agentId, collectable);
+            const remaining = Object.values((await store.read()).agents).flatMap((agent) => Object.values(agent.builds).map((build) => build.dir));
+            for (const build of removed) {
+                report.removed.push({ agentId, buildId: build.buildId, dir: build.dir });
+                inputs.lastSeen.delete(buildKey(agentId, build.buildId));
+                for (const dir of new Set([build.dir, ownedDirOf(build)])) {
+                    if (remaining.some((other) => within(dir, other) || within(other, dir)))
+                        continue;
+                    const discard = () => store.discard(inside(store.root, dir));
+                    if (build.kind === 'uv')
+                        await store.withTreeLock(dir, discard);
+                    else
+                        await discard();
+                    report.discarded.push(dir);
+                }
+                await removeIfEmpty(path.dirname(inside(store.root, build.dir)), store.root);
+            }
+            log(`[acp-builds] GC: removed ${removed.map((build) => `${agentId} ${build.buildId}`).join(', ')}`);
+        });
+    }
+    return report;
+}
+/** Removes `dir` (and then its empty parents, up to `root`) while it is empty; never recursive. */
+async function removeIfEmpty(dir, root) {
+    for (let at = dir; at.startsWith(root + path.sep) && at !== root; at = path.dirname(at)) {
+        try {
+            await rmdir(at);
+        }
+        catch {
+            return;
+        }
+    }
+}
+function psCommandLines() {
+    return new Promise((resolve) => {
+        execFile('ps', ['-A', '-o', 'args='], { maxBuffer: 64 * 1024 * 1024, timeout: 10_000 }, (error, stdout) => {
+            resolve(error ? undefined : stdout.split('\n').filter((line) => line.trim() !== ''));
+        });
+    });
+}
+/**
+ * Every running process's command line, for "does anything still run from this path". Linux reads `/proc/<pid>/cmdline` through
+ * the kit's `/proc` check (final review minor 11: container images without `ps` never collected legacy leftovers); elsewhere,
+ * and on a Linux without a readable `/proc`, `ps -A -o args=`. `undefined` where it cannot be read (Windows, neither source):
+ * legacy trees are then left alone.
+ */
+export async function processCommandLines(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform === 'win32')
+        return undefined;
+    if (platform === 'linux') {
+        let entries;
+        try {
+            entries = await (deps.readProc ?? (() => readdir('/proc')))();
+        }
+        catch {
+            entries = undefined;
+        }
+        const pids = (entries ?? []).filter((entry) => /^\d+$/.test(entry)).map(Number);
+        if (pids.length > 0) {
+            const lines = [];
+            for (const pid of pids) {
+                const line = await processCommand(pid, { platform: 'linux', ...(deps.readCmdline ? { readCmdline: deps.readCmdline } : {}) });
+                // '': it ended meanwhile (or a kernel thread); null: not ours to read (another user's) — it cannot run from our 0700 tree.
+                if (line)
+                    lines.push(line);
+            }
+            return lines;
+        }
+    }
+    return (deps.ps ?? psCommandLines)();
+}
+/**
+ * What an older CLI left under the `acp-adapters` root (see the file comment): the 15c legacy links, unmigrated legacy version
+ * directories, and `patched-npm/` — each removed only when no build record points inside it and no running process names it.
+ */
+export async function collectLegacy(options) {
+    const { store, commandLines } = options;
+    const log = options.log ?? ((line) => console.info(line));
+    if (commandLines === undefined)
+        return [];
+    const root = store.root;
+    const document = await store.read();
+    const recorded = Object.values(document.agents).flatMap((agent) => Object.values(agent.builds).map((build) => inside(root, build.dir)));
+    const referenced = (target) => recorded.some((dir) => dir === target || dir.startsWith(target + path.sep)) || commandLines.some((line) => line.includes(target));
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        const at = path.join(root, entry.name);
+        if (entry.name === 'patched-npm') {
+            if (!(await lstat(at)).isDirectory() || referenced(at))
+                continue;
+            await store.discard(at);
+            removed.push(at);
+            continue;
+        }
+        if (entry.name.startsWith('.') || RESERVED_ROOT_NAMES.has(entry.name) || !entry.isDirectory())
+            continue;
+        // `acp-adapters/<agentId>/`: legacy version directories and the links the migration left in their place.
+        let versions;
+        try {
+            versions = await readdir(at, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        // A real legacy version directory is only garbage once the agent has a build of its own (its migration ran, or it was installed
+        // anew): before that it may be the only install of an agent whose migration is still to come.
+        const migrated = document.agents[entry.name]?.current !== undefined;
+        for (const version of versions) {
+            const target = path.join(at, version.name);
+            const stat = await lstat(target).catch(() => undefined);
+            if (!stat || referenced(target))
+                continue;
+            if (stat.isSymbolicLink()) {
+                // Never followed: the link itself goes, whatever it points at.
+                await unlink(target).catch(() => undefined);
+            }
+            else if (stat.isDirectory() && migrated) {
+                await store.discard(target);
+            }
+            else {
+                continue;
+            }
+            removed.push(target);
+        }
+        try {
+            await rmdir(at);
+        }
+        catch { /* not empty: something is still referenced there */ }
+    }
+    if (removed.length > 0)
+        log(`[acp-builds] GC: removed what an older CLI left: ${removed.map((p) => path.relative(root, p)).join(', ')}`);
+    return removed;
+}

package/dist/workstation/acp/builds/install/binary.js

@@ -0,0 +1,28 @@
+/**
+ * Binary-distributed adapters as builds: `binaryInstall.ts` stages and renames the archive into
+ * `bin/<agentId>/<version>/`; this turns that tree into a {@link Build} record.
+ */
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { binaryBuildDir, buildIdFor, inside } from '../model.js';
+export function binaryBuild(options) {
+    const dir = binaryBuildDir(options.agentId, options.version);
+    const entry = path.posix.normalize(options.target.cmd.replace(/\\/g, '/'));
+    if (entry.startsWith('../') || path.posix.isAbsolute(entry))
+        throw new Error(`Adapter command escapes its install: ${options.target.cmd}`);
+    if (!statSync(inside(inside(options.root, dir), entry)).isFile()) {
+        throw new Error(`Agent '${options.agentId}' ${options.version} has no '${options.target.cmd}' in its archive`);
+    }
+    return {
+        buildId: buildIdFor(options.version),
+        agentId: options.agentId,
+        kind: 'binary',
+        version: options.version,
+        dir,
+        launch: { runtime: 'native', entry, args: [...(options.target.args ?? [])], env: { ...options.env } },
+        registryVersion: options.registryVersion,
+        source: options.source,
+        installedBy: options.installedBy,
+        installedAt: (options.now ?? new Date()).toISOString(),
+    };
+}

package/dist/workstation/acp/builds/install/npm.js

@@ -0,0 +1,235 @@
+/**
+ * npm-distributed adapters as daemon-owned builds (spec §6.2): `npm install --prefix <staging>` into a
+ * fresh staging tree, renamed to `npm/<sha16(name)>/<version>/pristine/`; when this CLI has patches for
+ * that version, a copy of pristine is patched into `patched/<digest>/`. Launch then runs the package's
+ * `bin` directly with the daemon's own Node — no npx, no network, nothing resolved at open time.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { open, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createPatchedTree, expectedPatchedFiles, patchDigest, selectPackagePatches, verifyPatchedFiles } from '../../managedPatches.js';
+import { assertSafePackageName, assertSafeVersion, buildIdFor, inside, npmPatchedDir, npmPristineDir, } from '../model.js';
+import { assertBuildRunsOn } from '../nodeGate.js';
+import { publishStaged } from '../store.js';
+/**
+ * The `npm` this daemon installs adapters with: `AXOM_WORKSTATION_NPM_PATH` when set (the service
+ * definition sets it, `workstation/config.ts`), else the one next to its own Node, else whatever `PATH` has.
+ */
+export function defaultNpmCommand(nodePath = process.execPath, platform = process.platform, env = process.env) {
+    const configured = env.AXOM_WORKSTATION_NPM_PATH?.trim();
+    if (configured)
+        return configured;
+    const sibling = path.join(path.dirname(nodePath), platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(sibling) ? sibling : platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+/** `npm view <name> version --json`: the version npm's `latest` names right now, or `undefined` when npm cannot say. */
+export function runNpmViewLatest(npmCommand, name, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile(npmCommand, ['view', name, 'version', '--json'], { timeout: timeoutMs, windowsHide: true }, (error, stdout) => {
+            if (error) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                const parsed = JSON.parse(stdout.toString());
+                resolve(typeof parsed === 'string' && parsed ? parsed : undefined);
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+    });
+}
+/** `npm install --prefix <prefix> --no-save --no-audit --no-fund <spec>`, argv only, never a shell. */
+export function runNpmInstall(npmCommand, prefix, spec, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile(npmCommand, ['install', '--prefix', prefix, '--no-save', '--no-audit', '--no-fund', spec], { timeout: timeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolve({ ok: true });
+                return;
+            }
+            const raw = stderr.toString();
+            const detail = raw.trim().split('\n').slice(-4).join(' ').trim();
+            resolve({ ok: false, error: detail ? `${error.message.split('\n')[0]}: ${detail}` : error.message, stderr: raw });
+        });
+    });
+}
+async function readPackage(packageDir) {
+    try {
+        return JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The installed version of `name` under `<root>/node_modules`, when it is really there. */
+async function installedVersion(treeRoot, name) {
+    const metadata = await readPackage(inside(path.join(treeRoot, 'node_modules'), name));
+    return metadata?.name === name && typeof metadata.version === 'string' ? metadata.version : undefined;
+}
+/**
+ * Make sure `npm/<sha16(name)>/<version>/pristine` exists. `version` undefined = unpinned (npm's
+ * `latest`, the install-time ETARGET fallback): the version is read back off what npm installed.
+ * Caller holds the agent lock.
+ */
+export async function ensurePristine(options) {
+    const { store, name } = options;
+    assertSafePackageName(name);
+    if (options.version === undefined) {
+        // Unpinned (the install-time ETARGET fallback): name the version first, so a `latest` that is
+        // already installed costs one metadata request and no download.
+        const latest = await runNpmViewLatest(options.npmCommand, name, options.timeoutMs);
+        let safe = false;
+        if (latest !== undefined) {
+            try {
+                assertSafeVersion(latest);
+                safe = true;
+            }
+            catch { /* an unusable answer: install unpinned and read the version back */ }
+        }
+        // Only the version check may fall through: a real install failure of `latest` is that failure,
+        // not a reason for a second, unpinned install.
+        if (safe)
+            return ensurePristine({ ...options, version: latest });
+    }
+    if (options.version !== undefined) {
+        const final = inside(store.root, npmPristineDir(name, options.version));
+        if ((await installedVersion(final, name)) === options.version)
+            return { ok: true, version: options.version, downloaded: false };
+    }
+    const staged = await store.stagingDir();
+    try {
+        const spec = options.version === undefined ? name : `${name}@${options.version}`;
+        const ran = await runNpmInstall(options.npmCommand, staged, spec, options.timeoutMs);
+        if (!ran.ok)
+            return ran;
+        const version = await installedVersion(staged, name);
+        if (!version)
+            return { ok: false, error: `npm reported success but ${spec} is not in the installed tree`, stderr: '' };
+        if (options.version !== undefined && version !== options.version) {
+            return { ok: false, error: `npm installed ${name}@${version} when ${spec} was asked for`, stderr: '' };
+        }
+        assertSafeVersion(version);
+        const { published } = await publishStaged(staged, inside(store.root, npmPristineDir(name, version)));
+        // Not published = that version's pristine was already there (we only learned the version now).
+        return { ok: true, version, downloaded: published };
+    }
+    finally {
+        // After a successful publish `staged` no longer exists; after a failure it is half-written.
+        await store.discard(staged);
+    }
+}
+/**
+ * The executable an npm package exposes, by npm's own `npm exec` rule: an explicit verified bin (from a
+ * patch recipe) when given; otherwise the only bin; otherwise the bin named like the package (scope
+ * stripped). Anything else is ambiguous and refused rather than guessed.
+ */
+export function selectBin(name, bin, explicit) {
+    const unscoped = name.includes('/') ? name.slice(name.indexOf('/') + 1) : name;
+    let chosen;
+    if (explicit !== undefined)
+        chosen = typeof bin === 'object' && bin !== null ? bin[explicit] : undefined;
+    else if (typeof bin === 'string')
+        chosen = bin;
+    else if (typeof bin === 'object' && bin !== null) {
+        const entries = Object.entries(bin);
+        chosen = entries.length === 1 ? entries[0][1] : bin[unscoped];
+    }
+    if (typeof chosen !== 'string' || !chosen)
+        throw new Error(`Adapter package ${name} has no unambiguous executable`);
+    return chosen;
+}
+/** `node` unless the entry is evidently not JavaScript (a native executable, or a script for another interpreter). */
+async function runtimeOf(file) {
+    const handle = await open(file, 'r');
+    try {
+        const head = Buffer.alloc(256);
+        const { bytesRead } = await handle.read(head, 0, head.length, 0);
+        const bytes = head.subarray(0, bytesRead);
+        const magic = bytes.length >= 4 ? bytes.readUInt32BE(0) : 0;
+        // ELF, Mach-O (both byte orders, 32/64, fat), PE.
+        if ([0x7f454c46, 0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xcafebabe].includes(magic) || bytes.subarray(0, 2).toString() === 'MZ') {
+            return 'native';
+        }
+        const text = bytes.toString('utf8');
+        if (text.startsWith('#!'))
+            return /\bnode\b/.test(text.split('\n')[0]) ? 'node' : 'native';
+        return 'node';
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * The build for `name@version` from its pristine tree: pristine itself when this CLI has no patch for
+ * that version, else a patched copy (created once, then reused). Not committed — the caller does
+ * that under the agent lock.
+ */
+export async function npmBuild(options) {
+    const { store, name, version } = options;
+    const pristineRel = npmPristineDir(name, version);
+    const pristine = inside(store.root, pristineRel);
+    const recipes = await selectPackagePatches(name, version, inside(path.join(pristine, 'node_modules'), name), options.recipes);
+    let dir = pristineRel;
+    let patch = {};
+    if (recipes.length) {
+        const digest = patchDigest(recipes);
+        dir = npmPatchedDir(name, version, digest);
+        const final = inside(store.root, dir);
+        if (!existsSync(final)) {
+            const staged = await store.stagingDir();
+            try {
+                await createPatchedTree(pristine, staged, name, version, recipes);
+                await publishStaged(staged, final);
+            }
+            finally {
+                await store.discard(staged);
+            }
+        }
+        // Whoever published it, the tree's receipt must be for exactly this recipe set.
+        const receipt = JSON.parse(await readFile(path.join(final, 'axom-patches.json'), 'utf8'));
+        if (receipt.digest !== digest)
+            throw new Error('Axom adapter patch receipt does not match this CLI');
+        // Expected hashes come from the shipped recipes, never from the writable receipt alone.
+        const files = expectedPatchedFiles(recipes);
+        await verifyPatchedFiles(inside(path.join(final, 'node_modules'), name), files);
+        patch = { patchDigest: digest, patches: recipes.map((recipe) => recipe.id), patchedFiles: files };
+    }
+    const root = inside(store.root, dir);
+    const packageRel = `node_modules/${name}`;
+    const metadata = await readPackage(inside(root, packageRel));
+    if (metadata?.name !== name || metadata.version !== version)
+        throw new Error(`Adapter package identity changed under ${dir}`);
+    const explicit = [...new Set(recipes.map((recipe) => recipe.bin).filter((bin) => bin !== undefined))];
+    if (explicit.length > 1)
+        throw new Error('Axom patches disagree about the adapter executable');
+    const entryRel = path.posix.normalize(`${packageRel}/${selectBin(name, metadata.bin, explicit[0])}`);
+    const entry = inside(root, entryRel);
+    if (!entryRel.startsWith(`${packageRel}/`) || !statSync(entry).isFile())
+        throw new Error(`Adapter executable is missing in ${dir}`);
+    const launch = {
+        runtime: await runtimeOf(entry),
+        entry: entryRel,
+        args: [...options.args],
+        env: { ...options.env },
+        pathDirs: ['node_modules/.bin'],
+    };
+    const build = {
+        buildId: buildIdFor(version, patch.patchDigest),
+        agentId: options.agentId,
+        kind: patch.patchDigest ? 'npm-patched' : 'npm',
+        version,
+        package: name,
+        ...patch,
+        dir,
+        launch,
+        registryVersion: options.registryVersion,
+        source: options.source,
+        installedBy: options.installedBy,
+        installedAt: (options.now ?? new Date()).toISOString(),
+    };
+    // Never hand back (so never commit, never make current) a build its own Node gate refuses.
+    await assertBuildRunsOn(build, store.root, options.nodePath);
+    return build;
+}