@agentage/cli 0.39.0 → 0.40.0

package/dist/commands/extension/setup.js

@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs';
+import { loadMachine, setProfileSource } from '../../core/profile/machine.js';
+import { keepMachine } from '../../core/profile/merge.js';
+import { defaultProfile, mutateProfile, parseProfileText, readProfile, } from '../../core/profile/profile.js';
+import {} from '../../core/profile/schema.js';
+import {} from '../auth/setup.js';
+import { installAndLoad } from './install-load.js';
+import { runSetupLatest } from './latest.js';
+import { printDryRun, runSetupCheck } from './plan.js';
+import { printWarnings } from './row-lines.js';
+import { accountSetup, disconnect } from './setup-cloud.js';
+import {} from './sync.js';
+const sourceOf = (label, parsed) => {
+    if (!parsed.ok)
+        throw new Error(`${label} is invalid:\n${parsed.errors.map((e) => `  ${e}`).join('\n')}`);
+    return { profile: parsed.profile, warnings: parsed.warnings };
+};
+const fileSource = (file) => {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(file))
+        throw new Error(`${file}: profile URLs are not supported; pass a file path`);
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        throw new Error(`cannot read profile ${file}: ${err.message}`);
+    }
+    return sourceOf(file, parseProfileText(raw));
+};
+// For --check and --dry-run: the local profile.json, else the built-in default.
+const localSource = () => {
+    const parsed = readProfile();
+    if (parsed !== null)
+        return sourceOf('profile.json', parsed);
+    return { profile: defaultProfile(), warnings: [] };
+};
+// --check and --dry-run read only and never sign in.
+const readOnly = (source, opts) => {
+    printWarnings(source.warnings);
+    if (opts.check)
+        runSetupCheck(source.profile, opts);
+    else
+        printDryRun(source.profile, opts);
+};
+// `--profile` never signs in nor calls the account; this machine's own entry is kept.
+const fromFile = async (source, deps) => {
+    const machine = await loadMachine();
+    await mutateProfile((current) => keepMachine(source.profile, current, machine.id));
+    await setProfileSource('file');
+    await installAndLoad(source.profile, deps.npm);
+};
+export const runExtensionSetup = async (opts, deps) => {
+    if (opts.disconnect)
+        return disconnect(deps);
+    const file = opts.profile === undefined ? null : fileSource(opts.profile);
+    if (opts.check || opts.dryRun)
+        return readOnly(file ?? localSource(), opts);
+    if (file)
+        return fromFile(file, deps);
+    if (opts.latest)
+        return runSetupLatest(deps);
+    await deps.ensureSignedIn({ reauth: opts.reauth, browser: opts.browser });
+    const token = process.env['AGENTAGE_TOKEN'];
+    const failure = await accountSetup(deps).then(() => null, (error) => error);
+    await deps.printStatus({ token });
+    if (failure)
+        throw failure;
+};

package/dist/commands/extension/sync.d.ts

@@ -0,0 +1,22 @@
+import { type Npm } from '../../core/installer/npm.js';
+import { type Account, type CloudFetch, type CloudProfile } from '../../core/profile/cloud.js';
+import { type MachineFile } from '../../core/profile/machine.js';
+import { type Apply, type LockPair, type Pushed, type ReplayOptions } from '../../core/profile/push.js';
+import { type Profile } from '../../core/profile/schema.js';
+import { type AccountOf } from './account.js';
+export interface EditDeps {
+    npm: () => Promise<Npm>;
+    npmMajor: () => Promise<number>;
+    account: AccountOf;
+}
+export type Change = (profile: Profile) => Profile;
+export interface Synced {
+    fetch: CloudFetch;
+    base: CloudProfile;
+}
+export declare const checkAccount: (account: Account, machine: MachineFile) => Promise<string | null>;
+export declare const pullForEdit: (deps: EditDeps) => Promise<Synced | null>;
+export declare const localLock: (deps: EditDeps) => Promise<LockPair>;
+export declare const applying: (change: Change, deps: EditDeps, note?: string | null) => Apply;
+export declare const pushApplied: (synced: Synced, apply: Apply, opts?: ReplayOptions) => Promise<Pushed>;
+export declare const finishEdit: (synced: Synced | null, change: Change, deps: EditDeps, note?: string | null) => Promise<void>;

