@agentage/cli 0.38.0 → 0.38.1

package/dist/lib/auth/sign-in.js

@@ -0,0 +1,95 @@
+import chalk from 'chalk';
+import { deleteAuth, ensureConfigDir, mutateAuth, readAuth } from '../fs/config.js';
+import { links, siteFqdn } from '../net/origins.js';
+import { AuthRequiredError } from './auth-errors.js';
+import { startCallbackServer } from './callback-server.js';
+import { detectEnvMismatch } from './env-match.js';
+import { introspectToken } from './introspect.js';
+import { buildAuthorizeUrl, exchangeCode, pkcePair, randomState, registerClient, revokeToken, tokensFrom, } from './oauth.js';
+const defaultDeps = {
+    register: registerClient,
+    exchange: exchangeCode,
+    revoke: revokeToken,
+    startServer: startCallbackServer,
+    openBrowser: async (url) => {
+        const { default: open } = await import('open');
+        await open(url);
+    },
+    introspect: introspectToken,
+    log: (msg) => console.log(msg),
+};
+const promptBrowser = async (url, opts, deps) => {
+    deps.log(`\nSign in to agentage (${siteFqdn()}):\n\n  ${url}\n`);
+    if (opts.browser === false)
+        deps.log('Open the URL above in a browser to continue.');
+    else
+        await deps
+            .openBrowser(url)
+            .catch(() => deps.log('Could not open a browser - use the URL above.'));
+    deps.log('Waiting for sign-in to complete...');
+};
+const authorize = async (server, state, opts, deps) => {
+    const authUrl = links(siteFqdn()).auth;
+    const { verifier, challenge } = pkcePair();
+    const clientId = await deps.register(authUrl, server.redirectUri);
+    const redirectUri = server.redirectUri;
+    const url = buildAuthorizeUrl(authUrl, { clientId, redirectUri, challenge, state });
+    await promptBrowser(url, opts, deps);
+    return { clientId, verifier, code: await server.waitForCode() };
+};
+// A fresh DCR client per run: the redirect URI binds this run's ephemeral callback port.
+export const signIn = async (opts, deps = defaultDeps) => {
+    const fqdn = siteFqdn();
+    ensureConfigDir();
+    const state = randomState();
+    const server = await deps.startServer(state);
+    try {
+        const { clientId, code, verifier } = await authorize(server, state, opts, deps);
+        const redirectUri = server.redirectUri;
+        const res = await deps.exchange(links(fqdn).auth, { clientId, code, redirectUri, verifier });
+        await mutateAuth(() => ({ siteFqdn: fqdn, clientId, tokens: tokensFrom(res) }));
+        deps.log(chalk.green('\nSigned in.\n'));
+    }
+    finally {
+        server.close();
+    }
+};
+export const signOut = async (deps = defaultDeps) => {
+    const auth = readAuth();
+    if (!auth) {
+        deps.log('Nothing to disconnect.');
+        return;
+    }
+    await deps.revoke(links(auth.siteFqdn).auth, auth.tokens.accessToken);
+    await deleteAuth();
+    deps.log('Disconnected - local credentials removed.');
+};
+const mismatchNote = (m) => `Signed in to ${m.credentialFqdn} (${m.credentialEnv}), but this run targets ` +
+    `${m.targetFqdn} (${m.targetEnv}) - signing you into ${m.targetEnv}.\n`;
+// Only a dead session re-signs: a transient verify failure keeps the credentials.
+const verifyStored = async (auth, deps) => {
+    try {
+        await deps.introspect(auth, links(auth.siteFqdn));
+        deps.log(`Already signed in. Run ${chalk.white('agentage setup --reauth')} to sign in again.\n`);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof AuthRequiredError) {
+            deps.log('Session expired - signing you in again.\n');
+            return false;
+        }
+        deps.log('You appear signed in (could not fully verify - temporary).\n');
+        return true;
+    }
+};
+// Never introspect a credential against another environment: it would misread as expired.
+export const ensureSignedIn = async (opts, deps = defaultDeps) => {
+    const stored = readAuth();
+    const mismatch = stored && !opts.reauth ? detectEnvMismatch(stored, siteFqdn()) : null;
+    if (mismatch)
+        deps.log(mismatchNote(mismatch));
+    else if (stored && !opts.reauth && (await verifyStored(stored, deps)))
+        return 'already';
+    await signIn(opts, deps);
+    return mismatch ? 'mismatch-resigned' : 'signed-in';
+};

