@agentage/cli 0.39.0 → 0.41.0

package/dist/core/installer/resolve.js

@@ -0,0 +1,140 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { isRecord, readJson } from '../../lib/fs/json-file.js';
+import {} from '../../lib/npm/npm-cli.js';
+import { PACKAGE_NAME, specProblem } from '../profile/schema.js';
+import { cliGate, needs, newestCompatible, parsePublished } from './compat.js';
+import { isKitShaped } from '../loader/kit-manifest.js';
+import { lastLines } from './installer.js';
+import {} from './npm.js';
+// Every release: a range, not `*`, which npm view reads as the `latest` tag alone.
+const EVERY_RELEASE = '>=0.0.0';
+const LOCAL = /^\.{1,2}(?:[/\\]|$)/;
+const REFUSED = /^(npm|github|file|http):/i;
+const PROTOCOL = /^[a-z][a-z0-9+.-]*:/i;
+const HTTPS = /^https:/i;
+const FULL_PREFIX = 'agentage-extension-';
+const INSTEAD = 'install a package name, an https: tarball URL or a local path (./path)';
+// `memory` -> the two names it may be published under; any other name stands for itself.
+export const candidatesFor = (name) => name.startsWith('@') || name.startsWith(FULL_PREFIX)
+    ? [name]
+    : [`@agentage/extension-${name}`, `${FULL_PREFIX}${name}`];
+const refusal = (input) => {
+    const scheme = REFUSED.exec(input)?.[1];
+    if (scheme)
+        return `${scheme.toLowerCase()}: is refused; ${INSTEAD}`;
+    return PROTOCOL.test(input) && !HTTPS.test(input) ? `unsupported; ${INSTEAD}` : null;
+};
+const folder = (input) => {
+    try {
+        return realpathSync(resolve(input));
+    }
+    catch {
+        return null;
+    }
+};
+// Its own package.json names the package and declares agentage.id, as discovery will check.
+const devExtension = (input) => {
+    const path = folder(input);
+    const manifest = path === null ? null : readJson(join(path, 'package.json'), isRecord);
+    const agentage = manifest?.['agentage'];
+    const name = manifest?.['name'];
+    if (path === null || typeof name !== 'string' || !isRecord(agentage) || !agentage['id'])
+        throw new Error(`${input}: not an extension folder (no package.json with a name and agentage.id)`);
+    return { kind: 'dev', name, path, kit: isKitShaped(agentage) };
+};
+// The first candidate the registry has; a missing one moves on to the next.
+const firstFound = async (specs, input, look) => {
+    for (const spec of specs) {
+        const found = await look(spec);
+        if (found)
+            return found;
+    }
+    throw new Error(`${input}: not found; tried ${specs.join(', ')}`);
+};
+const fromUrl = async (url, look) => {
+    const problem = specProblem(url);
+    if (problem)
+        throw new Error(`${url}: ${problem}`);
+    const { name } = await firstFound([url], url, look);
+    return { kind: 'package', name, spec: url, skipped: [] };
+};
+const pinned = (input, name, published) => {
+    const gate = cliGate();
+    const { version, skipped } = newestCompatible(published, gate);
+    if (version !== null)
+        return { kind: 'package', name, spec: `^${version}`, skipped };
+    const newest = skipped[0] === undefined ? '' : ` (${needs(skipped[0])})`;
+    const api = skipped[0]?.kit ? `kit ${gate.kit}` : `extension API ${gate.api}`;
+    throw new Error(`${input}: no published version works with ${api}${newest}`);
+};
+// The first candidate the registry has, at its newest version this CLI can load.
+const compatible = async (input, name, versions) => {
+    const names = candidatesFor(name);
+    for (const candidate of names) {
+        const published = await versions(candidate);
+        if (published !== null)
+            return pinned(input, candidate, published);
+    }
+    throw new Error(`${input}: not found; tried ${names.join(', ')}`);
+};
+// `name@range` keeps the range; without one, the newest compatible version as `^<version>`.
+const fromName = async (input, registry) => {
+    const at = input.indexOf('@', 1);
+    const name = at === -1 ? input : input.slice(0, at);
+    const range = at === -1 ? null : input.slice(at + 1);
+    if (!PACKAGE_NAME.test(name))
+        throw new Error(`${input}: not a package name`);
+    const problem = range === null ? null : specProblem(range);
+    if (problem)
+        throw new Error(`${input}: ${problem}`);
+    if (range === null)
+        return compatible(input, name, registry.versions);
+    const specs = candidatesFor(name).map((c) => `${c}@${range}`);
+    const found = await firstFound(specs, input, registry.find);
+    return { kind: 'package', name: found.name, spec: range, skipped: [] };
+};
+// A local path, then refused schemes, then a tarball URL, then a package or short name.
+export const resolveName = async (input, registry) => {
+    if (LOCAL.test(input) || isAbsolute(input))
+        return devExtension(input);
+    const refused = refusal(input);
+    if (refused)
+        throw new Error(`${input}: ${refused}`);
+    return HTTPS.test(input) ? fromUrl(input, registry.find) : fromName(input, registry);
+};
+const parseFound = (stdout) => {
+    try {
+        const [first] = JSON.parse(stdout);
+        const { name, version } = isRecord(first) ? first : {};
+        return typeof name === 'string' && typeof version === 'string' ? { name, version } : null;
+    }
+    catch {
+        return null;
+    }
+};
+// E404 means absent; any other failure, or an answer that does not parse, stops the install.
+const answerOf = (spec, res, parse) => {
+    if (res.code !== 0 && /\bE404\b/.test(`${res.stdout}\n${res.stderr}`))
+        return null;
+    const parsed = res.code === 0 ? parse(res.stdout) : null;
+    if (parsed !== null)
+        return parsed;
+    // With --json, npm repeats its stderr lines as a JSON object on stdout.
+    const why = lastLines(res.stderr.trim() === '' ? res.stdout : res.stderr);
+    throw new Error(`npm could not read ${spec} (exit ${res.code})\n${why}`);
+};
+// npm is prepared on the first question, through the registries the profile routes.
+export const registryLookup = (prepare, registries) => {
+    let manifest;
+    const ask = async (command, spec) => {
+        manifest ??= prepare();
+        return (await manifest)(command, spec, registries);
+    };
+    const versions = async (name) => {
+        const spec = `${name}@${EVERY_RELEASE}`;
+        return answerOf(spec, await ask('view', spec), parsePublished);
+    };
+    const find = async (spec) => answerOf(spec, await ask('pack', spec), parseFound);
+    return { find, versions };
+};

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

