@agentage/cli 0.38.0 → 0.39.0

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

@@ -0,0 +1,16 @@
+export declare const ID_PATTERN: RegExp;
+export declare const DEFAULT_ENGINE = "^1";
+export declare const RESERVED_IDS: ReadonlySet<string>;
+export interface ManifestInfo {
+    name: string | null;
+    version: string | null;
+    id: string | null;
+    engine: string;
+    entry: string | null;
+    commands: string[];
+    peers: string[];
+    optionalPeers: string[];
+}
+export declare const entryOf: (pkg: Record<string, unknown>) => string | null;
+export declare const manifestInfo: (pkg: Record<string, unknown>) => ManifestInfo;
+export declare const manifestProblem: (pkg: string, info: ManifestInfo, api?: string) => string | null;

package/dist/core/loader/manifest.js

@@ -0,0 +1,66 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+import { PLUGIN_API_VERSION } from '../../plugin.js';
+import { isRange, satisfies } from '../semver-range.js';
+export const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const DEFAULT_ENGINE = '^1';
+const CORE_COMMANDS = ['setup', 'status', 'update', 'add', 'remove', 'help'];
+const DEVICE_NAMES = ['con', 'prn', 'aux', 'nul'].concat(...Array.from({ length: 10 }, (_, n) => [`com${n}`, `lpt${n}`]));
+export const RESERVED_IDS = new Set([...CORE_COMMANDS, ...DEVICE_NAMES]);
+const str = (value) => (typeof value === 'string' ? value : null);
+const record = (value) => (isRecord(value) ? value : {});
+const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+const fromConditions = (value, depth = 0) => {
+    if (typeof value === 'string')
+        return value;
+    if (!isRecord(value) || depth > 3)
+        return null;
+    return fromConditions(value['import'], depth + 1) ?? fromConditions(value['default'], depth + 1);
+};
+// Node semantics: a present `exports` field is authoritative, `main` only applies without it.
+export const entryOf = (pkg) => {
+    const exp = pkg['exports'];
+    if (exp === undefined)
+        return str(pkg['main']);
+    if (isRecord(exp) && '.' in exp)
+        return fromConditions(exp['.']);
+    const subpathsOnly = isRecord(exp) && Object.keys(exp).some((key) => key.startsWith('.'));
+    return subpathsOnly ? null : fromConditions(exp);
+};
+const optionalPeersOf = (meta) => Object.entries(meta)
+    .filter(([, m]) => isRecord(m) && m['optional'] === true)
+    .map(([name]) => name);
+export const manifestInfo = (pkg) => {
+    const agentage = record(pkg['agentage']);
+    return {
+        name: str(pkg['name']),
+        version: str(pkg['version']),
+        id: str(agentage['id']),
+        engine: str(record(pkg['engines'])['agentage']) ?? DEFAULT_ENGINE,
+        entry: entryOf(pkg),
+        commands: strings(record(agentage['contributes'])['commands']),
+        peers: Object.keys(record(pkg['peerDependencies'])),
+        optionalPeers: optionalPeersOf(record(pkg['peerDependenciesMeta'])),
+    };
+};
+const idProblem = (id) => {
+    if (id === null)
+        return 'agentage.id is missing';
+    if (!ID_PATTERN.test(id))
+        return `agentage.id "${id}" must match [a-z][a-z0-9-]*`;
+    return RESERVED_IDS.has(id) ? `agentage.id "${id}" is reserved` : null;
+};
+const engineProblem = (engine, api) => {
+    if (!isRange(engine))
+        return `engines.agentage "${engine}" is not a supported range`;
+    if (satisfies(api, engine))
+        return null;
+    return `engines.agentage "${engine}" does not match plugin API ${api}`;
+};
+// Static checks only: the manifest is read as data and the entry is never imported.
+export const manifestProblem = (pkg, info, api = PLUGIN_API_VERSION) => {
+    if (info.name !== pkg)
+        return `package.json name ${JSON.stringify(info.name)} is not ${pkg}`;
+    return (idProblem(info.id) ??
+        engineProblem(info.engine, api) ??
+        (info.entry === null ? 'no entry point (exports or main)' : null));
+};

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

