@agentage/cli 0.38.1 → 0.40.0

package/dist/core/loader/states.js

@@ -0,0 +1,52 @@
+import {} from './discover.js';
+const reaches = (from, target, byPkg, seen) => (byPkg.get(from)?.peers ?? []).some((peer) => {
+    if (peer === target)
+        return true;
+    if (seen.has(peer))
+        return false;
+    seen.add(peer);
+    return reaches(peer, target, byPkg, seen);
+});
+const inCycle = (p, byPkg) => reaches(p.pkg, p.pkg, byPkg, new Set());
+const missingReason = (p) => p.source === 'dev' ? `no package.json at ${p.dir}` : 'not installed in the current tree';
+const ownState = (p, off, byPkg) => {
+    if (p.problem)
+        return { state: 'invalid', error: p.problem };
+    if (p.missing)
+        return { state: 'missing', error: missingReason(p) };
+    if (inCycle(p, byPkg))
+        return { state: 'invalid', error: 'peer dependency cycle' };
+    if (p.source === 'tree' && off.includes(p.pkg))
+        return { state: 'off', error: null };
+    return { state: 'installed', error: null };
+};
+const peerBlock = (p, walk) => {
+    for (const peer of p.peers.filter((name) => !p.optionalPeers.includes(name))) {
+        const target = walk.byPkg.get(peer);
+        if (!target)
+            return { state: 'blocked', error: `peer ${peer} is not in the profile` };
+        const { state } = resolveState(target, walk);
+        if (state !== 'installed')
+            return { state: 'blocked', error: `peer ${peer} is ${state}` };
+    }
+    return null;
+};
+// Cycles are already invalid, so the recursion through peers always terminates.
+const resolveState = (p, walk) => {
+    const cached = walk.done.get(p.pkg);
+    if (cached)
+        return cached;
+    const own = walk.own.get(p.pkg) ?? { state: 'invalid', error: null };
+    const result = own.state === 'installed' ? (peerBlock(p, walk) ?? own) : own;
+    walk.done.set(p.pkg, result);
+    return result;
+};
+// The states `status` can know without running extension code; `ok` and `failed` need a load.
+export const staticStates = (extensions, off) => {
+    const byPkg = new Map(extensions.map((p) => [p.pkg, p]));
+    const own = new Map(extensions.map((p) => [p.pkg, ownState(p, off, byPkg)]));
+    const walk = { byPkg, own, done: new Map() };
+    for (const p of extensions)
+        resolveState(p, walk);
+    return walk.done;
+};

package/dist/core/loader/timeout.d.ts

@@ -0,0 +1 @@
+export declare const withTimeout: <T>(promise: Promise<T>, ms: number) => Promise<T>;

package/dist/core/loader/timeout.js

@@ -0,0 +1,8 @@
+// The timer is always cleared; the promise given up on runs on, as loaded code cannot be stopped.
+export const withTimeout = (promise, ms) => {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), ms);
+    });
+    return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
+};

package/dist/core/loader/use.d.ts

@@ -0,0 +1,8 @@
+import { type ExtensionApi, type ExtensionUse } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export interface LoadedPeer {
+    ext: DiscoveredExtension;
+    facade: ExtensionApi;
+}
+export declare const facadeOf: (api: unknown) => ExtensionApi;
+export declare const createUse: (self: DiscoveredExtension, loaded: ReadonlyMap<string, LoadedPeer>) => ExtensionUse;

package/dist/core/loader/use.js

@@ -0,0 +1,18 @@
+import {} from '../../extension.js';
+import { isRecord } from '../../lib/fs/json-file.js';
+import {} from './discover.js';
+// Only own function members cross, bound to the original, in a frozen object of their own.
+export const facadeOf = (api) => {
+    const methods = Object.entries(isRecord(api) ? api : {}).filter((entry) => typeof entry[1] === 'function');
+    return Object.freeze(Object.fromEntries(methods.map(([name, fn]) => [name, fn.bind(api)])));
+};
+// `loaded` is keyed by id; only an extension `self` peer-depends on is reachable.
+export const createUse = (self, loaded) => ((id, options = {}) => {
+    const peer = loaded.get(id);
+    const peers = [...self.peers, ...self.optionalPeers];
+    if (peer && peers.includes(peer.ext.pkg))
+        return peer.facade;
+    if (options.optional)
+        return undefined;
+    throw new Error(`use("${id}"): not a loaded peer of ${self.id}`);
+});

