@agentage/cli 0.38.0 → 0.38.1

package/dist/lib/update/update-cache.js

@@ -1,6 +1,6 @@
-import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureConfigDir, getConfigDir } from '../fs/config.js';
+import { isRecord, readJson, writeJsonAtomic } from '../fs/json-file.js';
 import { fetchJsonUnref } from '../net/http.js';
 import { compareVersions, INSTALL_HINT, REGISTRY_URL } from './update-check.js';
 import { VERSION } from '../../utils/version.js';
@@ -8,18 +8,14 @@ const CACHE_FILE = 'update-check.json';
 const TTL_MS = 60 * 60 * 1000; // passive checks refresh at most once an hour
 const BG_TIMEOUT_MS = 3000; // hard cap on the whole background attempt, connect included
 const cachePath = () => join(getConfigDir(), CACHE_FILE);
-export const readUpdateCache = () => {
-    try {
-        const c = JSON.parse(readFileSync(cachePath(), 'utf-8'));
-        return typeof c.checkedAt === 'number' ? c : null;
-    }
-    catch {
-        return null;
-    }
-};
+// A wrong-typed field reads as no cache: the post-action hint must never throw.
+export const isUpdateCache = (value) => isRecord(value) &&
+    typeof value['checkedAt'] === 'number' &&
+    (value['latest'] === null || typeof value['latest'] === 'string');
+export const readUpdateCache = () => readJson(cachePath(), isUpdateCache);
 const writeUpdateCache = (latest, now) => {
     ensureConfigDir();
-    writeFileSync(cachePath(), JSON.stringify({ checkedAt: now, latest }) + '\n', 'utf-8');
+    writeJsonAtomic(cachePath(), { checkedAt: now, latest });
 };
 // The one dim hint line printed after a command, read purely from the cache (never the network),
 // only when the cached latest is newer than us. null = print nothing.

package/dist/lib/update/update-check.js