@@ -0,0 +1,12 @@
+export declare const RUN_STATES: readonly ["ok", "failed", "invalid", "off", "blocked", "installed"];
+export type RunStateName = (typeof RUN_STATES)[number];
+export interface RunState {
+    at: string;
+    pid: number;
+    state: RunStateName;
+    error: string | null;
+}
+export interface RunStateDeps {
+    dir: () => string;
+}
+export declare const readRunState: (id: string, deps?: RunStateDeps) => RunState | null;

package/dist/core/loader/state.js

@@ -0,0 +1,21 @@
+import { join } from 'node:path';
+import { isRecord, readJson } from '../../lib/fs/json-file.js';
+import { stateDir } from '../paths.js';
+import { ID_PATTERN } from './manifest.js';
+export const RUN_STATES = ['ok', 'failed', 'invalid', 'off', 'blocked', 'installed'];
+const defaultDeps = { dir: stateDir };
+const isRunStateName = (value) => RUN_STATES.some((name) => name === value);
+const isRunState = (value) => isRecord(value) &&
+    typeof value['at'] === 'string' &&
+    typeof value['pid'] === 'number' &&
+    isRunStateName(value['state']) &&
+    (value['error'] === undefined || value['error'] === null || typeof value['error'] === 'string');
+// Reads the core's own record of the last run; plugin logs are never consulted.
+export const readRunState = (id, deps = defaultDeps) => {
+    if (!ID_PATTERN.test(id))
+        return null;
+    const found = readJson(join(deps.dir(), `${id}.json`), isRunState);
+    if (!found)
+        return null;
+    return { at: found.at, pid: found.pid, state: found.state, error: found.error ?? null };
+};

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

@@ -0,0 +1,7 @@
+import { type DiscoveredPlugin } from './discover.js';
+export type StaticState = 'installed' | 'off' | 'blocked' | 'invalid' | 'missing';
+export interface StaticResult {
+    state: StaticState;
+    error: string | null;
+}
+export declare const staticStates: (plugins: DiscoveredPlugin[], off: string[]) => Map<string, StaticResult>;

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 plugin code; `ok` and `failed` need a load.
+export const staticStates = (plugins, off) => {
+    const byPkg = new Map(plugins.map((p) => [p.pkg, p]));
+    const own = new Map(plugins.map((p) => [p.pkg, ownState(p, off, byPkg)]));
+    const walk = { byPkg, own, done: new Map() };
+    for (const p of plugins)
+        resolveState(p, walk);
+    return walk.done;
+};

package/dist/core/paths.d.ts

@@ -0,0 +1,4 @@
+export declare const profilePath: () => string;
+export declare const machinePath: () => string;
+export declare const stateDir: () => string;
+export declare const pluginsDir: () => string;

package/dist/core/paths.js

@@ -0,0 +1,6 @@
+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 pluginsDir = () => process.env['AGENTAGE_PLUGINS_DIR'] || join(getConfigDir(), 'plugins');

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;
+}
+export interface MachineDeps {
+    path: () => string;
+    read: (path: string) => unknown;
+    write: (path: string, machine: MachineFile) => void;
+    lock: <T>(path: string, fn: () => T) => Promise<T>;
+    hostname: () => string;
+    newId: () => string;
+}
+export declare const MACHINE_ID: RegExp;
+export declare const parseMachine: (raw: unknown) => MachineFile | null;
+export declare const loadMachine: (deps?: MachineDeps) => Promise<MachineFile>;

package/dist/core/profile/machine.js