@@ -0,0 +1,21 @@
+export declare const LOCK_FILE = "package-lock.json";
+export interface TreeFiles {
+    manifest: string;
+    npmrc: string;
+    lock: string | null;
+}
+export declare const sortedSet: (install: Record<string, string>) => Record<string, string>;
+export declare const manifestText: (install: Record<string, string>) => string;
+export declare const npmrcText: (registries: Record<string, string>) => string;
+export declare const treeName: (entries: string[]) => string;
+export declare const treePath: (extensionsDir: string, name: string) => string;
+export declare const isComplete: (extensionsDir: string, name: string) => boolean;
+export declare const readText: (path: string) => string | null;
+export declare const clearStaging: (extensionsDir: string) => void;
+export declare const stageTree: (extensionsDir: string, files: TreeFiles) => string;
+export declare const discardTree: (dir: string) => void;
+export declare const commitTree: (extensionsDir: string, staging: string, name: string) => void;
+export declare const collectTrees: (extensionsDir: string, keep: string) => void;
+export declare const pointCurrent: (extensionsDir: string, name: string) => void;
+export declare const promoteFiles: (extensionsDir: string, files: Omit<TreeFiles, "npmrc">) => void;
+export declare const withInstallLock: <T>(extensionsDir: string, fn: () => Promise<T>) => Promise<T>;