@@ -7,10 +7,7 @@ export const REGISTRY_URL = 'https://registry.npmjs.org/@agentage/cli/latest';
 // Compare dotted numeric versions (major.minor.patch); prerelease/build suffixes are
 // ignored - good enough for an update hint. Returns -1 / 0 / 1.
 export const compareVersions = (a, b) => {
-    const parts = (v) => v
-        .split('-')[0]
-        .split('.')
-        .map((n) => Number.parseInt(n, 10) || 0);
+    const parts = (v) => (v.split('-')[0] ?? '').split('.').map((n) => Number.parseInt(n, 10) || 0);
     const pa = parts(a);
     const pb = parts(b);
     for (let i = 0; i < 3; i++) {

package/dist/program.d.ts

@@ -1 +1,18 @@
-export declare const run: () => Promise<void>;
+import { Command } from 'commander';
+import { type SetupOptions } from './commands/auth/setup.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>;
+    updateHint: () => string | null;
+    refreshUpdateCache: () => Promise<void>;
+    writeOut: (text: string) => void;
+    writeErr: (text: string) => void;
+}
+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 run: (argv?: string[], deps?: ProgramDeps) => Promise<number>;

package/dist/program.js

@@ -1,38 +1,81 @@
 import chalk from 'chalk';
-import { Command } from 'commander';
-import { registerSetup } from './commands/auth/setup.js';
-import { registerStatus } from './commands/status/status.js';
-import { registerUpdate } from './commands/update/update.js';
+import { Command, CommanderError } from 'commander';
+import { registerSetup, runSetup } from './commands/auth/setup.js';
+import { registerStatus, runStatus } from './commands/status/status.js';
+import { registerUpdate, runUpdate } from './commands/update/update.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 program = new Command();
-program
-    .name('agentage')
-    .description('Connect this machine to agentage from the terminal')
-    .version(VERSION);
-program.addHelpText('after', '\nNew here? Run: agentage setup to connect this machine.');
-// After any command (except the update-aware ones, which report richer state themselves), print a
-// one-line hint from the cache, then kick a fire-and-forget refresh. Never awaited, never throws -
-// the command output is already done and the cache-only read keeps this instant. The hint is
-// suppressed under --json so it never corrupts machine-readable output.
-program.hook('postAction', (_thisCommand, actionCommand) => {
-    const name = actionCommand.name();
-    if (name === 'status' || name === 'update')
+const defaultDeps = {
+    setup: (opts) => runSetup(opts, {
+        ensureSignedIn: (signInOpts) => ensureSignedIn(signInOpts),
+        signOut: () => signOut(),
+        printStatus: () => runStatus({}),
+    }),
+    status: (opts) => runStatus(opts),
+    update: (opts) => runUpdate(opts),
+    updateHint,
+    refreshUpdateCache: () => refreshUpdateCache(),
+    writeOut: (text) => void process.stdout.write(text),
+    writeErr: (text) => void process.stderr.write(text),
+};
+export const EXIT_OK = 0;
+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().
+const withAction = (deps, fn, prefix = '') => async (opts) => {
+    try {
+        await fn(opts);
+    }
+    catch (err) {
+        deps.writeErr(`${chalk.red(`${prefix}${messageOf(err)}`)}\n`);
+        throw new CommanderError(EXIT_FAILED, ACTION_FAILED, messageOf(err));
+    }
+};
+// status and update report update state themselves; the hint never touches --json stdout.
+const hintAfter = (deps) => (_program, action) => {
+    if (action.name() === 'status' || action.name() === 'update')
         return;
-    if (!actionCommand.opts()['json']) {
-        const hint = updateHint();
-        if (hint)
-            console.error(chalk.dim(hint)); // stderr: never corrupt piped stdout
+    const hint = action.opts()['json'] ? null : deps.updateHint();
+    if (hint)
+        deps.writeErr(`${chalk.dim(hint)}\n`);
+    void deps.refreshUpdateCache();
+};
+export const createProgram = (deps = defaultDeps) => {
+    const program = new Command()
+        .name('agentage')
+        .description('Connect this machine to agentage from the terminal')
+        .version(VERSION)
+        .exitOverride()
+        .configureOutput({ writeOut: deps.writeOut, writeErr: deps.writeErr })
+        .addHelpText('after', '\nNew here? Run: agentage setup to connect this machine.')
+        .hook('postAction', hintAfter(deps));
+    registerSetup(program, withAction(deps, deps.setup, 'Setup failed: '));
+    registerStatus(program, withAction(deps, deps.status));
+    registerUpdate(program, withAction(deps, deps.update));
+    return program;
+};
+// Commander's own exit 0 (--help, --version) stays 0; any other commander error is usage.
+const exitCodeOf = (err, deps) => {
+    if (!(err instanceof CommanderError)) {
+        deps.writeErr(`${chalk.red(messageOf(err))}\n`);
+        return EXIT_FAILED;
+    }
+    if (err.code === ACTION_FAILED)
+        return EXIT_FAILED;
+    return err.exitCode === 0 ? EXIT_OK : EXIT_USAGE;
+};
+// Returns the exit code instead of exiting, so piped stdout is never cut short.
+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);
+        return EXIT_OK;
+    }
+    catch (err) {
+        return exitCodeOf(err, deps);
     }
-    void refreshUpdateCache();
-});
-registerSetup(program);
-registerStatus(program);
-registerUpdate(program);
-// Called by the bin (src/cli.ts).
-export const run = async () => {
-    await program.parseAsync().catch((err) => {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/cli",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "description": "The agentage CLI - connect this machine to agentage from the terminal",
   "type": "module",
   "main": "./dist/index.js",

package/dist/lib/update/update-lock.d.ts

@@ -1,2 +0,0 @@
-export declare const acquireUpdateLock: (now?: number) => boolean;
-export declare const releaseUpdateLock: () => void;

package/dist/lib/update/update-lock.js

@@ -1,109 +0,0 @@
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { ensureConfigDir, getConfigDir } from '../fs/config.js';
-const LOCK_FILE = 'update.lock';
-const LOCK_TTL_MS = 10 * 60 * 1000; // a lock older than this whose holder is gone is a crashed run
-// Past this age a holder is taken over even if its pid still resolves (pid reuse after a crash); far
-// beyond any real run or scheduler pause, so a live-but-slow holder is never mistaken for crashed.
-const STALE_HARD_MS = 30 * 60 * 1000;
-const lockPath = () => join(getConfigDir(), LOCK_FILE);
-// The lock file holds "<pid> <timestamp>": pid gates crash-takeover, the trailing token is the
-// acquisition time. A legacy single-token file parses as pid 0 (unknown holder), aging out on TTL.
-const holderOf = (path) => {
-    try {
-        const parts = readFileSync(path, 'utf-8').trim().split(/\s+/);
-        const at = Number.parseInt(parts[parts.length - 1] ?? '', 10);
-        if (Number.isNaN(at))
-            return null;
-        const pid = parts.length >= 2 ? Number.parseInt(parts[0] ?? '', 10) : 0;
-        return { pid: Number.isNaN(pid) ? 0 : pid, at };
-    }
-    catch {
-        return null;
-    }
-};
-// Same-host liveness probe. ESRCH = the holder is gone (crashed); EPERM = alive but owned by another
-// user. pid 0/unknown counts as gone so a legacy or malformed lock still ages out on the TTL.
-const holderAlive = (pid) => {
-    if (pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-};
-// A holder is safe to take over only once it is past the TTL AND provably gone: a dead pid, our own
-// leftover pid, or so old that pid reuse is the only explanation. A live holder merely starved of
-// CPU is never stolen - stealing it would let two writers run concurrently.
-const isCrashed = (holder, now) => {
-    const age = now - holder.at;
-    if (age < LOCK_TTL_MS)
-        return false;
-    if (age >= STALE_HARD_MS)
-        return true;
-    return holder.pid === process.pid || !holderAlive(holder.pid);
-};
-const unlinkQuiet = (path) => {
-    try {
-        unlinkSync(path);
-    }
-    catch {
-        // already gone
-    }
-};
-// Serialize stale-lock takeover behind its own exclusive create, so no taker can ever delete a
-// lock that turned FRESH mid-takeover (the ABA race: reader sees the stale timestamp, a winner
-// re-creates the lock, the reader deletes the winner's file). Under the guard the staleness is
-// re-checked and only a genuinely stale lock is cleared; losers simply refuse. A guard left by a
-// crashed taker expires like the lock itself. Returns whether to re-race the create.
-const takeOverStale = (now) => {
-    const guard = `${lockPath()}.takeover`;
-    const guardHeld = holderOf(guard);
-    if (guardHeld !== null && isCrashed(guardHeld, now))
-        unlinkQuiet(guard);
-    try {
-        writeFileSync(guard, `${process.pid} ${now}`, { flag: 'wx' });
-    }
-    catch {
-        return false; // another taker is mid-takeover; let it win
-    }
-    try {
-        const holder = holderOf(lockPath());
-        if (holder !== null && !isCrashed(holder, now))
-            return false; // fresh or a live-but-slow holder
-        unlinkQuiet(lockPath());
-        return true;
-    }
-    finally {
-        unlinkQuiet(guard);
-    }
-};
-// Acquire the single-writer update lock. The O_EXCL ('wx') create IS the mutex - concurrent runs
-// cannot both win it, unlike a check-then-write. A fresh holder (younger than the TTL) refuses;
-// a stale one (crashed run) is cleared under the takeover guard and re-raced once. `now` is
-// injectable.
-export const acquireUpdateLock = (now = Date.now()) => {
-    ensureConfigDir();
-    for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-            writeFileSync(lockPath(), `${process.pid} ${now}`, { flag: 'wx' });
-            return true;
-        }
-        catch {
-            const holder = holderOf(lockPath());
-            if (holder !== null && !isCrashed(holder, now))
-                return false;
-            if (!takeOverStale(now))
-                return false;
-        }
-    }
-    return false;
-};
-export const releaseUpdateLock = () => {
-    const path = lockPath();
-    if (existsSync(path))
-        unlinkSync(path);
-};