@agentage/cli 0.39.0 → 0.41.0

package/dist/core/profile/merge.js

@@ -1,12 +1,12 @@
 import {} from './machine.js';
 import {} from './schema.js';
 // Machine values replace shared ones per key; no deep merge, so arrays are replaced whole.
-export const mergeConfig = (shared, local) => {
+const mergeConfig = (shared, local) => {
     const ids = [...new Set([...Object.keys(shared), ...Object.keys(local)])].sort();
     return Object.fromEntries(ids.map((id) => [id, { ...shared[id], ...local[id] }]));
 };
 export const effective = (profile, machine) => {
-    const install = { ...profile?.plugins };
+    const install = { ...profile?.extensions };
     const self = profile?.machines[machine.id];
     const off = self?.off ?? [];
     const kept = Object.keys(install).filter((name) => !off.includes(name));
@@ -14,3 +14,8 @@ export const effective = (profile, machine) => {
     const config = mergeConfig(profile?.config ?? {}, self?.config ?? {});
     return { install, load, off, dev: { ...machine.dev }, config };
 };
+// `setup --profile` replaces the shared fields; this machine's own `off` and `config` survive.
+export const keepMachine = (next, current, machineId) => {
+    const self = current?.machines[machineId];
+    return self ? { ...next, machines: { ...next.machines, [machineId]: self } } : next;
+};

package/dist/core/profile/profile.d.ts

@@ -1,6 +1,6 @@
-import { type ProfileParse } from './schema.js';
-export interface ProfileDeps {
-    path: () => string;
-    readText: (path: string) => string | null;
-}
-export declare const readProfile: (deps?: ProfileDeps) => ProfileParse | null;
+import { type Profile, type ProfileParse } from './schema.js';
+export declare const defaultProfile: () => Profile;
+export declare const parseProfileText: (raw: string) => ProfileParse;
+export declare const readProfile: () => ProfileParse | null;
+export declare const editableProfile: () => Profile;
+export declare const mutateProfile: (fn: (current: Profile | null) => Profile) => Promise<Profile>;

package/dist/core/profile/profile.js

@@ -1,6 +1,26 @@
-import { readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { withFileLock } from '../../lib/fs/file-lock.js';
+import { writeJsonAtomic } from '../../lib/fs/json-file.js';
 import { profilePath } from '../paths.js';
-import { parseProfile } from './schema.js';
+import { parseProfile, SCHEMA_VERSION, toDocument, } from './schema.js';
+// No extension is published yet, so a machine without a profile starts with none.
+export const defaultProfile = () => ({
+    version: SCHEMA_VERSION,
+    extensions: {},
+    registries: {},
+    config: {},
+    machines: {},
+    extra: {},
+});
+export const parseProfileText = (raw) => {
+    try {
+        return parseProfile(JSON.parse(raw));
+    }
+    catch {
+        return { ok: false, errors: ['not valid JSON'] };
+    }
+};
 const readText = (path) => {
     try {
         return readFileSync(path, 'utf-8');
@@ -11,24 +31,38 @@ const readText = (path) => {
         throw err;
     }
 };
-const defaultDeps = { path: profilePath, readText };
-const messageOf = (err) => (err instanceof Error ? err.message : String(err));
-const parseText = (raw) => {
-    try {
-        return parseProfile(JSON.parse(raw));
-    }
-    catch {
-        return { ok: false, errors: ['profile.json: not valid JSON'] };
-    }
-};
 // null only when profile.json is absent; an unreadable or invalid file reports its errors.
-export const readProfile = (deps = defaultDeps) => {
+export const readProfile = () => {
     let raw;
     try {
-        raw = deps.readText(deps.path());
+        raw = readText(profilePath());
     }
     catch (err) {
-        return { ok: false, errors: [`profile.json: ${messageOf(err)}`] };
+        return { ok: false, errors: [err.message] };
     }
-    return raw === null ? null : parseText(raw);
+    return raw === null ? null : parseProfileText(raw);
+};
+const listed = (errors) => errors.map((e) => `  ${e}`).join('\n');
+// What `extension install` and `remove` change: the default when absent; never an invalid or newer file.
+export const editableProfile = () => {
+    const parsed = readProfile();
+    if (parsed === null)
+        return defaultProfile();
+    if (!parsed.ok)
+        throw new Error(`profile.json is invalid:\n${listed(parsed.errors)}`);
+    if (!parsed.readOnly)
+        return parsed.profile;
+    const { version } = parsed.profile;
+    throw new Error(`profile.json is version ${version}, newer than this CLI understands; it was not changed`);
+};
+// Re-read under the lock: `fn` sees the newest local copy (null when absent or invalid).
+export const mutateProfile = async (fn) => {
+    const path = profilePath();
+    return withFileLock(path, () => {
+        const current = readProfile();
+        const next = fn(current?.ok ? current.profile : null);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeJsonAtomic(path, toDocument(next));
+        return next;
+    });
 };

package/dist/core/profile/push.d.ts

@@ -0,0 +1,16 @@
+import { type CloudFetch, type CloudProfile, type JsonObject, type ProfileWrite } from './cloud.js';
+import { type Profile } from './schema.js';
+export type Apply = (base: CloudProfile) => Promise<ProfileWrite>;
+export interface Pushed {
+    etag: string;
+    pushed: boolean;
+}
+export interface LockPair {
+    lock: JsonObject | null;
+    npmMajor: number | null;
+}
+export interface ReplayOptions {
+    lockCounts?: boolean;
+}
+export declare const pushBody: (next: Profile, base: CloudProfile, local: LockPair) => ProfileWrite;
+export declare const pushWithReplay: (fetch: CloudFetch, base: CloudProfile, apply: Apply, { lockCounts }?: ReplayOptions) => Promise<Pushed>;

package/dist/core/profile/push.js

@@ -0,0 +1,49 @@
+import { isDeepStrictEqual } from 'node:util';
+import { pushProfile, } from './cloud.js';
+import { toDocument } from './schema.js';
+// A lock from another npm major than the account's is not pushed: the account keeps its own.
+export const pushBody = (next, base, local) => {
+    const other = base.npmMajor !== null && local.npmMajor !== null;
+    const keep = other && base.npmMajor !== local.npmMajor;
+    const pair = keep ? { lock: base.lock, npmMajor: base.npmMajor } : local;
+    return { version: next.version, profile: toDocument(next), ...pair };
+};
+const refuseNewer = (base) => {
+    if (!base.readOnly)
+        return;
+    const newer = `version ${base.profile.version}, newer than this CLI understands`;
+    throw new Error(`the profile in your account is ${newer}; it was not changed`);
+};
+// The account holds this already: the same profile and, when the lock counts, the same lock.
+const held = (body, base, lockCounts) => base.etag !== null &&
+    isDeepStrictEqual(body.profile, toDocument(base.profile)) &&
+    (!lockCounts || isDeepStrictEqual(body.lock, base.lock));
+const attemptOn = async (fetch, base, apply, lockCounts) => {
+    refuseNewer(base);
+    const body = await apply(base);
+    if (held(body, base, lockCounts))
+        return { kind: 'done', etag: base.etag, pushed: false };
+    const res = await pushProfile(fetch, body, base.etag);
+    if (res.kind === 'stored')
+        return { kind: 'done', etag: res.etag, pushed: true };
+    return { kind: 'conflict', body, current: res.current };
+};
+const shown = (doc) => JSON.stringify(doc, null, 2);
+const conflictError = (body, current) => {
+    const theirs = current
+        ? `in your account (etag ${current.etag}):\n${shown(toDocument(current.profile))}`
+        : 'in your account: none';
+    return new Error('not pushed: the profile in your account changed again while this change was pushed\n' +
+        `yours:\n${shown(body.profile)}\n${theirs}`);
+};
+// On a 412 the change is replayed once on the account's document; a second 412 shows both.
+export const pushWithReplay = async (fetch, base, apply, { lockCounts = false } = {}) => {
+    const first = await attemptOn(fetch, base, apply, lockCounts);
+    if (first.kind === 'done')
+        return { etag: first.etag, pushed: first.pushed };
+    const retry = first.current ?? { ...base, etag: null };
+    const second = await attemptOn(fetch, retry, apply, lockCounts);
+    if (second.kind === 'done')
+        return { etag: second.etag, pushed: second.pushed };
+    throw conflictError(second.body, second.current);
+};

package/dist/core/profile/register.d.ts

@@ -0,0 +1,5 @@
+import { type CloudFetch } from './cloud.js';
+import { type MachineFile } from './machine.js';
+export declare const registerMachine: (fetch: CloudFetch, machine: Pick<MachineFile, "id" | "name">) => Promise<void>;
+export declare const seenMachine: (fetch: CloudFetch, id: string) => Promise<boolean | null>;
+export declare const disconnectMachine: (fetch: CloudFetch, id: string) => Promise<void>;

package/dist/core/profile/register.js

@@ -0,0 +1,57 @@
+import { VERSION } from '../../utils/version.js';
+import { errorCode } from './cloud.js';
+import {} from './machine.js';
+// Fire and forget: never longer than this, never a failure, silent unless AGENTAGE_DEBUG=1.
+const BUDGET_MS = 2_000;
+const NAME_MAX = 128;
+const routeOf = (id) => `/v1/machines/${id}`;
+const debug = (text) => {
+    if (process.env['AGENTAGE_DEBUG'] === '1')
+        console.error(`machines: ${text}`);
+};
+// A 404's body is read for its code; any other body is dropped unread.
+const answerOf = async (res) => {
+    if (res.status === 404)
+        return { status: 404, code: await errorCode(res) };
+    await res.body?.cancel();
+    return { status: res.status, code: null };
+};
+// What the account answered, or null when it did not.
+const send = async (fetch, call, timeoutMs = BUDGET_MS) => {
+    const headers = call.body ? { 'content-type': 'application/json' } : {};
+    const body = call.body ? JSON.stringify(call.body) : undefined;
+    try {
+        const answer = await answerOf(await fetch(call.path, { method: call.method, headers, body, timeoutMs }));
+        debug(`${call.method} ${call.path} ${answer.status}${answer.code ? ` ${answer.code}` : ''}`);
+        return answer;
+    }
+    catch (err) {
+        const reason = err.name === 'TimeoutError' ? 'timed out' : err.message;
+        debug(`${call.method} ${call.path} failed: ${reason}`);
+        return null;
+    }
+};
+const registration = (machine) => ({
+    name: machine.name.slice(0, NAME_MAX),
+    platform: `${process.platform}-${process.arch}`,
+    cliVersion: VERSION,
+    state: 'connected',
+});
+// Signed-in setup: create or refresh the record, then mark it seen, both inside one budget.
+export const registerMachine = async (fetch, machine) => {
+    const deadline = Date.now() + BUDGET_MS;
+    const path = routeOf(machine.id);
+    await send(fetch, { method: 'PUT', path, body: registration(machine) });
+    await send(fetch, { method: 'POST', path: `${path}/seen` }, Math.max(1, deadline - Date.now()));
+};
+// true when the account knows this machine, false on MACHINE_NOT_FOUND, null when it did not
+// say: any other 404 is an API without the route, as unknown as no answer.
+export const seenMachine = async (fetch, id) => {
+    const answer = await send(fetch, { method: 'POST', path: `${routeOf(id)}/seen` });
+    if (answer?.code === 'MACHINE_NOT_FOUND')
+        return false;
+    return answer !== null && answer.status >= 200 && answer.status < 300 ? true : null;
+};
+export const disconnectMachine = async (fetch, id) => {
+    await send(fetch, { method: 'PATCH', path: routeOf(id), body: { state: 'disconnected' } });
+};

package/dist/core/profile/schema.d.ts

@@ -7,7 +7,8 @@ export interface MachineEntry {
 }
 export interface Profile {
     version: number;
-    plugins: Record<string, string>;
+    extensions: Record<string, string>;
+    registries: Record<string, string>;
     config: ConfigMap;
     machines: Record<string, MachineEntry>;
     extra: Record<string, unknown>;
@@ -21,6 +22,7 @@ export type ProfileParse = {
     ok: false;
     errors: string[];
 };
+export declare const PACKAGE_NAME: RegExp;
 export declare const specProblem: (spec: string) => string | null;
 export declare const parseProfile: (doc: unknown) => ProfileParse;
 export declare const toDocument: (profile: Profile) => Record<string, unknown>;

package/dist/core/profile/schema.js

@@ -1,9 +1,10 @@
 import { isRecord } from '../../lib/fs/json-file.js';
 import { isRange } from '../semver-range.js';
 export const SCHEMA_VERSION = 1;
-const TOP_KEYS = ['version', 'plugins', 'config', 'machines'];
+const TOP_KEYS = ['version', 'extensions', 'registries', 'config', 'machines'];
 const MACHINE_KEYS = ['off', 'config'];
-const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+export const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const SCOPE = /^@[a-z0-9][a-z0-9._~-]*$/;
 const LOOPBACK_HOST = /^(?:localhost|.+\.localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\])$/i;
 const REFUSED_PREFIX = /^(npm|github|file|http):/i;
 const OTHER_PROTOCOL = /^[a-z][a-z0-9+.-]*:/i;
@@ -15,15 +16,20 @@ const fail = (issues, message, fallback) => {
     issues.errors.push(message);
     return fallback;
 };
-const httpsProblem = (spec) => {
+const urlOf = (text) => {
     try {
-        const host = new URL(spec).hostname;
-        return LOOPBACK_HOST.test(host) ? 'loopback URLs are refused' : null;
+        return new URL(text);
     }
     catch {
-        return 'is not a valid https: URL';
+        return null;
     }
 };
+const httpsProblem = (spec) => {
+    const url = urlOf(spec);
+    if (url === null)
+        return 'is not a valid https: URL';
+    return LOOPBACK_HOST.test(url.hostname) ? 'loopback URLs are refused' : null;
+};
 export const specProblem = (spec) => {
     const refused = REFUSED_PREFIX.exec(spec)?.[1];
     if (refused)
@@ -36,27 +42,41 @@ export const specProblem = (spec) => {
         return `unsupported spec; ${USE_INSTEAD}`;
     return isRange(spec) ? null : `is not a semver range; ${USE_INSTEAD}`;
 };
-const pluginProblem = (name, spec) => {
+const extensionProblem = (name, spec) => {
     if (!PACKAGE_NAME.test(name))
         return 'is not a valid package name';
     if (typeof spec !== 'string' || spec.trim() === '')
         return 'must be a non-empty string';
     return specProblem(spec.trim());
 };
-const parsePlugins = (value, issues) => {
+// Whitespace is refused outright: the URL lands on one line of the tree's .npmrc.
+const registryProblem = (scope, url) => {
+    if (!SCOPE.test(scope))
+        return 'is not an npm scope (@name)';
+    const parsed = typeof url === 'string' && !/\s/.test(url) ? urlOf(url) : null;
+    if (parsed && (parsed.username || parsed.password))
+        return 'must not carry credentials';
+    if (parsed?.protocol === 'https:')
+        return null;
+    if (parsed?.protocol === 'http:' && LOOPBACK_HOST.test(parsed.hostname))
+        return null;
+    return 'must be an https: URL, or http: on a loopback host';
+};
+// A map of strings: each entry is checked on its own and reported by its path.
+const parseMap = (value, path, problemOf, issues) => {
     if (value === undefined)
         return {};
     if (!isRecord(value))
-        return fail(issues, 'plugins: must be an object', {});
-    const plugins = {};
-    for (const [name, spec] of Object.entries(value)) {
-        const problem = pluginProblem(name, spec);
+        return fail(issues, `${path}: must be an object`, {});
+    const map = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const problem = problemOf(key, entry);
         if (problem)
-            issues.errors.push(`plugins${at(name)}: ${problem}`);
+            issues.errors.push(`${path}${at(key)}: ${problem}`);
         else
-            plugins[name] = String(spec);
+            map[key] = String(entry);
     }
-    return plugins;
+    return map;
 };
 const parseConfig = (value, path, issues) => {
     if (value === undefined)
@@ -118,7 +138,8 @@ export const parseProfile = (doc) => {
     const issues = { errors: [], warnings: [] };
     const profile = {
         version: parseVersionField(doc['version'], issues),
-        plugins: parsePlugins(doc['plugins'], issues),
+        extensions: parseMap(doc['extensions'], 'extensions', extensionProblem, issues),
+        registries: parseMap(doc['registries'], 'registries', registryProblem, issues),
         config: parseConfig(doc['config'], 'config', issues),
         machines: parseMachines(doc['machines'], issues),
         extra: extraKeys(doc, TOP_KEYS, 'profile.json', issues),
@@ -133,7 +154,8 @@ export const parseProfile = (doc) => {
 // The inverse of parseProfile: unknown keys go back where they were found.
 export const toDocument = (profile) => ({
     version: profile.version,
-    plugins: profile.plugins,
+    extensions: profile.extensions,
+    ...(Object.keys(profile.registries).length > 0 ? { registries: profile.registries } : {}),
     config: profile.config,
     machines: Object.fromEntries(Object.entries(profile.machines).map(([id, m]) => [
         id,

package/dist/core/semver-range.d.ts

@@ -13,4 +13,5 @@ export declare const parseVersion: (text: string) => Version | null;
 export declare const parseRange: (range: string) => Comparator[][] | null;
 export declare const isRange: (range: string) => boolean;
 export declare const satisfies: (version: string, range: string) => boolean;
+export declare const newestFirst: (a: string, b: string) => number;
 export {};

package/dist/core/semver-range.js

@@ -114,3 +114,11 @@ export const satisfies = (version, range) => {
         return false;
     return sets.some((set) => set.every((c) => holds(c, v)));
 };
+// For sort(): newest version first; text that is not a version goes last.
+export const newestFirst = (a, b) => {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    if (x && y)
+        return compareVersions(y, x);
+    return (x ? -1 : 0) + (y ? 1 : 0);
+};

package/dist/extension-test.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import { type ExtensionApi, type ExtensionContext } from './extension.js';
+export interface TestContextOverrides extends Partial<Omit<ExtensionContext, 'mode' | 'use'>> {
+    use?: Record<string, ExtensionApi>;
+    program?: Command;
+}
+export declare const createTestContext: (overrides?: TestContextOverrides) => ExtensionContext;

package/dist/extension-test.js

@@ -0,0 +1,49 @@
+/**
+ * The `@agentage/cli/extension/test` subpath export: `createTestContext` builds the `ctx` an
+ * extension's own unit tests hand to its `register`, over a temp dir, with `use` from fakes.
+ */
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import {} from './extension.js';
+const memorySecrets = () => {
+    const values = new Map();
+    return {
+        get: async (key) => values.get(key),
+        set: async (key, value) => void values.set(key, value),
+        delete: async (key) => void values.delete(key),
+    };
+};
+const fakeUse = (fakes) => ((id, options = {}) => {
+    const fake = fakes[id];
+    if (fake !== undefined || options.optional)
+        return fake;
+    throw new Error(`use("${id}"): no fake for it in createTestContext({ use })`);
+});
+// A fresh temp dir per context, laid out like the CLI's config dir.
+const folders = (id) => {
+    const root = mkdtempSync(join(tmpdir(), 'agentage-test-'));
+    return { data: join(root, 'data', id), cache: join(root, 'cache', id) };
+};
+// Same members, in the same order, as the ctx the CLI builds; mode is always 'test'.
+export const createTestContext = (overrides = {}) => {
+    const { use = {}, program = new Command('agentage'), config = {}, ...rest } = overrides;
+    const id = rest.id ?? 'test';
+    const subscriptions = [];
+    const ctx = {
+        id,
+        version: '0.0.0',
+        previousVersion: null,
+        mode: 'test',
+        config: Object.freeze({ ...config }),
+        secrets: memorySecrets(),
+        ...folders(id),
+        log: () => undefined,
+        commands: { add: (...registrars) => registrars.forEach((register) => register(program)) },
+        use: fakeUse(use),
+        subscriptions: { push: (...items) => void subscriptions.push(...items) },
+        ...rest,
+    };
+    return Object.freeze(ctx);
+};

package/dist/extension.d.ts

@@ -0,0 +1,83 @@
+import { type Command } from 'commander';
+export declare const EXTENSION_API_VERSION = "1.0.0";
+export type ConfigType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+export interface ConfigurationEntry {
+    type: ConfigType;
+    default?: unknown;
+    description?: string;
+    enum?: unknown[];
+    secret?: boolean;
+    scope?: 'shared' | 'machine';
+}
+export interface ExtensionManifest {
+    name: string;
+    version: string;
+    keywords?: string[];
+    engines?: {
+        agentage?: string;
+    };
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+    }>;
+    agentage: {
+        id: string;
+        contributes?: {
+            commands?: string[];
+        };
+        configuration?: Record<string, ConfigurationEntry>;
+    };
+}
+export interface Disposable {
+    dispose: () => void | Promise<void>;
+}
+export type ExtensionApi = Readonly<Record<string, (...args: never[]) => unknown>>;
+export interface ExtensionApis {
+}
+export interface ExtensionUse {
+    <K extends keyof ExtensionApis>(id: K, options?: {
+        optional?: false;
+    }): ExtensionApis[K];
+    <K extends keyof ExtensionApis>(id: K, options: {
+        optional: true;
+    }): ExtensionApis[K] | undefined;
+    (id: string, options?: {
+        optional?: false;
+    }): ExtensionApi;
+    (id: string, options: {
+        optional: true;
+    }): ExtensionApi | undefined;
+}
+export interface ExtensionSecrets {
+    get: (key: string) => Promise<string | undefined>;
+    set: (key: string, value: string) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+}
+export type ExtensionLog = (message: string, fields?: Record<string, unknown>) => void;
+export type CommandRegistrar = (program: Command) => void;
+export interface ExtensionCommands {
+    add: (...registrars: CommandRegistrar[]) => void;
+}
+export interface ExtensionSubscriptions {
+    push: (...disposables: Disposable[]) => void;
+}
+export type ExtensionMode = 'installed' | 'dev' | 'test';
+export interface ExtensionContext {
+    readonly id: string;
+    readonly version: string;
+    readonly previousVersion: string | null;
+    readonly mode: ExtensionMode;
+    readonly config: Readonly<Record<string, unknown>>;
+    readonly secrets: ExtensionSecrets;
+    readonly data: string;
+    readonly cache: string;
+    readonly log: ExtensionLog;
+    readonly commands: ExtensionCommands;
+    readonly use: ExtensionUse;
+    readonly subscriptions: ExtensionSubscriptions;
+}
+export type Register = (ctx: ExtensionContext) => ExtensionApi | void | Promise<ExtensionApi | void>;
+export interface Extension {
+    register: Register;
+}
+export declare const defineExtension: <T extends Extension>(extension: T) => T;

package/dist/extension.js

@@ -0,0 +1,6 @@
+// Types for an extension's entry; at runtime an extension gets everything through ctx, never this.
+import {} from 'commander';
+// The extension contract is versioned apart from the CLI, so extensions pin it, not a CLI release.
+export const EXTENSION_API_VERSION = '1.0.0';
+// Identity at runtime: it only gives an entry its types.
+export const defineExtension = (extension) => extension;

package/dist/lib/auth/api.d.ts

@@ -1,8 +1,8 @@
 import { type AuthState } from '../fs/config.js';
-import { type CliRequestInit } from '../net/fetch.js';
+import { type CliFetchOptions, type CliRequestInit } from '../net/fetch.js';
 import { type Links } from '../net/origins.js';
 export { AuthRequiredError, TransientAuthError } from './auth-errors.js';
 export declare const refreshOrThrow: (auth: AuthState, links: Links) => Promise<void>;
-export declare const authedFetch: (auth: AuthState, links: Links, url: string, init?: CliRequestInit) => Promise<Response>;
+export declare const authedFetch: (auth: AuthState, links: Links, url: string, init?: CliRequestInit, opts?: CliFetchOptions) => Promise<Response>;
 export declare const authedJson: <T>(auth: AuthState, links: Links, url: string, init?: CliRequestInit) => Promise<T>;
 export { introspectToken, type TokenSession } from './introspect.js';

package/dist/lib/auth/api.js

@@ -61,12 +61,12 @@ const withBearer = (auth, init) => ({
     headers: { ...init.headers, authorization: `Bearer ${auth.tokens.accessToken}` },
 });
 // The raw Response after at most one refresh-and-retry on 401; callers branch on the status.
-export const authedFetch = async (auth, links, url, init = {}) => {
-    const res = await cliFetch(url, withBearer(auth, init));
+export const authedFetch = async (auth, links, url, init = {}, opts = {}) => {
+    const res = await cliFetch(url, withBearer(auth, init), opts);
     if (res.status !== 401 || !(await tryRefresh(auth, links)))
         return res;
     await res.body?.cancel();
-    return cliFetch(url, withBearer(auth, init));
+    return cliFetch(url, withBearer(auth, init), opts);
 };
 export const authedJson = async (auth, links, url, init = {}) => {
     const method = init.method ?? 'GET';

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

@@ -2,7 +2,9 @@ export interface LockOptions {
     ttlMs?: number;
     hardStaleMs?: number;
     maxWaitMs?: number;
+    onWait?: () => void;
 }
 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, opts?: LockOptions) => Promise<T>;
+export declare const refreshFileLock: (target: string, now?: number) => boolean;
+export declare const withFileLock: <T>(target: string, fn: () => T | Promise<T>, opts?: LockOptions) => Promise<T>;

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

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 // 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 };
@@ -132,22 +132,37 @@ export const releaseFileLock = (target) => {
     if (holderOf(path)?.pid === process.pid)
         unlinkQuiet(path);
 };
+// Heartbeat for a long holder: a fresh stamp keeps waiters from ever reading it as crashed.
+export const refreshFileLock = (target, now = Date.now()) => {
+    const path = lockPath(target);
+    if (holderOf(path)?.pid !== process.pid)
+        return false;
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.new`;
+    writeFileSync(tmp, `${process.pid} ${now}`);
+    try {
+        renameSync(tmp, path);
+    }
+    finally {
+        unlinkQuiet(tmp);
+    }
+    return true;
+};
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// `fn` MUST be synchronous and hold the whole read-modify-write; released in a finally.
+// Held for all of `fn`, sync or async; a holder past hardStaleMs keeps it with refreshFileLock.
 export const withFileLock = async (target, fn, opts = {}) => {
     const { maxWaitMs } = limitsOf(opts);
     const deadline = Date.now() + maxWaitMs;
-    for (;;) {
-        if (acquireFileLock(target, Date.now(), opts)) {
-            try {
-                return fn();
-            }
-            finally {
-                releaseFileLock(target);
-            }
-        }
+    for (let tries = 0; !acquireFileLock(target, Date.now(), opts); tries++) {
+        if (tries === 0)
+            opts.onWait?.();
         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));
     }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseFileLock(target);
+    }
 };

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

@@ -1,3 +1,4 @@
 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 writeTextAtomic: (path: string, text: string, mode?: number) => void;
 export declare const writeJsonAtomic: (path: string, value: unknown, mode?: number) => void;