@agentage/cli 0.39.0 → 0.41.0

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

@@ -27,11 +27,11 @@ const unlinkQuiet = (path) => {
     }
 };
 // Unique temp sibling + chmod before rename: never half-written, never briefly world-readable.
-export const writeJsonAtomic = (path, value, mode = 0o600) => {
+export const writeTextAtomic = (path, text, mode = 0o600) => {
     const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
     let renamed = false;
     try {
-        writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf-8', mode });
+        writeFileSync(tmp, text, { encoding: 'utf-8', mode });
         chmodSync(tmp, mode);
         renameSync(tmp, path);
         renamed = true;
@@ -41,3 +41,4 @@ export const writeJsonAtomic = (path, value, mode = 0o600) => {
             unlinkQuiet(tmp);
     }
 };
+export const writeJsonAtomic = (path, value, mode = 0o600) => writeTextAtomic(path, JSON.stringify(value, null, 2) + '\n', mode);

package/dist/lib/net/fetch.js

@@ -1,7 +1,7 @@
 import { requestHeaders } from './user-agent.js';
 export const DEFAULT_TIMEOUT_MS = 10_000;
 export const AUTH_TIMEOUT_MS = 15_000;
-// Captured at load: plugins loaded later must not be able to swap the fetch that carries tokens.
+// Captured at load: extensions loaded later must not be able to swap the fetch that carries tokens.
 const baseFetch = globalThis.fetch;
 // redirect: 'manual' so a bearer or form body is never replayed to a redirect target.
 export const cliFetch = (url, init = {}, opts = {}) => baseFetch(url, {

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

@@ -7,4 +7,5 @@ export interface Links {
 export declare const normalizeFqdn: (raw?: string) => string;
 export declare const siteFqdn: () => string;
 export declare const environment: (fqdn: string) => Env;
+export declare const apiOrigin: (fqdn: string) => string;
 export declare const links: (fqdn: string) => Links;

package/dist/lib/net/origins.js

@@ -17,19 +17,19 @@ const stubOrigin = (fqdn) => {
     return m ? `http://127.0.0.1:${m[1]}` : null;
 };
 export const environment = (fqdn) => isLocal(fqdn) || fqdn.startsWith('dev.') ? 'development' : 'production';
+// The account routes (/v1/...) sit at the root of the API origin; `links().api` is its /api family.
+export const apiOrigin = (fqdn) => {
+    const stub = stubOrigin(fqdn);
+    if (stub)
+        return stub;
+    return isLocal(fqdn) ? 'http://localhost:3001' : `https://api.${fqdn}`;
+};
 export const links = (fqdn) => {
     const stub = stubOrigin(fqdn);
+    const api = `${apiOrigin(fqdn)}/api`;
     if (stub)
-        return { site: stub, api: `${stub}/api`, auth: stub };
+        return { site: stub, api, auth: stub };
     return isLocal(fqdn)
-        ? {
-            site: 'http://localhost:3000',
-            api: 'http://localhost:3001/api',
-            auth: 'http://localhost:3010',
-        }
-        : {
-            site: `https://${fqdn}`,
-            api: `https://api.${fqdn}/api`,
-            auth: `https://auth.${fqdn}`,
-        };
+        ? { site: 'http://localhost:3000', api, auth: 'http://localhost:3010' }
+        : { site: `https://${fqdn}`, api, auth: `https://auth.${fqdn}` };
 };

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

@@ -7,11 +7,13 @@ export interface RunNpmOptions {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     timeoutMs: number;
+    npmCli?: string;
 }
 export interface ResolveNpmOptions {
     execPath?: string;
     env?: NodeJS.ProcessEnv;
 }
 export declare const resolveNpmCli: (opts?: ResolveNpmOptions) => string;
+export declare const scrubNpmEnv: (parent: NodeJS.ProcessEnv, env?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
 export declare const runNpm: (args: string[], opts: RunNpmOptions) => Promise<NpmResult>;
 export declare const requireNpm10: (run?: typeof runNpm) => Promise<string>;

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

@@ -43,8 +43,8 @@ export const resolveNpmCli = (opts = {}) => {
 };
 const isScrubbed = (key) => /^npm_config_/i.test(key) || key.toUpperCase() === 'NODE_OPTIONS';
 // Inherited npm_config_* (an `npx` or `npm run` parent) would redirect a global install.
-const childEnv = (env = {}) => ({
-    ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !isScrubbed(key))),
+export const scrubNpmEnv = (parent, env = {}) => ({
+    ...Object.fromEntries(Object.entries(parent).filter(([key]) => !isScrubbed(key))),
     ...env,
 });
 const failureNote = (err, timeoutMs) => {
@@ -55,10 +55,10 @@ const failureNote = (err, timeoutMs) => {
     return `\nnpm could not run (${String(err.code ?? err.signal ?? 'unknown')})`;
 };
 export const runNpm = (args, opts) => new Promise((resolve) => {
-    const argv = [resolveNpmCli(), ...args, '--no-audit', '--no-fund'];
+    const argv = [opts.npmCli ?? resolveNpmCli(), ...args, '--no-audit', '--no-fund'];
     const options = {
         cwd: opts.cwd,
-        env: childEnv(opts.env),
+        env: scrubNpmEnv(process.env, opts.env),
         timeout: opts.timeoutMs,
         maxBuffer: MAX_BUFFER,
         windowsHide: true,

package/dist/program.d.ts

@@ -1,11 +1,27 @@
 import { Command } from 'commander';
 import { type SetupOptions } from './commands/auth/setup.js';
+import { type ExtensionBuildOptions } from './commands/extension/build.js';
+import { type ExtensionDoctorOptions } from './commands/extension/doctor.js';
+import { type ExtensionInstallOptions } from './commands/extension/install.js';
+import { type ExtensionListOptions } from './commands/extension/list.js';
+import { type ExtensionRemoveOptions } from './commands/extension/remove.js';
+import { type LoadKitTool } from './commands/extension/kit-tool.js';
+import { type ExtensionDownOptions, type ExtensionTokenOptions, type ExtensionUpOptions } from './commands/extension/up.js';
 import { type StatusOptions } from './commands/status/status.js';
 import { type UpdateOptions } from './commands/update/update.js';
 export interface ProgramDeps {
     setup: (opts: SetupOptions) => Promise<void>;
     status: (opts: StatusOptions) => Promise<void>;
     update: (opts: UpdateOptions) => Promise<void>;
+    extensionInstall: (opts: ExtensionInstallOptions) => Promise<void>;
+    extensionRemove: (opts: ExtensionRemoveOptions) => Promise<void>;
+    extensionList: (opts: ExtensionListOptions) => Promise<void>;
+    extensionDoctor: (opts: ExtensionDoctorOptions) => Promise<void>;
+    extensionBuild: (opts: ExtensionBuildOptions) => Promise<void>;
+    extensionUp: (opts: ExtensionUpOptions) => Promise<void>;
+    extensionDown: (opts: ExtensionDownOptions) => Promise<void>;
+    extensionToken: (opts: ExtensionTokenOptions) => Promise<void>;
+    kitTool: LoadKitTool;
     updateHint: () => string | null;
     refreshUpdateCache: () => Promise<void>;
     writeOut: (text: string) => void;
@@ -14,5 +30,5 @@ export interface ProgramDeps {
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_USAGE = 2;
-export declare const createProgram: (deps?: ProgramDeps) => Command;
+export declare const createProgram: (deps?: ProgramDeps, argv?: string[]) => Command;
 export declare const run: (argv?: string[], deps?: ProgramDeps) => Promise<number>;

package/dist/program.js

@@ -1,19 +1,43 @@
 import chalk from 'chalk';
 import { Command, CommanderError } from 'commander';
-import { registerSetup, runSetup } from './commands/auth/setup.js';
-import { registerStatus, runStatus } from './commands/status/status.js';
+import { registerSetup } from './commands/auth/setup.js';
+import { runExtensionBuild } from './commands/extension/build.js';
+import { registerDelegates } from './commands/extension/delegate.js';
+import { deprecatedCheck, runExtensionDoctor, } from './commands/extension/doctor.js';
+import { runExtensionInstall } from './commands/extension/install.js';
+import { registerExtension, runExtensionList, } from './commands/extension/list.js';
+import { runExtensionRemove, terminalIo, } from './commands/extension/remove.js';
+import { signedInAccount } from './commands/extension/account.js';
+import { KIT_EXIT } from './commands/extension/kit-commands.js';
+import { loadKitTool } from './commands/extension/kit-tool.js';
+import { runExtensionSetup } from './commands/extension/setup.js';
+import { runExtensionDown, runExtensionToken, runExtensionUp, } from './commands/extension/up.js';
+import { registerStatus, runStatus, statusDeps, } from './commands/status/status.js';
 import { registerUpdate, runUpdate } from './commands/update/update.js';
+import { npmMajor, prepareManifest, prepareNpm } from './core/installer/npm.js';
 import { ensureSignedIn, signOut } from './lib/auth/sign-in.js';
 import { refreshUpdateCache, updateHint } from './lib/update/update-cache.js';
 import { VERSION } from './utils/version.js';
+const setupDeps = {
+    ensureSignedIn: (signInOpts) => ensureSignedIn(signInOpts),
+    signOut: () => signOut(),
+    printStatus: (opts) => runStatus(opts, statusDeps(false)),
+};
+// What a profile edit reaches: npm, and the account it syncs with when signed in.
+const editDeps = { npm: () => prepareNpm(), npmMajor: () => npmMajor(), account: signedInAccount };
 const defaultDeps = {
-    setup: (opts) => runSetup(opts, {
-        ensureSignedIn: (signInOpts) => ensureSignedIn(signInOpts),
-        signOut: () => signOut(),
-        printStatus: () => runStatus({}),
-    }),
+    setup: (opts) => runExtensionSetup(opts, { ...setupDeps, ...editDeps }),
     status: (opts) => runStatus(opts),
     update: (opts) => runUpdate(opts),
+    extensionInstall: (opts) => runExtensionInstall(opts, { ...editDeps, manifest: () => prepareManifest() }),
+    extensionRemove: (opts) => runExtensionRemove(opts, { ...editDeps, io: terminalIo() }),
+    extensionList: (opts) => runExtensionList(opts),
+    extensionDoctor: (opts) => runExtensionDoctor(opts),
+    extensionBuild: (opts) => runExtensionBuild(opts),
+    extensionUp: (opts) => runExtensionUp(opts),
+    extensionDown: (opts) => runExtensionDown(opts),
+    extensionToken: (opts) => runExtensionToken(opts),
+    kitTool: loadKitTool,
     updateHint,
     refreshUpdateCache: () => refreshUpdateCache(),
     writeOut: (text) => void process.stdout.write(text),
@@ -24,12 +48,14 @@ export const EXIT_FAILED = 1;
 export const EXIT_USAGE = 2;
 const ACTION_FAILED = 'agentage.actionFailed';
 const messageOf = (err) => (err instanceof Error ? err.message : String(err));
-// One failure path for every command: a red stderr line, then exit 1 through run().
+// One failure path: a red stderr line, exit 1; an extension's --help or usage error keeps its code.
 const withAction = (deps, fn, prefix = '') => async (opts) => {
     try {
         await fn(opts);
     }
     catch (err) {
+        if (err instanceof CommanderError)
+            throw err;
         deps.writeErr(`${chalk.red(`${prefix}${messageOf(err)}`)}\n`);
         throw new CommanderError(EXIT_FAILED, ACTION_FAILED, messageOf(err));
     }
@@ -43,7 +69,28 @@ const hintAfter = (deps) => (_program, action) => {
         deps.writeErr(`${chalk.dim(hint)}\n`);
     void deps.refreshUpdateCache();
 };
-export const createProgram = (deps = defaultDeps) => {
+// Extension manifests are read as data; whatever goes wrong there, today's commands still run.
+const addExtensions = (program, deps, argv) => {
+    registerExtension(program, {
+        install: withAction(deps, deps.extensionInstall),
+        remove: withAction(deps, deps.extensionRemove),
+        list: withAction(deps, deps.extensionList),
+        doctor: withAction(deps, deps.extensionDoctor),
+        check: withAction(deps, deprecatedCheck(deps.extensionDoctor, deps.writeErr)),
+        build: withAction(deps, deps.extensionBuild),
+        up: withAction(deps, deps.extensionUp),
+        down: withAction(deps, deps.extensionDown),
+        token: withAction(deps, deps.extensionToken),
+    });
+    try {
+        registerDelegates(program, argv, (fn) => withAction(deps, fn), deps.kitTool);
+    }
+    catch (err) {
+        deps.writeErr(`${chalk.yellow(`warning: extension commands skipped: ${messageOf(err)}`)}\n`);
+    }
+};
+// `argv` reaches an extension's own Command unchanged, so it parses exactly what was typed.
+export const createProgram = (deps = defaultDeps, argv = process.argv) => {
     const program = new Command()
         .name('agentage')
         .description('Connect this machine to agentage from the terminal')
@@ -55,9 +102,10 @@ export const createProgram = (deps = defaultDeps) => {
     registerSetup(program, withAction(deps, deps.setup, 'Setup failed: '));
     registerStatus(program, withAction(deps, deps.status));
     registerUpdate(program, withAction(deps, deps.update));
+    addExtensions(program, deps, argv);
     return program;
 };
-// Commander's own exit 0 (--help, --version) stays 0; any other commander error is usage.
+// --help and --version stay 0; a kit command keeps its code; any other commander error is usage.
 const exitCodeOf = (err, deps) => {
     if (!(err instanceof CommanderError)) {
         deps.writeErr(`${chalk.red(messageOf(err))}\n`);
@@ -65,6 +113,8 @@ const exitCodeOf = (err, deps) => {
     }
     if (err.code === ACTION_FAILED)
         return EXIT_FAILED;
+    if (err.code === KIT_EXIT)
+        return err.exitCode;
     return err.exitCode === 0 ? EXIT_OK : EXIT_USAGE;
 };
 // Returns the exit code instead of exiting, so piped stdout is never cut short.
@@ -72,7 +122,7 @@ export const run = async (argv = process.argv, deps = defaultDeps) => {
     if (process.env['NO_COLOR'])
         chalk.level = 0; // chalk ignores NO_COLOR on its own
     try {
-        await createProgram(deps).parseAsync(argv);
+        await createProgram(deps, argv).parseAsync(argv);
         return EXIT_OK;
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/cli",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "The agentage CLI - connect this machine to agentage from the terminal",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,9 +10,13 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./plugin": {
-      "types": "./dist/plugin.d.ts",
-      "default": "./dist/plugin.js"
+    "./extension": {
+      "types": "./dist/extension.d.ts",
+      "default": "./dist/extension.js"
+    },
+    "./extension/test": {
+      "types": "./dist/extension-test.d.ts",
+      "default": "./dist/extension-test.js"
     },
     "./package.json": "./package.json"
   },
@@ -51,6 +55,7 @@
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
+    "@agentage/extension": "^0.2.0",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "open": "^11.0.0"

package/dist/commands/plugins/status-print.d.ts

@@ -1,2 +0,0 @@
-import { type PluginsStatus } from './status-rows.js';
-export declare const pluginStatusLines: (status: PluginsStatus) => string[];

package/dist/commands/plugins/status-print.js

@@ -1,44 +0,0 @@
-import chalk from 'chalk';
-import {} from '../../core/loader/states.js';
-import {} from './status-rows.js';
-const COLOR = {
-    installed: chalk.green,
-    off: chalk.dim,
-    blocked: chalk.yellow,
-    invalid: chalk.red,
-    missing: chalk.yellow,
-};
-const STATE_WIDTH = Math.max(...Object.keys(COLOR).map((state) => state.length));
-const line = (label, value) => `${label.padEnd(10)} ${value}`;
-const profileText = (profile) => {
-    if (profile.state === 'missing')
-        return 'no profile';
-    if (profile.state === 'invalid')
-        return chalk.red('profile.json is invalid');
-    const readOnly = profile.readOnly ? chalk.yellow(', read-only') : '';
-    return `version ${profile.version} (source: ${profile.source}${readOnly})`;
-};
-const lastRunText = (run) => {
-    if (run === null)
-        return '';
-    const error = run.error === null ? '' : ` "${run.error}"`;
-    return `  last run: ${run.state}${error} at ${run.at}`;
-};
-const pluginLine = (row, idWidth) => {
-    const id = (row.id ?? '?').padEnd(idWidth);
-    const state = COLOR[row.state](row.state.padEnd(STATE_WIDTH));
-    const wanted = row.mode === 'dev' ? 'dev' : `wants ${row.wanted ?? '?'}`;
-    const pkg = `${row.package} ${row.installed ?? '-'} (${wanted})`;
-    const commands = row.commands.length > 0 ? `  commands: ${row.commands.join(', ')}` : '';
-    const error = row.error === null ? '' : chalk.dim(`  ${row.error}`);
-    return `  ${id}  ${state}  ${pkg}${commands}${lastRunText(row.lastRun)}${error}`;
-};
-export const pluginStatusLines = (status) => {
-    const idWidth = Math.max(0, ...status.plugins.map((row) => (row.id ?? '?').length));
-    return [
-        line('machine', `${status.machine.id} (${status.machine.name})`),
-        line('profile', profileText(status.profile)),
-        line('plugins', status.plugins.length === 0 ? 'none' : String(status.plugins.length)),
-        ...status.plugins.map((row) => pluginLine(row, idWidth)),
-    ];
-};

package/dist/commands/plugins/status-rows.d.ts

@@ -1,51 +0,0 @@
-import { type DiscoverInput, type Discovery } from '../../core/loader/discover.js';
-import { type RunState } from '../../core/loader/state.js';
-import { type StaticState } from '../../core/loader/states.js';
-import { type MachineFile, type ProfileSource } from '../../core/profile/machine.js';
-import { type ProfileParse } from '../../core/profile/schema.js';
-export interface PluginRow {
-    id: string | null;
-    package: string;
-    mode: 'installed' | 'dev';
-    wanted: string | null;
-    installed: string | null;
-    state: StaticState;
-    error: string | null;
-    commands: string[];
-    lastRun: {
-        at: string;
-        state: string;
-        error: string | null;
-    } | null;
-}
-export type ProfileStatus = {
-    state: 'missing';
-} | {
-    state: 'invalid';
-    errors: string[];
-} | {
-    state: 'ok';
-    version: number;
-    source: ProfileSource;
-    readOnly: boolean;
-};
-export interface PluginsStatus {
-    machine: {
-        id: string;
-        name: string;
-    };
-    profile: ProfileStatus;
-    plugins: PluginRow[];
-}
-export interface PluginsGather {
-    status: PluginsStatus;
-    warnings: string[];
-}
-export interface StatusRowsDeps {
-    loadMachine: () => Promise<MachineFile>;
-    readProfile: () => ProfileParse | null;
-    discover: (input: DiscoverInput) => Discovery;
-    readRunState: (id: string) => RunState | null;
-    pluginsDir: () => string;
-}
-export declare const gatherPluginStatus: (deps?: StatusRowsDeps) => Promise<PluginsGather>;

package/dist/commands/plugins/status-rows.js

@@ -1,58 +0,0 @@
-import { discover, } from '../../core/loader/discover.js';
-import { readRunState } from '../../core/loader/state.js';
-import { staticStates } from '../../core/loader/states.js';
-import { pluginsDir } from '../../core/paths.js';
-import { loadMachine } from '../../core/profile/machine.js';
-import { effective } from '../../core/profile/merge.js';
-import { readProfile } from '../../core/profile/profile.js';
-import {} from '../../core/profile/schema.js';
-const defaultDeps = {
-    loadMachine: () => loadMachine(),
-    readProfile: () => readProfile(),
-    discover: (input) => discover(input),
-    readRunState: (id) => readRunState(id),
-    pluginsDir,
-};
-const profileStatus = (parsed, machine) => {
-    if (parsed === null)
-        return { state: 'missing' };
-    if (!parsed.ok)
-        return { state: 'invalid', errors: parsed.errors };
-    const { version } = parsed.profile;
-    return { state: 'ok', version, source: machine.profileSource, readOnly: parsed.readOnly };
-};
-// A row for an invalid manifest has no trustworthy id, so it never shows another plugin's run.
-const lastRunOf = (p, s, deps) => {
-    const run = p.id === null || s.state === 'invalid' ? null : deps.readRunState(p.id);
-    return run && { at: run.at, state: run.state, error: run.error };
-};
-const toRow = (p, eff, s, deps) => ({
-    id: p.id,
-    package: p.pkg,
-    mode: p.source === 'dev' ? 'dev' : 'installed',
-    wanted: eff.install[p.pkg] ?? null,
-    installed: p.version,
-    state: s.state,
-    error: s.error,
-    commands: p.commands,
-    lastRun: lastRunOf(p, s, deps),
-});
-const UNKNOWN = { state: 'invalid', error: null };
-// Reads manifests, profile and state files; writes only a missing machine.json.
-export const gatherPluginStatus = async (deps = defaultDeps) => {
-    const machine = await deps.loadMachine();
-    const parsed = deps.readProfile();
-    const eff = effective(parsed?.ok ? parsed.profile : null, machine);
-    const names = Object.keys(eff.install);
-    const found = deps.discover({ pluginsDir: deps.pluginsDir(), names, dev: eff.dev });
-    const states = staticStates(found.plugins, eff.off);
-    const plugins = found.plugins
-        .map((p) => toRow(p, eff, states.get(p.pkg) ?? UNKNOWN, deps))
-        .sort((a, b) => (a.package < b.package ? -1 : 1));
-    const status = {
-        machine: { id: machine.id, name: machine.name },
-        profile: profileStatus(parsed, machine),
-        plugins,
-    };
-    return { status, warnings: [...(parsed?.ok ? parsed.warnings : []), ...found.warnings] };
-};

package/dist/core/flag.d.ts

@@ -1 +0,0 @@
-export declare const pluginsEnabled: () => boolean;

package/dist/core/flag.js

@@ -1 +0,0 @@
-export const pluginsEnabled = () => process.env['AGENTAGE_PLUGINS'] === '1';

package/dist/plugin.d.ts

@@ -1 +0,0 @@
-export declare const PLUGIN_API_VERSION = "1.0.0";

package/dist/plugin.js

@@ -1,2 +0,0 @@
-// The plugin contract is versioned apart from the CLI, so plugins pin it, not a CLI release.
-export const PLUGIN_API_VERSION = '1.0.0';