package/dist/commands/extension/sync.js

@@ -0,0 +1,81 @@
+import { join } from 'node:path';
+import { parseLock } from '../../core/installer/compare-lock.js';
+import {} from '../../core/installer/npm.js';
+import { LOCK_FILE, readText } from '../../core/installer/tree.js';
+import { extensionsDir } from '../../core/paths.js';
+import { localProfile, NotPushedError, pullProfile, } from '../../core/profile/cloud.js';
+import { changeProfile } from '../../core/profile/edit.js';
+import { accountMismatch, loadMachine, setCloud, } from '../../core/profile/machine.js';
+import { editableProfile, mutateProfile } from '../../core/profile/profile.js';
+import { pushBody, pushWithReplay, } from '../../core/profile/push.js';
+import {} from '../../core/profile/schema.js';
+import {} from './account.js';
+import { installAndLoad, line } from './install-load.js';
+const NOT_SIGNED_IN = 'not signed in - run: agentage setup (this machine syncs its profile with your account)';
+const REPLAY = 'changed in your account meanwhile, replaying this change on it';
+// The signed-in account's id, refused when this machine is connected to another account.
+export const checkAccount = async (account, machine) => {
+    const userId = await account.id();
+    const mismatch = accountMismatch(machine, userId);
+    if (mismatch)
+        throw mismatch;
+    return userId;
+};
+// Pulled whole, before anything changes, so the edit applies to the account's newest document.
+export const pullForEdit = async (deps) => {
+    const machine = await loadMachine();
+    if (machine.profileSource !== 'cloud')
+        return null;
+    const account = deps.account();
+    if (account === null)
+        throw new Error(NOT_SIGNED_IN);
+    await checkAccount(account, machine);
+    const pulled = await pullProfile(account.fetch, null);
+    if (pulled.kind === 'unavailable')
+        throw new Error(`cloud profile unavailable (${pulled.reason}); nothing changed`);
+    const base = pulled.kind === 'found' ? pulled.doc : localProfile(editableProfile());
+    return { fetch: account.fetch, base };
+};
+// extensions/package-lock.json and the npm major that wrote it, pushed with the profile.
+export const localLock = async (deps) => {
+    const lock = parseLock(readText(join(extensionsDir(), LOCK_FILE)));
+    return { lock, npmMajor: lock === null ? null : await deps.npmMajor() };
+};
+// Nothing is pushed unless the new tree installed and loaded: installAndLoad throws otherwise.
+export const applying = (change, deps, note = null) => {
+    let calls = 0;
+    return async (base) => {
+        const next = change(base.profile);
+        await mutateProfile(() => next);
+        const text = calls++ === 0 ? note : line('profile', REPLAY);
+        if (text !== null)
+            console.log(text);
+        await installAndLoad({ ...next, lock: base.lock }, deps.npm);
+        return pushBody(next, base, await localLock(deps));
+    };
+};
+const onThisMachine = async (change, deps, note) => {
+    await changeProfile(change);
+    if (note !== null)
+        console.log(note);
+    await installAndLoad(editableProfile(), deps.npm);
+};
+const installedHere = (err) => {
+    if (!(err instanceof NotPushedError))
+        throw err;
+    throw new Error(`${err.message}; installed here only, run the command again to push it`);
+};
+// `apply` installs and loads before it returns the body: a failed load pushes nothing.
+export const pushApplied = async (synced, apply, opts = {}) => {
+    const done = await pushWithReplay(synced.fetch, synced.base, apply, opts).catch(installedHere);
+    await setCloud(done.etag);
+    return done;
+};
+// install, remove and --off end here; the account gets the change only after the tree loaded.
+export const finishEdit = async (synced, change, deps, note = null) => {
+    if (synced === null)
+        return onThisMachine(change, deps, note);
+    const done = await pushApplied(synced, applying(change, deps, note));
+    const where = done.pushed ? 'pushed to' : 'already in';
+    console.log(line('profile', `${where} your account (etag ${done.etag})`));
+};