@@ -0,0 +1,60 @@
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+import { withFileLock } from '../../lib/fs/file-lock.js';
+import { isRecord, writeJsonAtomic } from '../../lib/fs/json-file.js';
+import { machinePath } from '../paths.js';
+export const MACHINE_ID = /^m_[0-9a-f]{8}$/;
+const SOURCES = ['cloud', 'file', 'default'];
+const readRaw = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+const defaultDeps = {
+    path: machinePath,
+    read: readRaw,
+    write: (path, machine) => {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeJsonAtomic(path, machine);
+    },
+    lock: (path, fn) => withFileLock(path, fn),
+    hostname: () => hostname(),
+    newId: () => `m_${randomBytes(4).toString('hex')}`,
+};
+const isDevMap = (value) => isRecord(value) && Object.values(value).every((path) => typeof path === 'string');
+// Strict: anything but the exact v1 shape is treated as absent, so no old file is migrated.
+export const parseMachine = (raw) => {
+    if (!isRecord(raw) || Object.keys(raw).length !== 4)
+        return null;
+    const { id, name, dev, profileSource } = raw;
+    if (typeof id !== 'string' || !MACHINE_ID.test(id))
+        return null;
+    if (typeof name !== 'string' || name === '')
+        return null;
+    if (!isDevMap(dev) || typeof profileSource !== 'string' || !SOURCES.includes(profileSource))
+        return null;
+    return { id, name, dev, profileSource: profileSource };
+};
+// Re-read under the lock so two first runs agree on one id.
+const create = (deps, path) => {
+    const fresh = parseMachine(deps.read(path));
+    if (fresh)
+        return fresh;
+    const machine = {
+        id: deps.newId(),
+        name: deps.hostname(),
+        dev: {},
+        profileSource: 'default',
+    };
+    deps.write(path, machine);
+    return machine;
+};
+export const loadMachine = async (deps = defaultDeps) => {
+    const path = deps.path();
+    return parseMachine(deps.read(path)) ?? deps.lock(path, () => create(deps, path));
+};

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 mergeConfig: (shared: ConfigMap, local: ConfigMap) => ConfigMap;
+export declare const effective: (profile: Profile | null, machine: MachineFile) => Effective;

package/dist/core/profile/merge.js

@@ -0,0 +1,16 @@
+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 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 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 };
+};

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

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

package/dist/core/profile/profile.js

@@ -0,0 +1,34 @@
+import { readFileSync } from 'node:fs';
+import { profilePath } from '../paths.js';
+import { parseProfile } from './schema.js';
+const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        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) => {
+    let raw;
+    try {
+        raw = deps.readText(deps.path());
+    }
+    catch (err) {
+        return { ok: false, errors: [`profile.json: ${messageOf(err)}`] };
+    }
+    return raw === null ? null : parseText(raw);
+};

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