package/dist/core/installer/tree.js

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { refreshFileLock, withFileLock } from '../../lib/fs/file-lock.js';
+import { writeTextAtomic } from '../../lib/fs/json-file.js';
+export const LOCK_FILE = 'package-lock.json';
+const MANIFEST_FILE = 'package.json';
+const TREES = 'trees';
+const COMPLETE = '.complete';
+// A fixed name keeps the lock's root entry identical in every tree directory.
+const MANIFEST_NAME = 'agentage-extensions';
+// Dot-prefixed: `extensions/current` only accepts names starting with a letter or digit.
+const STAGING_PREFIX = '.staging-';
+// An install runs for minutes: a long TTL plus a heartbeat keep a live holder from looking dead.
+const INSTALL_LOCK = { ttlMs: 2 * 60_000, hardStaleMs: 60 * 60_000, maxWaitMs: 30 * 60_000 };
+const HEARTBEAT_MS = 20_000;
+export const sortedSet = (install) => Object.fromEntries(Object.entries(install).sort(([a], [b]) => (a < b ? -1 : 1)));
+// Same install set, same bytes: no scripts, nothing machine-specific.
+export const manifestText = (install) => `${JSON.stringify({ name: MANIFEST_NAME, private: true, dependencies: sortedSet(install) }, null, 2)}\n`;
+// npm's own per-scope registry lines; every other package uses the --registry default.
+export const npmrcText = (registries) => Object.entries(sortedSet(registries))
+    .map(([scope, url]) => `${scope}:registry=${url}\n`)
+    .join('');
+// Content-addressed: the same normalized lock names the same tree on every machine.
+export const treeName = (entries) => createHash('sha256').update(entries.join('\n')).digest('hex').slice(0, 16);
+export const treePath = (extensionsDir, name) => join(extensionsDir, TREES, name);
+export const isComplete = (extensionsDir, name) => existsSync(join(treePath(extensionsDir, name), COMPLETE));
+export const readText = (path) => {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+};
+const remove = (path) => rmSync(path, { recursive: true, force: true });
+// Only called under the install lock, so every staging dir left over is from a dead run.
+export const clearStaging = (extensionsDir) => {
+    const trees = join(extensionsDir, TREES);
+    if (!existsSync(trees))
+        return;
+    for (const name of readdirSync(trees).filter((n) => n.startsWith(STAGING_PREFIX)))
+        remove(join(trees, name));
+};
+export const stageTree = (extensionsDir, files) => {
+    const trees = join(extensionsDir, TREES);
+    mkdirSync(trees, { recursive: true, mode: 0o700 });
+    const dir = mkdtempSync(join(trees, STAGING_PREFIX));
+    writeFileSync(join(dir, MANIFEST_FILE), files.manifest);
+    writeFileSync(join(dir, '.npmrc'), files.npmrc);
+    if (files.lock !== null)
+        writeFileSync(join(dir, LOCK_FILE), files.lock);
+    return dir;
+};
+export const discardTree = (dir) => remove(dir);
+// `.complete` lands before the rename, so a tree appears finished or not at all.
+export const commitTree = (extensionsDir, staging, name) => {
+    const target = treePath(extensionsDir, name);
+    if (existsSync(join(target, COMPLETE)))
+        return discardTree(staging);
+    remove(target);
+    writeFileSync(join(staging, COMPLETE), '');
+    renameSync(staging, target);
+};
+// Only `keep` stays: the lock in the extensions root can rebuild any other tree. Staging dirs are
+// left to clearStaging, so a run never removes another's.
+export const collectTrees = (extensionsDir, keep) => {
+    const trees = join(extensionsDir, TREES);
+    if (!existsSync(trees))
+        return;
+    for (const name of readdirSync(trees))
+        if (name !== keep && !name.startsWith(STAGING_PREFIX))
+            remove(join(trees, name));
+};
+export const pointCurrent = (extensionsDir, name) => writeTextAtomic(join(extensionsDir, 'current'), `${name}\n`);
+// The extensions root always describes the tree `current` names, never a failed attempt.
+export const promoteFiles = (extensionsDir, files) => {
+    writeTextAtomic(join(extensionsDir, MANIFEST_FILE), files.manifest);
+    const lock = join(extensionsDir, LOCK_FILE);
+    if (files.lock === null)
+        remove(lock);
+    else
+        writeTextAtomic(lock, files.lock);
+};
+const heartbeat = async (target, fn) => {
+    const beat = setInterval(() => refreshFileLock(target), HEARTBEAT_MS);
+    beat.unref();
+    try {
+        return await fn();
+    }
+    finally {
+        clearInterval(beat);
+    }
+};
+// A second run waits on `<extensionsDir>/install.lock` instead of racing the first one.
+export const withInstallLock = (extensionsDir, fn) => {
+    const target = join(extensionsDir, 'install');
+    const onWait = () => console.error(`waiting for another install to finish (${target}.lock)`);
+    return withFileLock(target, () => heartbeat(target, fn), { ...INSTALL_LOCK, onWait });
+};

package/dist/core/kit-version.d.ts

@@ -0,0 +1 @@
+export declare const kitVersion: () => string;