package/dist/core/paths.d.ts

@@ -0,0 +1,8 @@
+export declare const profilePath: () => string;
+export declare const machinePath: () => string;
+export declare const stateDir: () => string;
+export declare const extensionsDir: () => string;
+export declare const secretsPath: () => string;
+export declare const dataDir: (id: string) => string;
+export declare const cacheDir: (id: string) => string;
+export declare const logsDir: () => string;

package/dist/core/paths.js

@@ -0,0 +1,10 @@
+import { join } from 'node:path';
+import { getConfigDir } from '../lib/fs/config.js';
+export const profilePath = () => join(getConfigDir(), 'profile.json');
+export const machinePath = () => join(getConfigDir(), 'machine.json');
+export const stateDir = () => join(getConfigDir(), 'state');
+export const extensionsDir = () => process.env['AGENTAGE_EXTENSIONS_DIR'] || join(getConfigDir(), 'extensions');
+export const secretsPath = () => join(getConfigDir(), 'secrets.json');
+export const dataDir = (id) => join(getConfigDir(), 'data', id);
+export const cacheDir = (id) => join(getConfigDir(), 'cache', id);
+export const logsDir = () => join(getConfigDir(), 'logs');

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

@@ -0,0 +1,53 @@
+import { type Profile } from './schema.js';
+export declare const PROFILE_PATH = "/v1/profile";
+export type JsonObject = Record<string, unknown>;
+export interface CloudInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+}
+export type CloudFetch = (path: string, init?: CloudInit) => Promise<Response>;
+export interface Account {
+    fetch: CloudFetch;
+    id: () => Promise<string | null>;
+}
+export interface ProfileWrite {
+    version: number;
+    profile: JsonObject;
+    lock: JsonObject | null;
+    npmMajor: number | null;
+}
+export interface CloudProfile {
+    profile: Profile;
+    readOnly: boolean;
+    lock: JsonObject | null;
+    npmMajor: number | null;
+    etag: string | null;
+}
+export type Pull = {
+    kind: 'current';
+} | {
+    kind: 'found';
+    doc: CloudProfile & {
+        etag: string;
+    };
+} | {
+    kind: 'none';
+} | {
+    kind: 'unavailable';
+    reason: string;
+};
+export type Push = {
+    kind: 'stored';
+    etag: string;
+} | {
+    kind: 'conflict';
+    current: CloudProfile | null;
+};
+export declare class NotPushedError extends Error {
+}
+export declare const localProfile: (profile: Profile) => CloudProfile;
+export declare const errorCode: (res: Response) => Promise<string | null>;
+export declare const pullProfile: (fetch: CloudFetch, etag: string | null, timeoutMs?: number) => Promise<Pull>;
+export declare const pushProfile: (fetch: CloudFetch, body: ProfileWrite, etag: string | null) => Promise<Push>;

package/dist/core/profile/cloud.js