package/dist/commands/status/account-status.d.ts

@@ -0,0 +1,3 @@
+import { type Account } from '../../core/profile/cloud.js';
+import { type ExtensionsGather } from '../extension/rows.js';
+export declare const gatherWithAccount: (account: Account | null) => Promise<ExtensionsGather>;

package/dist/commands/status/account-status.js

@@ -0,0 +1,27 @@
+import { pullProfile } from '../../core/profile/cloud.js';
+import { seenMachine } from '../../core/profile/register.js';
+import { gatherExtensions } from '../extension/rows.js';
+const STATUS_TIMEOUT_MS = 2_000;
+// The account's profile when it moved past the local copy; null when the same or not known.
+const accountProfile = async (fetch, profile) => {
+    if (profile.state !== 'ok' || profile.etag === null)
+        return null;
+    const pulled = await pullProfile(fetch, profile.etag, STATUS_TIMEOUT_MS);
+    if (pulled.kind !== 'found')
+        return null;
+    return { version: pulled.doc.profile.version, etag: pulled.doc.etag };
+};
+// `status`: marks this machine seen (does the account know it?) and compares the profile copies.
+export const gatherWithAccount = async (account) => {
+    const gathered = await gatherExtensions();
+    const { machine, profile } = gathered.status;
+    const [registered, cloud] = account === null
+        ? [null, null]
+        : await Promise.all([
+            seenMachine(account.fetch, machine.id),
+            accountProfile(account.fetch, profile),
+        ]);
+    const compared = cloud !== null && profile.state === 'ok' ? { ...profile, cloud } : profile;
+    const status = { ...gathered.status, machine: { ...machine, registered }, profile: compared };
+    return { ...gathered, status };
+};

package/dist/commands/status/status.d.ts

@@ -1,6 +1,6 @@
 import { type Command } from 'commander';
 import { type StatusReport } from '../../lib/status/status-info.js';