package/dist/core/kit-version.js

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module';
+import { isRecord, readJson } from '../lib/fs/json-file.js';
+let cached;
+const read = () => {
+    try {
+        const path = createRequire(import.meta.url).resolve('@agentage/extension/package.json');
+        const version = readJson(path, isRecord)?.['version'];
+        return typeof version === 'string' ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+};
+// The kit's own version (KIT_VERSION), read as data so startup never loads the kit's code.
+export const kitVersion = () => (cached ??= read());

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

@@ -0,0 +1,7 @@
+export interface CheckedConfig {
+    config: Record<string, unknown>;
+    secrets: string[];
+    descriptions: Record<string, string>;
+    problem: string | null;
+}
+export declare const checkConfig: (id: string, configuration: Record<string, unknown>, slice: Record<string, unknown>) => CheckedConfig;

package/dist/core/loader/config.js

@@ -0,0 +1,59 @@
+import { isRecord } from '../../lib/fs/json-file.js';
+const TYPES = {
+    string: (value) => typeof value === 'string',
+    number: (value) => typeof value === 'number',
+    boolean: (value) => typeof value === 'boolean',
+    array: (value) => Array.isArray(value),
+    object: isRecord,
+};
+const typeOf = (value) => {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'array' : typeof value;
+};
+const quoted = (value) => JSON.stringify(value);
+const declarationProblem = (key, declared) => {
+    const type = declared['type'];
+    if (typeof type !== 'string' || !TYPES[type])
+        return `agentage.configuration.${key}.type must be one of ${Object.keys(TYPES).join(', ')}`;
+    const allowed = declared['enum'];
+    if (allowed !== undefined && !Array.isArray(allowed))
+        return `agentage.configuration.${key}.enum must be an array`;
+    return null;
+};
+// Compared as JSON, so an enum of arrays or objects works too.
+const valueProblem = (name, declared, value) => {
+    const type = String(declared['type']);
+    if (value === undefined)
+        return null;
+    if (!TYPES[type]?.(value))
+        return `${name}: must be of type ${type} (got ${typeOf(value)})`;
+    const allowed = declared['enum'];
+    if (!Array.isArray(allowed) || allowed.some((v) => quoted(v) === quoted(value)))
+        return null;
+    return `${name}: must be one of ${allowed.map(quoted).join(', ')} (got ${quoted(value)})`;
+};
+const declarations = (configuration) => Object.entries(configuration).map(([key, entry]) => ({
+    key,
+    declared: isRecord(entry) ? entry : {},
+}));
+const descriptionsOf = (all) => Object.fromEntries(all.flatMap(({ key, declared }) => {
+    const text = declared['description'];
+    return typeof text === 'string' ? [[key, text]] : [];
+}));
+// The profile's slice for one extension, checked against what its manifest declares.
+export const checkConfig = (id, configuration, slice) => {
+    const all = declarations(configuration);
+    const secrets = all.filter((d) => d.declared['secret'] === true).map((d) => d.key);
+    const config = Object.fromEntries(Object.entries(slice).filter(([k]) => !secrets.includes(k)));
+    const descriptions = descriptionsOf(all);
+    for (const { key, declared } of all.filter((d) => !secrets.includes(d.key))) {
+        const value = key in slice ? slice[key] : declared['default'];
+        const problem = declarationProblem(key, declared) ?? valueProblem(`config.${id}.${key}`, declared, value);
+        if (problem)
+            return { config: {}, secrets: [], descriptions: {}, problem };
+        if (value !== undefined)
+            config[key] = value;
+    }
+    return { config, secrets, descriptions, problem: null };
+};

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

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type Disposable, type ExtensionContext, type ExtensionUse } from '../../extension.js';
+import { type DiscoveredExtension } from './discover.js';
+export interface StagedContext {
+    ctx: ExtensionContext;
+    program: Command;
+    subscriptions: Disposable[];
+    revoke: () => void;
+    close: () => void;
+}
+export interface ContextInput {
+    ext: DiscoveredExtension;
+    use: ExtensionUse;
+    template: Command;
+}
+export declare const createContext: ({ ext, use, template }: ContextInput) => StagedContext;

package/dist/core/loader/ctx.js