@@ -0,0 +1,109 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+import { parseProfile } from './schema.js';
+// One resource per account: the profile, npm's lock and the npm major that wrote it, one ETag.
+export const PROFILE_PATH = '/v1/profile';
+// The account answered a push with something other than a new ETag or a 412.
+export class NotPushedError extends Error {
+}
+// A profile that is not in the account yet: pushing it creates it.
+export const localProfile = (profile) => ({
+    profile,
+    readOnly: profile.version > 1,
+    lock: null,
+    npmMajor: null,
+    etag: null,
+});
+// What a request ended with: the Response, or why there was none.
+const attempt = async (request) => {
+    try {
+        return await request();
+    }
+    catch (err) {
+        return err.name === 'TimeoutError' ? 'timed out' : err.message;
+    }
+};
+const bodyOf = async (res) => {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+};
+// The code of the house error envelope, e.g. PROFILE_NOT_FOUND; null without one. Reads the body.
+export const errorCode = async (res) => {
+    const body = await bodyOf(res);
+    const error = isRecord(body) && isRecord(body['error']) ? body['error'] : {};
+    return typeof error['code'] === 'string' ? error['code'] : null;
+};
+// e.g. "503 AUTH_UNAVAILABLE": the status, and the envelope's code when there is one.
+const failureOf = async (res) => {
+    const code = await errorCode(res);
+    return code === null ? `${res.status}` : `${res.status} ${code}`;
+};
+const isMajor = (value) => value === null || (typeof value === 'number' && Number.isInteger(value));
+// A served resource and its etag, parsed; a string says what is wrong with it.
+const resourceOf = (data, etag) => {
+    if (!isRecord(data) || typeof etag !== 'string')
+        return 'unexpected answer';
+    const { lock, npmMajor } = data;
+    if (!(lock === null || isRecord(lock)) || !isMajor(npmMajor))
+        return 'unexpected answer';
+    const parsed = parseProfile(data['profile']);
+    if (!parsed.ok)
+        return `the profile in your account is invalid: ${parsed.errors.join('; ')}`;
+    return { profile: parsed.profile, readOnly: parsed.readOnly, lock, npmMajor, etag };
+};
+// meta.etag equals the ETag header on a 2xx; either will do.
+const etagOf = (body, header) => {
+    const meta = isRecord(body) && isRecord(body['meta']) ? body['meta'] : {};
+    return meta['etag'] ?? header;
+};
+const served = (body, header) => resourceOf(isRecord(body) ? body['data'] : null, etagOf(body, header));
+const unavailable = (reason) => ({ kind: 'unavailable', reason });
+const NO_PROFILE = '404 PROFILE_NOT_FOUND';
+// GET, conditional on the local copy's etag: 304 keeps it, 200 replaces it, 404 means none yet.
+export const pullProfile = async (fetch, etag, timeoutMs) => {
+    const headers = etag === null ? {} : { 'if-none-match': etag };
+    const res = await attempt(() => fetch(PROFILE_PATH, { headers, timeoutMs }));
+    if (typeof res === 'string')
+        return unavailable(res);
+    if (res.status === 304)
+        return { kind: 'current' };
+    if (res.status !== 200) {
+        // Any other 404 is an API without the profile route, not an account without a profile.
+        const failure = await failureOf(res);
+        return failure === NO_PROFILE ? { kind: 'none' } : unavailable(failure);
+    }
+    const doc = served(await bodyOf(res), res.headers.get('etag'));
+    return typeof doc === 'string' ? unavailable(doc) : { kind: 'found', doc };
+};
+// A 412 carries the account's current resource and etag (both null when it holds none).
+const conflictOf = (body) => {
+    const error = isRecord(body) && isRecord(body['error']) ? body['error'] : {};
+    const details = isRecord(error['details']) ? error['details'] : {};
+    if (details['current'] === null)
+        return { kind: 'conflict', current: null };
+    const current = resourceOf(details['current'], details['etag']);
+    if (typeof current === 'string')
+        throw new NotPushedError(`not pushed to your account (412: ${current})`);
+    return { kind: 'conflict', current };
+};
+const notPushed = (reason) => new NotPushedError(`not pushed to your account (${reason})`);
+// PUT the whole resource: If-Match replaces the copy it was pulled at, no etag creates it.
+export const pushProfile = async (fetch, body, etag) => {
+    const precondition = etag === null ? { 'if-none-match': '*' } : { 'if-match': etag };
+    const headers = { 'content-type': 'application/json', ...precondition };
+    const init = { method: 'PUT', headers, body: JSON.stringify(body) };
+    const res = await attempt(() => fetch(PROFILE_PATH, init));
+    if (typeof res === 'string')
+        throw notPushed(res);
+    if (res.status === 412)
+        return conflictOf(await bodyOf(res));
+    if (res.status !== 200 && res.status !== 201)
+        throw notPushed(await failureOf(res));
+    const stored = etagOf(await bodyOf(res), res.headers.get('etag'));
+    if (typeof stored !== 'string')
+        throw notPushed('unexpected answer');
+    return { kind: 'stored', etag: stored };
+};

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