-import { type PluginsGather } from '../plugins/status-rows.js';
+import { type ExtensionsGather } from '../extension/rows.js';
 export declare const printStatus: (report: StatusReport) => void;
 export interface StatusOptions {
     json?: boolean;
@@ -8,7 +8,8 @@ export interface StatusOptions {
 }
 export interface StatusDeps {
     gather: (opts: StatusOptions) => Promise<StatusReport>;
-    plugins: () => Promise<PluginsGather | null>;
+    extensions: (opts: StatusOptions) => Promise<ExtensionsGather>;
 }
+export declare const statusDeps: (account?: boolean) => StatusDeps;
 export declare const runStatus: (opts?: StatusOptions, deps?: StatusDeps) => Promise<void>;
 export declare const registerStatus: (program: Command, action: (opts: StatusOptions) => Promise<void>) => void;

package/dist/commands/status/status.js

@@ -1,12 +1,13 @@
 import chalk from 'chalk';
 import {} from 'commander';
-import { pluginsEnabled } from '../../core/flag.js';
 import { resolveAuth } from '../../lib/auth/credentials.js';
 import { siteFqdn } from '../../lib/net/origins.js';
 import { gatherStatus } from '../../lib/status/status-info.js';
 import { INSTALL_HINT } from '../../lib/update/update-check.js';
-import { pluginStatusLines } from '../plugins/status-print.js';
-import { gatherPluginStatus } from '../plugins/status-rows.js';
+import { signedInAccount } from '../extension/account.js';
+import { printWarnings, summaryLines } from '../extension/row-lines.js';
+import { gatherExtensions, invalidProfileError } from '../extension/rows.js';
+import { gatherWithAccount } from './account-status.js';
 const mark = (good) => (good ? chalk.green('✓') : chalk.red('✗'));
 const row = (label, value) => {
     console.log(`${label.padEnd(10)} ${value}`);
@@ -50,60 +51,59 @@ export const printStatus = (report) => {
     if (report.update.message)
         console.log(chalk.yellow(`\n${report.update.message}`));
 };
-const defaultDeps = {
+// `account` false: the report that closes setup, which reached the account already.
+export const statusDeps = (account = true) => ({
     gather: (opts) => gatherStatus(resolveAuth({ token: opts.token }), siteFqdn()),
-    plugins: () => (pluginsEnabled() ? gatherPluginStatus() : Promise.resolve(null)),
-};
-const settle = async (deps) => {
+    extensions: (opts) => account ? gatherWithAccount(signedInAccount({ token: opts.token })) : gatherExtensions(),
+});
+const settle = async (deps, opts) => {
     try {
-        return { gathered: await deps.plugins(), error: null };
+        return { gathered: await deps.extensions(opts), error: null };
     }
     catch (error) {
         return { gathered: null, error };
     }
 };
+// `--json` adds machine, profile, the extension count and the plan after the report's own keys;
+// when the extension side failed, the report alone.
+const jsonOf = (report, gathered) => {
+    if (!gathered)
+        return report;
+    const { machine, profile, extensions, plan } = gathered.status;
+    return { ...report, machine, profile, extensions: extensions.length, plan };
+};
 const emit = (report, gathered, json) => {
-    if (json) {
-        console.log(JSON.stringify(gathered ? { ...report, ...gathered.status } : report, null, 2));
-        return;
-    }
+    if (json)
+        return console.log(JSON.stringify(jsonOf(report, gathered), null, 2));
     printStatus(report);
-    for (const text of gathered ? pluginStatusLines(gathered.status) : [])
+    for (const text of gathered ? summaryLines(gathered.status) : [])
         console.log(text);
 };
-const profileFailure = (gathered) => {
-    const profile = gathered?.status.profile;
-    if (profile?.state !== 'invalid')
-        return null;
-    return new Error(`profile.json is invalid:\n${profile.errors.map((e) => `  ${e}`).join('\n')}`);
-};
-// The report always prints; a plugin-side failure then fails the step (exit 1) on stderr.
-export const runStatus = async (opts = {}, deps = defaultDeps) => {
+// The report always prints; an extension-side failure then fails the step (exit 1) on stderr.
+export const runStatus = async (opts = {}, deps = statusDeps()) => {
     const report = await deps.gather(opts);
-    const { gathered, error } = await settle(deps);
+    const { gathered, error } = await settle(deps, opts);
     emit(report, gathered, opts.json);
-    for (const warning of gathered?.warnings ?? [])
-        console.error(chalk.yellow(`warning: ${warning}`));
+    printWarnings(gathered?.warnings ?? []);
     if (error)
         throw error;
-    const failure = profileFailure(gathered);
+    const failure = gathered && invalidProfileError(gathered.status.profile);
     if (failure)
         throw failure;
 };
-const PLUGINS_HELP = `
-Plugins: one row per plugin in the profile or a dev path: id, state (installed, off,
-blocked, invalid, missing), package, installed version, wanted range, contributed commands,
-the last run from state/<id>.json, and the reason when it cannot load. Plugin code is never
-loaded; the only file written is machine.json.`;
+const EXTENSIONS_HELP = `
+Extensions: adds this machine's id and name (machine.json), the local profile version
+(profile.json) with its source and, for a profile from your account, its etag and the
+account's when that moved on, and the number of extensions, with what setup would change, e.g.
+(1 to add); agentage extension list shows one row per extension. Signed in, it also marks this
+machine seen in your account (--json: machine.registered). Extension code is never loaded; the
+only file written is machine.json.`;
 export const registerStatus = (program, action) => {
-    const command = program
+    program
         .command('status')
-        .description(pluginsEnabled()
-        ? 'Show CLI, account, endpoint, machine, profile, and plugin status'
-        : 'Show CLI, account, and endpoint status')
+        .description('Show CLI, account, endpoint, machine, profile, and extension status')
         .option('--json', 'machine-readable output')
         .option('--token <token>', 'authenticate with a personal access token (aga_...); or set AGENTAGE_TOKEN')
+        .addHelpText('after', EXTENSIONS_HELP)
         .action(action);
-    if (pluginsEnabled())
-        command.addHelpText('after', PLUGINS_HELP);
 };

package/dist/core/installer/compare-lock.d.ts

@@ -0,0 +1,8 @@
+type Doc = Record<string, unknown>;
+export declare const parseLock: (raw: string | null) => Doc | null;
+export declare const lockEntries: (lock: Doc) => string[];
+export declare const rootDependencies: (lock: Doc) => Record<string, string>;
+export declare const lockedVersion: (lock: Doc | null, name: string) => string | null;
+export declare const lockAgrees: (lock: Doc, dependencies: Record<string, string>) => boolean;
+export declare const integrityDrift: (a: Doc, b: Doc) => string[];
+export {};

package/dist/core/installer/compare-lock.js

@@ -0,0 +1,51 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+const NODE_MODULES = 'node_modules/';
+const text = (value) => (typeof value === 'string' ? value : '');
+export const parseLock = (raw) => {
+    if (raw === null)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return isRecord(value) && isRecord(value['packages']) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const packagesOf = (lock) => (isRecord(lock['packages']) ? lock['packages'] : {});
+// Nested and hoisted copies are the same package: only the name after the last node_modules/.
+const nameAt = (path, entry) => {
+    const name = text(entry['name']) || path.slice(path.lastIndexOf(NODE_MODULES) + NODE_MODULES.length);
+    return `${name}@${text(entry['version'])}`;
+};
+const entryKey = (path, entry) => `${nameAt(path, entry)}+${text(entry['integrity'])}`;
+const installed = (lock) => Object.entries(packagesOf(lock)).filter((pair) => pair[0] !== '' && isRecord(pair[1]));
+// `resolved`, key order and the npm major's layout choices never reach the set.
+export const lockEntries = (lock) => [...new Set(installed(lock).map(([path, entry]) => entryKey(path, entry)))].sort();
+// What package.json asked npm for when it wrote this lock: name -> range or URL.
+export const rootDependencies = (lock) => {
+    const root = packagesOf(lock)[''];
+    const deps = isRecord(root) && isRecord(root['dependencies']) ? root['dependencies'] : {};
+    return Object.fromEntries(Object.entries(deps).map(([name, spec]) => [name, text(spec)]));
+};
+// The version the lock installed for a root dependency; null when it has none.
+export const lockedVersion = (lock, name) => {
+    const entry = lock === null ? null : packagesOf(lock)[`${NODE_MODULES}${name}`];
+    return isRecord(entry) && typeof entry['version'] === 'string' ? entry['version'] : null;
+};
+// npm ci refuses a lock whose root dependencies differ from package.json.
+export const lockAgrees = (lock, dependencies) => {
+    const locked = rootDependencies(lock);
+    const names = Object.keys(dependencies);
+    return (Object.keys(locked).length === names.length &&
+        names.every((name) => locked[name] === dependencies[name]));
+};
+const integrities = (lock) => new Map(installed(lock).map(([path, entry]) => [nameAt(path, entry), text(entry['integrity'])]));
+// The same name@version with another integrity: one of the two locks was changed by hand.
+export const integrityDrift = (a, b) => {
+    const theirs = integrities(b);
+    return [...integrities(a)]
+        .filter(([key, sri]) => theirs.has(key) && theirs.get(key) !== sri)
+        .map(([key]) => key)
+        .sort();
+};

package/dist/core/installer/compat.d.ts

@@ -0,0 +1,12 @@
+export interface Published {
+    version: string;
+    engine: string;
+}
+export interface Compatible {
+    version: string | null;
+    skipped: Published[];
+}
+export declare const fitsApi: (engine: string, api?: string) => boolean;
+export declare const needs: ({ version, engine }: Published) => string;
+export declare const newestCompatible: (published: Published[], api?: string) => Compatible;
+export declare const parsePublished: (stdout: string) => Published[] | null;

package/dist/core/installer/compat.js

@@ -0,0 +1,35 @@
+import { EXTENSION_API_VERSION } from '../../extension.js';
+import { isRecord } from '../../lib/fs/json-file.js';
+import { manifestInfo } from '../loader/manifest.js';
+import { isRange, newestFirst, satisfies } from '../semver-range.js';
+export const fitsApi = (engine, api = EXTENSION_API_VERSION) => isRange(engine) && satisfies(api, engine);
+export const needs = ({ version, engine }) => `${version}: needs extension API ${engine}`;
+// The resolver's rule: the newest version this CLI can load, instead of whatever `latest` is.
+export const newestCompatible = (published, api = EXTENSION_API_VERSION) => {
+    const sorted = [...published].sort((a, b) => newestFirst(a.version, b.version));
+    const at = sorted.findIndex((p) => fitsApi(p.engine, api));
+    if (at === -1)
+        return { version: null, skipped: sorted };
+    return { version: sorted[at]?.version ?? null, skipped: sorted.slice(0, at) };
+};
+const publishedOf = (item) => {
+    if (typeof item === 'string')
+        return { version: item, engine: manifestInfo({}).engine };
+    if (!isRecord(item) || typeof item['version'] !== 'string')
+        return null;
+    return { version: item['version'], engine: manifestInfo(item).engine };
+};
+// npm view prints one object per version, a lone object for one version, or bare versions.
+export const parsePublished = (stdout) => {
+    if (stdout.trim() === '')
+        return [];
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const items = (Array.isArray(value) ? value : [value]).map(publishedOf);
+    return items.every((p) => p !== null) ? items : null;
+};

package/dist/core/installer/installer.d.ts

@@ -0,0 +1,28 @@
+import { type Profile } from '../profile/schema.js';
+import { type Npm, type NpmCommand } from './npm.js';
+import { type TreeFiles } from './tree.js';
+export type InstallSet = Pick<Profile, 'extensions' | 'registries'> & {
+    lock?: Record<string, unknown> | null;
+};
+export interface InstallPlan extends TreeFiles {
+    extensionsDir: string;
+    install: Record<string, string>;
+    registries: Record<string, string>;
+    npm: NpmCommand | null;
+    tree: string | null;
+    reuse: boolean;
+}
+export interface InstallResult {
+    tree: string;
+    npm: NpmCommand | null;
+    reused: boolean;
+    count: number;
+}
+export declare const planInstall: (set: InstallSet) => InstallPlan;
+export declare const lastLines: (output: string, count?: number) => string;
+export declare const runNpmInto: (staging: string, command: NpmCommand, npm: Npm, packages?: string[]) => Promise<{
+    tree: string;
+    lock: string;
+}>;
+export declare const refuseDrift: (dir: string) => void;
+export declare const install: (set: InstallSet, prepare?: () => Promise<Npm>) => Promise<InstallResult>;

package/dist/core/installer/installer.js

@@ -0,0 +1,87 @@
+import { join } from 'node:path';
+import {} from '../../lib/npm/npm-cli.js';
+import { extensionsDir } from '../paths.js';
+import {} from '../profile/schema.js';
+import { lockAgrees, lockEntries, parseLock } from './compare-lock.js';
+import { prepareNpm } from './npm.js';
+import { driftLines, lockDrift } from './plan.js';
+import { clearStaging, collectTrees, commitTree, discardTree, isComplete, LOCK_FILE, manifestText, npmrcText, pointCurrent, promoteFiles, readText, sortedSet, stageTree, treeName, withInstallLock, } from './tree.js';
+// The current lock rides into the staged tree, so npm keeps every pin it can.
+const lockPlan = (dir, install, raw) => {
+    if (Object.keys(install).length === 0) {
+        const tree = treeName([]);
+        return { lock: null, npm: null, tree, reuse: isComplete(dir, tree) };
+    }
+    const lock = parseLock(raw);
+    if (lock === null)
+        return { lock: null, npm: 'install', tree: null, reuse: false };
+    if (!lockAgrees(lock, install))
+        return { lock: raw, npm: 'install', tree: null, reuse: false };
+    const tree = treeName(lockEntries(lock));
+    const reuse = isComplete(dir, tree);
+    return { lock: raw, npm: reuse ? null : 'ci', tree, reuse };
+};
+// Reads only: `setup --dry-run` prints this and stops.
+export const planInstall = (set) => {
+    const dir = extensionsDir();
+    const install = sortedSet(set.extensions);
+    const registries = sortedSet(set.registries);
+    const files = { manifest: manifestText(install), npmrc: npmrcText(registries) };
+    const raw = set.lock ? `${JSON.stringify(set.lock, null, 2)}\n` : readText(join(dir, LOCK_FILE));
+    const lock = lockPlan(dir, install, raw);
+    return { extensionsDir: dir, install, registries, ...files, ...lock };
+};
+// npm's last lines, enough to see why it failed.
+export const lastLines = (output, count = 20) => output
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '')
+    .slice(-count)
+    .join('\n');
+const npmFailure = (command, res) => new Error(`npm ${command} failed (exit ${res.code}); extensions/current is unchanged\n` +
+    lastLines(`${res.stdout}\n${res.stderr}`));
+// The staged tree's name and lock text, once npm succeeded in it; `packages` limits an update.
+export const runNpmInto = async (staging, command, npm, packages = []) => {
+    const res = await npm(command, staging, packages);
+    if (res.code !== 0)
+        throw npmFailure(command, res);
+    const lock = readText(join(staging, LOCK_FILE));
+    const parsed = parseLock(lock);
+    if (lock === null || parsed === null)
+        throw new Error(`npm ${command} wrote no usable ${LOCK_FILE}`);
+    return { tree: treeName(lockEntries(parsed)), lock };
+};
+const build = async (plan, prepare) => {
+    const npm = plan.npm === null ? null : await prepare();
+    const staging = stageTree(plan.extensionsDir, plan);
+    try {
+        const built = npm === null || plan.npm === null
+            ? { tree: treeName([]), lock: null }
+            : await runNpmInto(staging, plan.npm, npm);
+        commitTree(plan.extensionsDir, staging, built.tree);
+        return built;
+    }
+    catch (err) {
+        discardTree(staging);
+        throw err;
+    }
+};
+// A lock that disagrees with its own tree on a package's bytes is never built on.
+export const refuseDrift = (dir) => {
+    const { integrity } = lockDrift(dir);
+    if (integrity.length > 0)
+        throw new Error(driftLines(integrity).join('\n'));
+};
+const execute = async (plan, prepare) => {
+    refuseDrift(plan.extensionsDir);
+    clearStaging(plan.extensionsDir);
+    const built = plan.reuse && plan.tree !== null
+        ? { tree: plan.tree, lock: plan.lock }
+        : await build(plan, prepare);
+    pointCurrent(plan.extensionsDir, built.tree);
+    promoteFiles(plan.extensionsDir, { manifest: plan.manifest, lock: built.lock });
+    collectTrees(plan.extensionsDir, built.tree);
+    const count = Object.keys(plan.install).length;
+    return { tree: built.tree, npm: plan.npm, reused: plan.reuse, count };
+};
+// Plans again under the lock: a run that waited sees the tree the first one built.
+export const install = async (set, prepare = prepareNpm) => withInstallLock(extensionsDir(), () => execute(planInstall(set), prepare));

package/dist/core/installer/latest.d.ts

@@ -0,0 +1,26 @@
+import { type InstallSet } from './installer.js';
+import { type Npm } from './npm.js';
+export interface VersionChange {
+    name: string;
+    from: string | null;
+    to: string | null;
+}
+export interface Held {
+    name: string;
+    version: string;
+    newer: string;
+    engine: string;
+}
+export interface LatestResult {
+    changes: VersionChange[];
+    held: Held[];
+    unchanged: number;
+    tree: string | null;
+    current: boolean;
+}
+export type Staged = Omit<LatestResult, 'tree' | 'current'> & {
+    tree: string;
+    dir: string;
+};
+export type Check = (staged: Staged) => Promise<boolean>;
+export declare const updateLatest: (set: InstallSet, prepare: () => Promise<Npm>, check: Check) => Promise<LatestResult>;