@@ -0,0 +1,76 @@
+import { Command } from 'commander';
+import {} from '../../extension.js';
+import { cacheDir, dataDir } from '../paths.js';
+import {} from './discover.js';
+import { extensionLog } from './log.js';
+import { secretsFor } from './secrets.js';
+import { readRunState } from './state.js';
+const gate = (fail) => {
+    let shut = false;
+    const pass = (fn) => (...args) => {
+        if (shut)
+            throw new Error(fail());
+        return fn(...args);
+    };
+    return { pass, shut: () => void (shut = true) };
+};
+const gates = (id) => {
+    const revoked = gate(() => `the context of extension ${id} was revoked`);
+    const closed = gate(() => `registration closed: ${id} adds commands and subscriptions in register`);
+    return {
+        live: revoked.pass,
+        staging: (fn) => revoked.pass(closed.pass(fn)),
+        revoke: revoked.shut,
+        close: closed.shut,
+    };
+};
+// Run at once on the extension's Command, so a name it may not claim fails its register.
+const addCommands = (ext, program, fns) => {
+    for (const fn of fns) {
+        const before = program.commands.length;
+        fn(program);
+        const added = program.commands.slice(before).map((command) => command.name());
+        const stray = added.find((name) => !ext.commands.includes(name));
+        if (stray)
+            throw new Error(`command "${stray}" is not in agentage.contributes.commands`);
+    }
+};
+const liveSecrets = (id, live) => {
+    const secrets = secretsFor(id);
+    return Object.freeze({
+        get: live(secrets.get),
+        set: live(secrets.set),
+        delete: live(secrets.delete),
+    });
+};
+const contextOf = (ext, live, staged) => {
+    const id = ext.id ?? '';
+    return Object.freeze({
+        id,
+        version: ext.version ?? '0.0.0',
+        previousVersion: readRunState(id)?.lastOk ?? null,
+        mode: ext.source === 'dev' ? 'dev' : 'installed',
+        config: Object.freeze({ ...ext.config }),
+        secrets: liveSecrets(id, live),
+        data: dataDir(id),
+        cache: cacheDir(id),
+        log: live(extensionLog(id)),
+        commands: staged.commands,
+        use: staged.use,
+        subscriptions: staged.subscriptions,
+    });
+};
+// One per load attempt: on a throw or a timeout the loader revokes it, and every method throws.
+export const createContext = ({ ext, use, template }) => {
+    const { live, staging, revoke, close } = gates(ext.id ?? '');
+    const program = new Command(template.name()).copyInheritedSettings(template);
+    const subscriptions = [];
+    const add = (...fns) => addCommands(ext, program, fns);
+    const push = (...items) => void subscriptions.push(...items);
+    const ctx = contextOf(ext, live, {
+        commands: Object.freeze({ add: staging(add) }),
+        use: live(use),
+        subscriptions: Object.freeze({ push: staging(push) }),
+    });
+    return { ctx, program, subscriptions, revoke, close };
+};

package/dist/core/loader/dev-path.d.ts

@@ -0,0 +1 @@
+export declare const unsafeDevPath: (dir: string, uid: number | undefined) => string | null;

package/dist/core/loader/dev-path.js

@@ -0,0 +1,20 @@
+import { statSync } from 'node:fs';
+const statOf = (dir) => {
+    try {
+        return statSync(dir);
+    }
+    catch {
+        return null;
+    }
+};
+// Whoever can write a dev folder runs code as you; root may own it. No uid (Windows): unchecked.
+export const unsafeDevPath = (dir, uid) => {
+    const stat = uid === undefined ? null : statOf(dir);
+    if (stat === null)
+        return null;
+    if ((stat.mode & 0o002) !== 0)
+        return `dev path ${dir} is world-writable`;
+    if (stat.uid !== uid && stat.uid !== 0)
+        return `dev path ${dir} is owned by uid ${stat.uid}`;
+    return null;
+};

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

@@ -1,33 +1,39 @@
-export type PluginSource = 'tree' | 'dev';
-export interface DiscoveredPlugin {
+import { type ConfigMap } from '../profile/schema.js';
+import { type KitCommand } from './kit-manifest.js';
+import { type ManifestKind } from './manifest.js';
+export type ExtensionSource = 'tree' | 'dev';
+export interface DiscoveredExtension {
     pkg: string;
-    source: PluginSource;
+    kind: ManifestKind;
+    source: ExtensionSource;
     dir: string;
     version: string | null;
     id: string | null;
     entry: string | null;
     commands: string[];
+    kitCommands: KitCommand[];
     peers: string[];
     optionalPeers: string[];
+    config: Record<string, unknown>;
+    secrets: string[];
+    descriptions: Record<string, string>;
     problem: string | null;
     missing: boolean;
 }
 export interface DiscoverInput {
-    pluginsDir: string;
+    extensionsDir: string;
     names: string[];
     dev: Record<string, string>;
+    config: ConfigMap;
+    tree?: string;
 }
 export interface Discovery {
-    plugins: DiscoveredPlugin[];
+    extensions: DiscoveredExtension[];
     warnings: string[];
 }
 export interface CurrentTree {
     dir: string | null;
     warning: string | null;
 }
-export interface DiscoverDeps {
-    readText: (path: string) => string | null;
-    exists: (path: string) => boolean;
-}
-export declare const currentTree: (pluginsDir: string, deps?: DiscoverDeps) => CurrentTree;
-export declare const discover: (input: DiscoverInput, deps?: DiscoverDeps) => Discovery;
+export declare const currentTree: (extensionsDir: string) => CurrentTree;
+export declare const discover: (input: DiscoverInput) => Discovery;