@@ -0,0 +1,4 @@
+import { type Profile } from './schema.js';
+export declare const addExtension: (profile: Profile, name: string, spec: string, machineId: string, off: boolean) => Profile;
+export declare const dropExtension: (profile: Profile, name: string, machineId: string) => Profile;
+export declare const changeProfile: (change: (profile: Profile) => Profile) => Promise<Profile>;

package/dist/core/profile/edit.js

@@ -0,0 +1,27 @@
+import { loadMachine, setProfileSource } from './machine.js';
+import { editableProfile, mutateProfile } from './profile.js';
+import {} from './schema.js';
+const NO_ENTRY = { off: [], config: {}, extra: {} };
+// This machine's off list with `name` in or out; an entry is only created to turn one off.
+const withOff = (profile, machineId, name, off) => {
+    const self = profile.machines[machineId];
+    if (!self && !off)
+        return profile;
+    const rest = (self?.off ?? []).filter((pkg) => pkg !== name);
+    const entry = { ...NO_ENTRY, ...self, off: off ? [...rest, name] : rest };
+    return { ...profile, machines: { ...profile.machines, [machineId]: entry } };
+};
+// Installing a name again replaces its spec; without --off it loads on this machine again.
+export const addExtension = (profile, name, spec, machineId, off) => withOff({ ...profile, extensions: { ...profile.extensions, [name]: spec } }, machineId, name, off);
+// Other machines' off lists are theirs to keep.
+export const dropExtension = (profile, name, machineId) => {
+    const extensions = Object.fromEntries(Object.entries(profile.extensions).filter(([pkg]) => pkg !== name));
+    return withOff({ ...profile, extensions }, machineId, name, false);
+};
+// A file source stays `file`; any other profile changed here is now this machine's own copy.
+export const changeProfile = async (change) => {
+    const next = await mutateProfile(() => change(editableProfile()));
+    if ((await loadMachine()).profileSource !== 'file')
+        await setProfileSource('default');
+    return next;
+};

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

@@ -0,0 +1,18 @@
+export type ProfileSource = 'cloud' | 'file' | 'default';
+export interface MachineFile {
+    id: string;
+    name: string;
+    dev: Record<string, string>;
+    profileSource: ProfileSource;
+    accountId: string | null;
+    profileEtag: string | null;
+}
+export declare const NO_MACHINE: MachineFile;
+export declare const readMachine: () => MachineFile | null;
+export declare const loadMachine: () => Promise<MachineFile>;
+export declare const setProfileSource: (source: ProfileSource) => Promise<MachineFile>;
+export declare const setDev: (name: string, path: string | null) => Promise<MachineFile>;
+export declare const setCloud: (etag: string) => Promise<MachineFile>;
+export declare const setAccount: (accountId: string) => Promise<MachineFile>;
+export declare const forgetAccount: () => Promise<MachineFile>;
+export declare const accountMismatch: (machine: MachineFile, userId: string | null) => Error | null;

package/dist/core/profile/machine.js