package/dist/lib/fs/config.d.ts

@@ -15,6 +15,7 @@ export interface AuthState {
 }
 export declare const getConfigDir: () => string;
 export declare const ensureConfigDir: () => string;
+export declare const isAuthState: (value: unknown) => value is AuthState;
 export declare const readAuth: () => AuthState | null;
 export declare const saveAuth: (state: AuthState) => void;
 export declare const deleteAuth: () => Promise<void>;

package/dist/lib/fs/config.js

@@ -1,8 +1,8 @@
-import { randomBytes } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { withFileLock } from './file-lock.js';
+import { isRecord, readJson, writeJsonAtomic } from './json-file.js';
 export const getConfigDir = () => process.env['AGENTAGE_CONFIG_DIR'] || join(process.env['HOME'] || homedir(), '.agentage');
 export const ensureConfigDir = () => {
     const dir = getConfigDir();
@@ -11,27 +11,20 @@ export const ensureConfigDir = () => {
     return dir;
 };
 const authPath = () => join(getConfigDir(), 'auth.json');
-export const readAuth = () => {
-    const path = authPath();
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(readFileSync(path, 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-};
-// Atomic 0600 write: a token file is never left half-written or briefly world-readable. Write a
-// per-save sibling temp (unique name: concurrent savers can never clobber each other's tmp),
-// chmod it 0600 BEFORE the rename, then rename over the target in one step.
+const isOptional = (value, type) => value === undefined || typeof value === type;
+const isStoredTokens = (value) => isRecord(value) &&
+    typeof value['accessToken'] === 'string' &&
+    isOptional(value['refreshToken'], 'string') &&
+    isOptional(value['expiresAt'], 'number');
+// A malformed auth.json (e.g. `{}`) reads as signed out rather than crashing every command.
+export const isAuthState = (value) => isRecord(value) &&
+    typeof value['siteFqdn'] === 'string' &&
+    typeof value['clientId'] === 'string' &&
+    isStoredTokens(value['tokens']);
+export const readAuth = () => readJson(authPath(), isAuthState);
 export const saveAuth = (state) => {
     ensureConfigDir();
-    const path = authPath();
-    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
-    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
-    chmodSync(tmp, 0o600);
-    renameSync(tmp, path);
+    writeJsonAtomic(authPath(), state);
 };
 // Sign-out under the same lock mutateAuth takes (issue #236), so a concurrent token refresh can
 // never slip its re-read+save between this existence check and the unlink.

package/dist/lib/fs/file-lock.d.ts

@@ -1,3 +1,8 @@
-export declare const acquireFileLock: (target: string, now?: number) => boolean;
+export interface LockOptions {
+    ttlMs?: number;
+    hardStaleMs?: number;
+    maxWaitMs?: number;
+}
+export declare const acquireFileLock: (target: string, now?: number, opts?: LockOptions) => boolean;
 export declare const releaseFileLock: (target: string) => void;
-export declare const withFileLock: <T>(target: string, fn: () => T) => Promise<T>;
+export declare const withFileLock: <T>(target: string, fn: () => T, opts?: LockOptions) => Promise<T>;

package/dist/lib/fs/file-lock.js

@@ -1,20 +1,16 @@
 import { randomBytes } from 'node:crypto';
 import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-// A cross-process advisory lock keyed to a target file (`<target>.lock`). Config read-modify-writes
-// are sub-millisecond, so a lock past this age whose holder is gone is a crashed holder to take over.
-const LOCK_TTL_MS = 10_000;
-// A caller blocks up to this long for a contended lock. Past the TTL so a crashed holder is taken
-// over rather than wedging the caller; a throw only happens if the lock is genuinely stuck.
-const MAX_WAIT_MS = 15_000;
-// Past this age a holder is taken over even if its pid still resolves - the only explanation left is
-// pid reuse after a crash. Far beyond any real critical section or plausible scheduler pause, so a
-// live-but-CPU-starved holder is never mistaken for crashed below it.
-const STALE_HARD_MS = 60_000;
+// Sized for sub-millisecond config read-modify-writes; the wait outlives the TTL on purpose.
+const DEFAULTS = { ttlMs: 10_000, hardStaleMs: 60_000, maxWaitMs: 15_000 };
 const STEP_MS = 25;
+const limitsOf = (opts) => ({
+    ttlMs: opts.ttlMs ?? DEFAULTS.ttlMs,
+    hardStaleMs: opts.hardStaleMs ?? DEFAULTS.hardStaleMs,
+    maxWaitMs: opts.maxWaitMs ?? DEFAULTS.maxWaitMs,
+});
 const lockPath = (target) => `${target}.lock`;
-// The lock file holds "<pid> <timestamp>": pid gates crash-takeover, the trailing token is the
-// acquisition time used for staleness. A legacy single-token file parses as pid 0 (unknown holder).
+// "<pid> <at>"; a legacy single-token file parses as pid 0 (unknown holder) and ages out on the TTL.
 const holderOf = (path) => {
     try {
         const parts = readFileSync(path, 'utf-8').trim().split(/\s+/);
@@ -28,8 +24,7 @@ const holderOf = (path) => {
         return null;
     }
 };
-// Same-host liveness probe. ESRCH = the holder is gone (crashed); EPERM = alive but owned by another
-// user. pid 0/unknown counts as gone so a legacy or malformed lock still ages out on the TTL.
+// ESRCH = gone; EPERM = alive under another user; pid 0 (unknown) counts as gone.
 const holderAlive = (pid) => {
     if (pid <= 0)
         return false;
@@ -41,15 +36,12 @@ const holderAlive = (pid) => {
         return err.code === 'EPERM';
     }
 };
-// A holder is safe to take over only once it is past the TTL AND provably gone: a dead pid, our own
-// leftover pid (we cannot be inside our own synchronous section while here), or so old that pid reuse
-// is the only explanation. A live holder merely starved of CPU is NEVER stolen - stealing it would
-// put two writers in the critical section and silently drop an append (issue #249).
-const isCrashed = (holder, now) => {
+// Never steal a live-but-CPU-starved holder: two writers in the section drop an append (#249).
+const isCrashed = (holder, now, lim) => {
     const age = now - holder.at;
-    if (age < LOCK_TTL_MS)
+    if (age < lim.ttlMs)
         return false;
-    if (age >= STALE_HARD_MS)
+    if (age >= lim.hardStaleMs)
         return true;
     return holder.pid === process.pid || !holderAlive(holder.pid);
 };
@@ -61,10 +53,7 @@ const unlinkQuiet = (path) => {
         // already gone
     }
 };
-// Atomic exclusive create: writeFileSync('wx') is create-then-write, so a concurrent holderOf can
-// read the freshly created but still-empty lock and mistake a live holder for absent (issue #231
-// lost-update). Instead write the full "<pid> <at>" to a unique temp, then linkSync it into place:
-// link is atomic and fails EEXIST if held, so the content is always complete when the lock appears.
+// Write-then-link: a reader can never see the lock before its "<pid> <at>" content (#231).
 const createLockExclusive = (path, content) => {
     const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.new`;
     writeFileSync(tmp, content);
@@ -75,15 +64,12 @@ const createLockExclusive = (path, content) => {
         unlinkQuiet(tmp);
     }
 };
-// Serialize stale-lock takeover behind its own exclusive create so no taker can delete a lock that
-// turned FRESH mid-takeover (the ABA race: a reader sees the stale timestamp, a winner re-creates
-// the lock, the reader deletes the winner's file). Same O_EXCL-guard design proven in
-// update-lock.ts. Returns whether to re-race the create.
-const takeOverStale = (target, now) => {
+// Takeover runs under its own exclusive guard so no taker deletes a lock that turned fresh (ABA).
+const takeOverStale = (target, now, lim) => {
     const path = lockPath(target);
     const guard = `${path}.takeover`;
     const guardHeld = holderOf(guard);
-    if (guardHeld !== null && isCrashed(guardHeld, now))
+    if (guardHeld !== null && isCrashed(guardHeld, now, lim))
         unlinkQuiet(guard);
     try {
         createLockExclusive(guard, `${process.pid} ${now}`);
@@ -93,10 +79,8 @@ const takeOverStale = (target, now) => {
     }
     try {
         const holder = holderOf(path);
-        // A null holder means the lock file exists but its content did not read cleanly. Never treat that
-        // as absent: clearing it here would steal a live holder still writing its bytes. Only a holder we
-        // can positively prove crashed is taken over.
-        if (holder === null || !isCrashed(holder, now))
+        // Unreadable content is not proof of a crash: only a provably crashed holder is cleared.
+        if (holder === null || !isCrashed(holder, now, lim))
             return false;
         unlinkQuiet(path);
         return true;
@@ -105,49 +89,56 @@ const takeOverStale = (target, now) => {
         unlinkQuiet(guard);
     }
 };
-// One-shot acquire: the atomic link IS the mutex - concurrent callers cannot both win it, and the
-// linked content is always complete so no reader sees an empty lock. A fresh or live holder refuses;
-// a crashed one (dead holder past the TTL) is cleared under the takeover guard and re-raced once.
-// `now` is injectable for tests.
-export const acquireFileLock = (target, now = Date.now()) => {
-    mkdirSync(dirname(target), { recursive: true });
+// Only EEXIST is contention; a permission error never clears, so it fails fast.
+const lockWriteError = (err, path) => {
+    const code = err.code;
+    if (code === 'EEXIST')
+        return null;
+    if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS')
+        return new Error(`permission denied: ${path}`);
+    return new Error(`could not write lock file ${path}${code ? ` (${code})` : ''}`);
+};
+const tryCreate = (path, now) => {
+    try {
+        createLockExclusive(path, `${process.pid} ${now}`);
+        return true;
+    }
+    catch (err) {
+        const fatal = lockWriteError(err, path);
+        if (fatal)
+            throw fatal;
+        return false;
+    }
+};
+// One-shot acquire: the atomic link IS the mutex; a crashed holder is cleared and re-raced once.
+export const acquireFileLock = (target, now = Date.now(), opts = {}) => {
+    const lim = limitsOf(opts);
+    const path = lockPath(target);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
     for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-            createLockExclusive(lockPath(target), `${process.pid} ${now}`);
+        if (tryCreate(path, now))
             return true;
-        }
-        catch (err) {
-            // Only EEXIST means contention. A permission/read-only error never clears, so failing fast
-            // beats burning the full MAX_WAIT_MS before reporting a generic "could not acquire lock".
-            const code = err.code;
-            if (code !== 'EEXIST') {
-                const path = lockPath(target);
-                throw new Error(code === 'EACCES' || code === 'EPERM' || code === 'EROFS'
-                    ? `permission denied: ${path}`
-                    : `could not write lock file ${path}${code ? ` (${code})` : ''}`);
-            }
-            const holder = holderOf(lockPath(target));
-            // Refuse unless the holder is positively crashed. A null holder (unreadable content) is NOT
-            // proof of a crash: attempting takeover on it once stole a live holder's lock (issue #231).
-            if (holder === null || !isCrashed(holder, now))
-                return false;
-            if (!takeOverStale(target, now))
-                return false;
-        }
+        const holder = holderOf(path);
+        if (holder === null || !isCrashed(holder, now, lim))
+            return false;
+        if (!takeOverStale(target, now, lim))
+            return false;
     }
     return false;
 };
-export const releaseFileLock = (target) => unlinkQuiet(lockPath(target));
+// Only our own lock: a holder that took over after the hard-stale age keeps theirs.
+export const releaseFileLock = (target) => {
+    const path = lockPath(target);
+    if (holderOf(path)?.pid === process.pid)
+        unlinkQuiet(path);
+};
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// Run `fn` while holding the advisory lock for `target`, blocking with bounded backoff until the
-// lock is free (or a crashed holder is taken over past the TTL). `fn` MUST be synchronous: the lock
-// is held only across one synchronous critical section, so in-process callers can never both be
-// inside it. The whole read-modify-write belongs in `fn` - locking only the write still loses
-// updates across the read->write gap. Released in a finally, so a throw never wedges the lock.
-export const withFileLock = async (target, fn) => {
-    const deadline = Date.now() + MAX_WAIT_MS;
+// `fn` MUST be synchronous and hold the whole read-modify-write; released in a finally.
+export const withFileLock = async (target, fn, opts = {}) => {
+    const { maxWaitMs } = limitsOf(opts);
+    const deadline = Date.now() + maxWaitMs;
     for (;;) {
-        if (acquireFileLock(target)) {
+        if (acquireFileLock(target, Date.now(), opts)) {
             try {
                 return fn();
             }
@@ -155,9 +146,8 @@ export const withFileLock = async (target, fn) => {
                 releaseFileLock(target);
             }
         }
-        if (Date.now() >= deadline) {
-            throw new Error(`could not acquire lock for ${target} within ${MAX_WAIT_MS}ms`);
-        }
+        if (Date.now() >= deadline)
+            throw new Error(`could not acquire lock for ${target} within ${maxWaitMs}ms`);
         await sleep(STEP_MS + Math.floor(Math.random() * STEP_MS));
     }
 };

package/dist/lib/fs/json-file.d.ts

@@ -0,0 +1,3 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const readJson: <T>(path: string, guard: (value: unknown) => value is T) => T | null;
+export declare const writeJsonAtomic: (path: string, value: unknown, mode?: number) => void;

package/dist/lib/fs/json-file.js

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// null on a missing, unparsable or wrong-shaped file: callers treat all three as "absent".
+export const readJson = (path, guard) => {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const value = JSON.parse(raw);
+        return guard(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+const unlinkQuiet = (path) => {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // already gone
+    }
+};
+// Unique temp sibling + chmod before rename: never half-written, never briefly world-readable.
+export const writeJsonAtomic = (path, value, mode = 0o600) => {
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    let renamed = false;
+    try {
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf-8', mode });
+        chmodSync(tmp, mode);
+        renameSync(tmp, path);
+        renamed = true;
+    }
+    finally {
+        if (!renamed)
+            unlinkQuiet(tmp);
+    }
+};

package/dist/lib/net/fetch.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const AUTH_TIMEOUT_MS = 15000;
+export type CliRequestInit = Omit<RequestInit, 'headers' | 'redirect' | 'signal'> & {
+    headers?: Record<string, string>;
+};
+export interface CliFetchOptions {
+    timeoutMs?: number;
+}
+export declare const cliFetch: (url: string, init?: CliRequestInit, opts?: CliFetchOptions) => Promise<Response>;
+export declare const isRedirect: (res: Response) => boolean;

package/dist/lib/net/fetch.js

@@ -0,0 +1,13 @@
+import { requestHeaders } from './user-agent.js';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const AUTH_TIMEOUT_MS = 15_000;
+// Captured at load: plugins loaded later must not be able to swap the fetch that carries tokens.
+const baseFetch = globalThis.fetch;
+// redirect: 'manual' so a bearer or form body is never replayed to a redirect target.
+export const cliFetch = (url, init = {}, opts = {}) => baseFetch(url, {
+    ...init,
+    headers: { ...init.headers, ...requestHeaders() },
+    redirect: 'manual',
+    signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+});
+export const isRedirect = (res) => res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);

package/dist/lib/net/http.js

@@ -1,27 +1,55 @@
-import { get } from 'node:https';
-// node:https instead of global fetch: undici keeps a ref'd ~10s connect timer alive even after
-// its AbortSignal fires, stalling process exit on an unreachable network. req.destroy() from an
-// unref'd timer caps the whole attempt and frees the event loop the moment it settles. Never
-// throws: an unreachable host or malformed body resolves null (unreachable) or json:null.
-export const fetchJsonUnref = (url, timeoutMs, headers = {}) => new Promise((resolve) => {
-    const req = get(url, { headers: { Accept: 'application/json', ...headers } }, (res) => {
-        let body = '';
-        res.setEncoding('utf8');
-        res.on('data', (chunk) => {
-            body += chunk;
-        });
-        res.on('end', () => {
-            const status = res.statusCode ?? 0;
-            let json = null;
-            try {
-                json = body ? JSON.parse(body) : null;
-            }
-            catch {
-                json = null;
-            }
-            resolve({ ok: status >= 200 && status < 300, status, json });
-        });
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+// Loopback stubs (AGENTAGE_SITE_FQDN=127.0.0.1:<port>) are plain http; every real target is https.
+const getterFor = (url) => {
+    try {
+        const { protocol } = new URL(url);
+        if (protocol === 'https:')
+            return httpsGet;
+        if (protocol === 'http:')
+            return httpGet;
+    }
+    catch {
+        // not a URL
+    }
+    return null;
+};
+const parseJson = (body) => {
+    try {
+        return body ? JSON.parse(body) : null;
+    }
+    catch {
+        return null;
+    }
+};
+const collect = (res, resolve) => {
+    let body = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+        body += chunk;
+    });
+    res.on('end', () => {
+        const status = res.statusCode ?? 0;
+        resolve({ ok: status >= 200 && status < 300, status, json: parseJson(body) });
     });
+};
+// A synchronous throw (e.g. an invalid header value) is a failed request, not a crash.
+const start = (url, headers, resolve) => {
+    const get = getterFor(url);
+    if (!get)
+        return null;
+    try {
+        return get(url, { headers: { Accept: 'application/json', ...headers } }, (res) => collect(res, resolve));
+    }
+    catch {
+        return null;
+    }
+};
+// node:http(s), not fetch: undici's ref'd connect timer outlives an abort and stalls process exit.
+export const fetchJsonUnref = (url, timeoutMs, headers = {}) => new Promise((resolve) => {
+    const req = start(url, headers, resolve);
+    if (!req)
+        return resolve(null);
     const timer = setTimeout(() => req.destroy(), timeoutMs);
     timer.unref();
     req.once('error', () => resolve(null));

package/dist/lib/npm/npm-cli.d.ts

@@ -0,0 +1,17 @@
+export interface NpmResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RunNpmOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}
+export interface ResolveNpmOptions {
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const resolveNpmCli: (opts?: ResolveNpmOptions) => string;
+export declare const runNpm: (args: string[], opts: RunNpmOptions) => Promise<NpmResult>;
+export declare const requireNpm10: (run?: typeof runNpm) => Promise<string>;

package/dist/lib/npm/npm-cli.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+const NPM_CLI = join('npm', 'bin', 'npm-cli.js');
+const NPM_MIN_MAJOR = 10;
+const VERSION_TIMEOUT_MS = 30_000;
+const MAX_BUFFER = 16 * 1024 * 1024;
+// POSIX prefixes keep npm in <prefix>/lib/node_modules; the Windows installer puts it beside node.exe.
+const bundledCandidates = (execPath) => [
+    join(dirname(execPath), '..', 'lib', 'node_modules', NPM_CLI),
+    join(dirname(execPath), 'node_modules', NPM_CLI),
+];
+// Homebrew-style installs keep npm apart from node; their `npm` on PATH links to npm-cli.js.
+const fromPath = (env) => {
+    for (const dir of (env['PATH'] ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            const real = realpathSync(join(dir, 'npm'));
+            if (real.endsWith('npm-cli.js'))
+                return real;
+        }
+        catch {
+            // no npm in this PATH entry
+        }
+    }
+    return undefined;
+};
+// npm runs as `node npm-cli.js`: no shell and no platform shim (npm.cmd) in between.
+export const resolveNpmCli = (opts = {}) => {
+    const execPath = opts.execPath ?? process.execPath;
+    const env = opts.env ?? process.env;
+    const bundled = bundledCandidates(execPath).find((path) => existsSync(path));
+    if (bundled)
+        return bundled;
+    const fromEnv = env['npm_execpath'];
+    if (fromEnv?.endsWith('npm-cli.js'))
+        return fromEnv;
+    const onPath = fromPath(env);
+    if (onPath)
+        return onPath;
+    throw new Error(`npm-cli.js not found next to ${execPath}`);
+};
+const isScrubbed = (key) => /^npm_config_/i.test(key) || key.toUpperCase() === 'NODE_OPTIONS';
+// Inherited npm_config_* (an `npx` or `npm run` parent) would redirect a global install.
+const childEnv = (env = {}) => ({
+    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !isScrubbed(key))),
+    ...env,
+});
+const failureNote = (err, timeoutMs) => {
+    if (!err || typeof err.code === 'number')
+        return '';
+    if (err.killed)
+        return `\nnpm timed out after ${timeoutMs}ms`;
+    return `\nnpm could not run (${String(err.code ?? err.signal ?? 'unknown')})`;
+};
+export const runNpm = (args, opts) => new Promise((resolve) => {
+    const argv = [resolveNpmCli(), ...args, '--no-audit', '--no-fund'];
+    const options = {
+        cwd: opts.cwd,
+        env: childEnv(opts.env),
+        timeout: opts.timeoutMs,
+        maxBuffer: MAX_BUFFER,
+        windowsHide: true,
+    };
+    execFile(process.execPath, argv, options, (err, stdout, stderr) => {
+        const code = !err ? 0 : typeof err.code === 'number' ? err.code : 1;
+        resolve({ code, stdout, stderr: stderr + failureNote(err, opts.timeoutMs) });
+    });
+});
+export const requireNpm10 = async (run = runNpm) => {
+    const res = await run(['--version'], { timeoutMs: VERSION_TIMEOUT_MS });
+    const version = res.stdout.trim();
+    if (res.code !== 0 || !(Number.parseInt(version, 10) >= NPM_MIN_MAJOR))
+        throw new Error(`npm ${NPM_MIN_MAJOR} or newer is required (found ${version || 'none'})`);
+    return version;
+};

package/dist/lib/status/status-info.js

@@ -1,5 +1,6 @@
 import { AuthRequiredError, introspectToken } from '../auth/api.js';
 import { detectEnvMismatch } from '../auth/env-match.js';
+import {} from '../fs/config.js';
 import { fetchJsonUnref } from '../net/http.js';
 import { requestHeaders } from '../net/user-agent.js';
 import { environment, links } from '../net/origins.js';

package/dist/lib/update/update-cache.d.ts

@@ -2,6 +2,7 @@ export interface UpdateCache {
     checkedAt: number;
     latest: string | null;
 }
+export declare const isUpdateCache: (value: unknown) => value is UpdateCache;
 export declare const readUpdateCache: () => UpdateCache | null;
 export declare const updateHint: () => string | null;
 export declare const fetchLatestVersion: (timeoutMs: number, url?: string) => Promise<string | null>;