@agentage/cli 0.38.1 → 0.40.0

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

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 // Sized for sub-millisecond config read-modify-writes; the wait outlives the TTL on purpose.
 const DEFAULTS = { ttlMs: 10_000, hardStaleMs: 60_000, maxWaitMs: 15_000 };
@@ -132,22 +132,37 @@ export const releaseFileLock = (target) => {
     if (holderOf(path)?.pid === process.pid)
         unlinkQuiet(path);
 };
+// Heartbeat for a long holder: a fresh stamp keeps waiters from ever reading it as crashed.
+export const refreshFileLock = (target, now = Date.now()) => {
+    const path = lockPath(target);
+    if (holderOf(path)?.pid !== process.pid)
+        return false;
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.new`;
+    writeFileSync(tmp, `${process.pid} ${now}`);
+    try {
+        renameSync(tmp, path);
+    }
+    finally {
+        unlinkQuiet(tmp);
+    }
+    return true;
+};
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// `fn` MUST be synchronous and hold the whole read-modify-write; released in a finally.
+// Held for all of `fn`, sync or async; a holder past hardStaleMs keeps it with refreshFileLock.
 export const withFileLock = async (target, fn, opts = {}) => {
     const { maxWaitMs } = limitsOf(opts);
     const deadline = Date.now() + maxWaitMs;
-    for (;;) {
-        if (acquireFileLock(target, Date.now(), opts)) {
-            try {
-                return fn();
-            }
-            finally {
-                releaseFileLock(target);
-            }
-        }
+    for (let tries = 0; !acquireFileLock(target, Date.now(), opts); tries++) {
+        if (tries === 0)
+            opts.onWait?.();
         if (Date.now() >= deadline)
             throw new Error(`could not acquire lock for ${target} within ${maxWaitMs}ms`);
         await sleep(STEP_MS + Math.floor(Math.random() * STEP_MS));
     }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseFileLock(target);
+    }
 };

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

@@ -1,3 +1,4 @@
 export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 export declare const readJson: <T>(path: string, guard: (value: unknown) => value is T) => T | null;
+export declare const writeTextAtomic: (path: string, text: string, mode?: number) => void;
 export declare const writeJsonAtomic: (path: string, value: unknown, mode?: number) => void;

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,19 @@
 import { Command } from 'commander';
 import { type SetupOptions } from './commands/auth/setup.js';
+import { type ExtensionCheckOptions } from './commands/extension/check.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 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>;
+    extensionCheck: (opts: ExtensionCheckOptions) => Promise<void>;
     updateHint: () => string | null;
     refreshUpdateCache: () => Promise<void>;
     writeOut: (text: string) => void;
@@ -14,5 +22,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,34 @@
 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 { runExtensionCheck } from './commands/extension/check.js';
+import { registerDelegates } from './commands/extension/delegate.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 { runExtensionSetup } from './commands/extension/setup.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),
+    extensionCheck: (opts) => runExtensionCheck(opts),
     updateHint,
     refreshUpdateCache: () => refreshUpdateCache(),
     writeOut: (text) => void process.stdout.write(text),
@@ -24,12 +39,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 +60,23 @@ 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),
+        check: withAction(deps, deps.extensionCheck),
+    });
+    try {
+        registerDelegates(program, argv, (fn) => withAction(deps, fn));
+    }
+    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,6 +88,7 @@ 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.
@@ -72,7 +106,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.38.1",
+  "version": "0.40.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"
   },

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';