@@ -0,0 +1,83 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { withFileLock } from '../../lib/fs/file-lock.js';
+import { isRecord, writeJsonAtomic } from '../../lib/fs/json-file.js';
+import { machinePath } from '../paths.js';
+// Without machine.json: no dev paths and no `off` list; reading never creates it.
+export const NO_MACHINE = {
+    id: '',
+    name: '',
+    dev: {},
+    profileSource: 'default',
+    accountId: null,
+    profileEtag: null,
+};
+const MACHINE_ID = /^m_[0-9a-f]{8}$/;
+const SOURCES = ['cloud', 'file', 'default'];
+const KEYS = Object.keys(NO_MACHINE).length;
+const isDevMap = (value) => isRecord(value) && Object.values(value).every((path) => typeof path === 'string');
+const isTextOrNull = (value) => value === null || (typeof value === 'string' && value !== '');
+// Strict: anything but the exact shape is treated as absent, so no old file is migrated.
+const parseMachine = (raw) => {
+    if (!isRecord(raw) || Object.keys(raw).length !== KEYS)
+        return null;
+    const { id, name, dev, profileSource, accountId, profileEtag } = raw;
+    if (typeof id !== 'string' || !MACHINE_ID.test(id))
+        return null;
+    if (typeof name !== 'string' || name === '' || !isDevMap(dev))
+        return null;
+    if (typeof profileSource !== 'string' || !SOURCES.includes(profileSource))
+        return null;
+    if (!isTextOrNull(accountId) || !isTextOrNull(profileEtag))
+        return null;
+    const source = profileSource;
+    return { id, name, dev, profileSource: source, accountId, profileEtag };
+};
+// Read only: null when absent or not exactly the current shape, and nothing is written.
+export const readMachine = () => {
+    try {
+        return parseMachine(JSON.parse(readFileSync(machinePath(), 'utf-8')));
+    }
+    catch {
+        return null;
+    }
+};
+const save = (machine) => {
+    mkdirSync(dirname(machinePath()), { recursive: true, mode: 0o700 });
+    writeJsonAtomic(machinePath(), machine);
+    return machine;
+};
+// Re-read under the lock so two first runs agree on one id.
+const readOrCreate = () => readMachine() ??
+    save({ ...NO_MACHINE, id: `m_${randomBytes(4).toString('hex')}`, name: hostname() });
+export const loadMachine = async () => readMachine() ?? withFileLock(machinePath(), readOrCreate);
+// Under the lock; written only when `change` changed something.
+const update = async (change) => withFileLock(machinePath(), () => {
+    const machine = readOrCreate();
+    const next = change(machine);
+    return isDeepStrictEqual(next, machine) ? machine : save(next);
+});
+export const setProfileSource = async (source) => update((machine) => ({ ...machine, profileSource: source }));
+// One dev entry by package name: a real path adds or replaces it, null removes it.
+export const setDev = async (name, path) => update((machine) => {
+    const dev = Object.fromEntries(Object.entries(machine.dev).filter(([pkg]) => pkg !== name));
+    return { ...machine, dev: path === null ? dev : { ...dev, [name]: path } };
+});
+// After a pull or a push: profile.json mirrors the account's profile at `etag`.
+export const setCloud = async (etag) => update((machine) => ({ ...machine, profileSource: 'cloud', profileEtag: etag }));
+export const setAccount = async (accountId) => update((machine) => ({ ...machine, accountId }));
+// `setup --disconnect`: no account; a copy of the account's profile becomes this machine's own.
+export const forgetAccount = async () => update((machine) => ({
+    ...machine,
+    accountId: null,
+    profileEtag: null,
+    profileSource: machine.profileSource === 'cloud' ? 'default' : machine.profileSource,
+}));
+// A machine stays with the account it was first set up with until `setup --disconnect`.
+export const accountMismatch = (machine, userId) => machine.accountId === null || userId === null || machine.accountId === userId
+    ? null
+    : new Error(`this machine is connected to account ${machine.accountId}, but you are signed in as ` +
+        `${userId}; run agentage setup --disconnect, then agentage setup`);

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

@@ -0,0 +1,11 @@
+import { type MachineFile } from './machine.js';
+import { type ConfigMap, type Profile } from './schema.js';
+export interface Effective {
+    install: Record<string, string>;
+    load: string[];
+    off: string[];
+    dev: Record<string, string>;
+    config: ConfigMap;
+}
+export declare const effective: (profile: Profile | null, machine: MachineFile) => Effective;
+export declare const keepMachine: (next: Profile, current: Profile | null, machineId: string) => Profile;

package/dist/core/profile/merge.js

@@ -0,0 +1,21 @@
+import {} from './machine.js';
+import {} from './schema.js';
+// Machine values replace shared ones per key; no deep merge, so arrays are replaced whole.
+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?.extensions };
+    const self = profile?.machines[machine.id];
+    const off = self?.off ?? [];
+    const kept = Object.keys(install).filter((name) => !off.includes(name));
+    const load = [...new Set([...kept, ...Object.keys(machine.dev)])].sort();
+    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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,68 @@
+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, 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');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+};
+// null only when profile.json is absent; an unreadable or invalid file reports its errors.
+export const readProfile = () => {
+    let raw;
+    try {
+        raw = readText(profilePath());
+    }
+    catch (err) {
+        return { ok: false, errors: [err.message] };
+    }
+    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>;