@@ -0,0 +1,26 @@
+export declare const SCHEMA_VERSION = 1;
+export type ConfigMap = Record<string, Record<string, unknown>>;
+export interface MachineEntry {
+    off: string[];
+    config: ConfigMap;
+    extra: Record<string, unknown>;
+}
+export interface Profile {
+    version: number;
+    plugins: Record<string, string>;
+    config: ConfigMap;
+    machines: Record<string, MachineEntry>;
+    extra: Record<string, unknown>;
+}
+export type ProfileParse = {
+    ok: true;
+    profile: Profile;
+    readOnly: boolean;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+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

@@ -0,0 +1,143 @@
+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 MACHINE_KEYS = ['off', 'config'];
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[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;
+const LOCAL_PATH = /^(?:\.{1,2}[/\\]|~?[/\\])/;
+const EMPTY_MACHINE = { off: [], config: {}, extra: {} };
+const USE_INSTEAD = 'use a semver range or an https: tarball URL';
+const at = (name) => `[${JSON.stringify(name)}]`;
+const fail = (issues, message, fallback) => {
+    issues.errors.push(message);
+    return fallback;
+};
+const httpsProblem = (spec) => {
+    try {
+        const host = new URL(spec).hostname;
+        return LOOPBACK_HOST.test(host) ? 'loopback URLs are refused' : null;
+    }
+    catch {
+        return 'is not a valid https: URL';
+    }
+};
+export const specProblem = (spec) => {
+    const refused = REFUSED_PREFIX.exec(spec)?.[1];
+    if (refused)
+        return `${refused.toLowerCase()}: specs are refused; ${USE_INSTEAD}`;
+    if (/^https:/i.test(spec))
+        return httpsProblem(spec);
+    if (LOCAL_PATH.test(spec))
+        return 'local paths are dev-only and belong in machine.json';
+    if (OTHER_PROTOCOL.test(spec))
+        return `unsupported spec; ${USE_INSTEAD}`;
+    return isRange(spec) ? null : `is not a semver range; ${USE_INSTEAD}`;
+};
+const pluginProblem = (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) => {
+    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);
+        if (problem)
+            issues.errors.push(`plugins${at(name)}: ${problem}`);
+        else
+            plugins[name] = String(spec);
+    }
+    return plugins;
+};
+const parseConfig = (value, path, issues) => {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        return fail(issues, `${path}: must be an object`, {});
+    const config = {};
+    for (const [id, slice] of Object.entries(value)) {
+        if (isRecord(slice))
+            config[id] = slice;
+        else
+            issues.errors.push(`${path}${at(id)}: must be an object`);
+    }
+    return config;
+};
+const extraKeys = (doc, known, path, issues) => {
+    const extra = Object.fromEntries(Object.entries(doc).filter(([key]) => !known.includes(key)));
+    for (const key of Object.keys(extra))
+        issues.warnings.push(`${path}: unknown key "${key}" kept`);
+    return extra;
+};
+const parseOff = (value, path, issues) => {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value) && value.every((name) => typeof name === 'string'))
+        return value;
+    return fail(issues, `${path}.off: must be an array of package names`, []);
+};
+const parseMachine = (value, path, issues) => {
+    if (!isRecord(value))
+        return fail(issues, `${path}: must be an object`, EMPTY_MACHINE);
+    return {
+        off: parseOff(value['off'], path, issues),
+        config: parseConfig(value['config'], `${path}.config`, issues),
+        extra: extraKeys(value, MACHINE_KEYS, path, issues),
+    };
+};
+const parseMachines = (value, issues) => {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        return fail(issues, 'machines: must be an object', {});
+    return Object.fromEntries(Object.entries(value).map(([id, entry]) => [
+        id,
+        parseMachine(entry, `machines${at(id)}`, issues),
+    ]));
+};
+const parseVersionField = (value, issues) => {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 1)
+        return value;
+    const got = value === undefined ? 'missing' : JSON.stringify(value);
+    issues.errors.push(`version: must be ${SCHEMA_VERSION} (got ${got})`);
+    return SCHEMA_VERSION;
+};
+const readOnlyWarning = (version) => `version: ${version} is newer than this CLI understands (${SCHEMA_VERSION}); read-only`;
+export const parseProfile = (doc) => {
+    if (!isRecord(doc))
+        return { ok: false, errors: ['profile.json: must be a JSON object'] };
+    const issues = { errors: [], warnings: [] };
+    const profile = {
+        version: parseVersionField(doc['version'], issues),
+        plugins: parsePlugins(doc['plugins'], issues),
+        config: parseConfig(doc['config'], 'config', issues),
+        machines: parseMachines(doc['machines'], issues),
+        extra: extraKeys(doc, TOP_KEYS, 'profile.json', issues),
+    };
+    if (issues.errors.length > 0)
+        return { ok: false, errors: issues.errors };
+    const readOnly = profile.version > SCHEMA_VERSION;
+    if (readOnly)
+        issues.warnings.push(readOnlyWarning(profile.version));
+    return { ok: true, profile, readOnly, warnings: issues.warnings };
+};
+// The inverse of parseProfile: unknown keys go back where they were found.
+export const toDocument = (profile) => ({
+    version: profile.version,
+    plugins: profile.plugins,
+    config: profile.config,
+    machines: Object.fromEntries(Object.entries(profile.machines).map(([id, m]) => [
+        id,
+        { off: m.off, config: m.config, ...m.extra },
+    ])),
+    ...profile.extra,
+});

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

@@ -0,0 +1,16 @@
+interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+type Op = '<' | '<=' | '>' | '>=' | '=';
+interface Comparator {
+    op: Op;
+    v: Version;
+}
+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 {};

package/dist/core/semver-range.js

@@ -0,0 +1,116 @@
+const WILD = /^[xX*]$/;
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const PARTIAL_RE = /^v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const COMPARATOR_RE = /^(\^|~|>=|<=|>|<|=)?(.+)$/;
+const ver = (major, minor, patch, pre = null) => ({
+    major,
+    minor,
+    patch,
+    pre,
+});
+export const parseVersion = (text) => {
+    const m = VERSION_RE.exec(text.trim());
+    if (!m)
+        return null;
+    return ver(Number(m[1]), Number(m[2]), Number(m[3]), m[4] ?? null);
+};
+const parsePartial = (text) => {
+    const m = PARTIAL_RE.exec(text);
+    if (!m)
+        return null;
+    const raw = [m[1], m[2], m[3]];
+    const nums = [];
+    for (const part of raw) {
+        if (part === undefined || WILD.test(part))
+            break;
+        nums.push(Number(part));
+    }
+    const concreteAfterWild = raw.slice(nums.length).some((p) => p !== undefined && !WILD.test(p));
+    if (concreteAfterWild || (m[4] !== undefined && nums.length < 3))
+        return null;
+    return { nums, pre: m[4] ?? null };
+};
+const lower = (p) => ver(p.nums[0] ?? 0, p.nums[1] ?? 0, p.nums[2] ?? 0, p.pre);
+// Exclusive upper bound one step above part `i`; the `-0` keeps that version's prereleases out.
+const bump = (p, i) => {
+    const [a = 0, b = 0, c = 0] = p.nums;
+    if (i <= 0)
+        return ver(a + 1, 0, 0, '0');
+    return i === 1 ? ver(a, b + 1, 0, '0') : ver(a, b, c + 1, '0');
+};
+const span = (p, i) => [
+    { op: '>=', v: lower(p) },
+    { op: '<', v: bump(p, i) },
+];
+const exact = (p) => p.nums.length === 3 ? [{ op: '=', v: lower(p) }] : span(p, p.nums.length - 1);
+const caretIndex = (nums) => {
+    const i = nums.findIndex((n) => n !== 0);
+    return i === -1 ? nums.length - 1 : i;
+};
+const bounded = (op, p) => {
+    const n = p.nums.length;
+    if (op === '>=')
+        return [{ op, v: lower(p) }];
+    if (op === '>')
+        return n === 3 ? [{ op, v: lower(p) }] : [{ op: '>=', v: bump(p, n - 1) }];
+    if (op === '<')
+        return [{ op, v: n === 3 ? lower(p) : { ...lower(p), pre: '0' } }];
+    return n === 3 ? [{ op, v: lower(p) }] : [{ op: '<', v: bump(p, n - 1) }];
+};
+const desugar = (op, p) => {
+    if (p.nums.length === 0)
+        return op === '>' || op === '<' ? null : [];
+    if (op === undefined || op === '=')
+        return exact(p);
+    if (op === '~')
+        return span(p, Math.min(p.nums.length - 1, 1));
+    if (op === '^')
+        return span(p, caretIndex(p.nums));
+    return bounded(op, p);
+};
+const parseComparator = (token) => {
+    const m = COMPARATOR_RE.exec(token);
+    const partial = m?.[2] === undefined ? null : parsePartial(m[2]);
+    return m && partial ? desugar(m[1], partial) : null;
+};
+const parseSet = (set) => {
+    const tokens = set
+        .replace(/(\^|~|>=|<=|>|<|=)\s+/g, '$1')
+        .trim()
+        .split(/\s+/);
+    if (tokens.length === 0 || tokens[0] === '')
+        return null;
+    const parsed = tokens.map(parseComparator);
+    return parsed.some((c) => c === null) ? null : parsed.flatMap((c) => c ?? []);
+};
+export const parseRange = (range) => {
+    const sets = range.split('||').map(parseSet);
+    return sets.some((s) => s === null) ? null : sets.map((s) => s ?? []);
+};
+export const isRange = (range) => parseRange(range) !== null;
+// Prereleases sort below their release, compared as plain strings (no identifier splitting).
+const comparePre = (a, b) => {
+    if (a === b)
+        return 0;
+    if (a === null || b === null)
+        return a === null ? 1 : -1;
+    return a < b ? -1 : 1;
+};
+const compareVersions = (a, b) => a.major - b.major || a.minor - b.minor || a.patch - b.patch || comparePre(a.pre, b.pre);
+const holds = (c, v) => {
+    const d = compareVersions(v, c.v);
+    if (c.op === '=')
+        return d === 0;
+    if (c.op === '<')
+        return d < 0;
+    if (c.op === '<=')
+        return d <= 0;
+    return c.op === '>' ? d > 0 : d >= 0;
+};
+export const satisfies = (version, range) => {
+    const v = parseVersion(version);
+    const sets = parseRange(range);
+    if (!v || !sets)
+        return false;
+    return sets.some((set) => set.every((c) => holds(c, v)));
+};

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

@@ -1,7 +1,8 @@
 import { type AuthState } from '../fs/config.js';
+import { 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 authedGet: <T>(auth: AuthState, links: Links, url: string) => Promise<T>;
-export declare const authedPost: (auth: AuthState, links: Links, url: string, body: unknown) => Promise<Response>;
+export declare const authedFetch: (auth: AuthState, links: Links, url: string, init?: CliRequestInit) => Promise<Response>;
+export declare const authedJson: <T>(auth: AuthState, links: Links, url: string, init?: CliRequestInit) => Promise<T>;
 export { introspectToken, type TokenSession } from './introspect.js';