agentloom 0.1.3 → 0.1.4

package/README.md

@@ -55,6 +55,7 @@ Global scope uses `~/.agents` with the same file layout.
 - `agentloom add <source>`
 - `agentloom find <query>`
 - `agentloom update [source]`
+- `agentloom upgrade`
 - `agentloom sync`
 - `agentloom delete <source|name>`
 
@@ -118,6 +119,7 @@ agentloom --help
 agentloom find --help
 agentloom add --help
 agentloom update --help
+agentloom upgrade --help
 agentloom sync --help
 agentloom delete --help
 agentloom agent --help
@@ -131,12 +133,16 @@ agentloom mcp server --help
 
 ### Version update notice
 
-`agentloom` now performs a best-effort npm version check and shows an update hint when a newer release is available.
+`agentloom` performs best-effort npm version checks and upgrades when a newer release is available.
 
-- check is cached (`~/.agents/.agentloom-version-cache.json`)
-- check runs at most once every 12 hours
-- check is skipped in non-interactive sessions
-- disable via:
+- checks are cached (`~/.agents/.agentloom-version-cache.json`)
+- check/upgrade attempts run at most once every 2 hours per detected version
+- in interactive TTY sessions, agentloom asks before upgrading
+- in non-interactive sessions, upgrades run without prompts
+- after an approved upgrade, the original command is re-run automatically
+- if running from `npx`, auto-upgrade re-runs with `npx agentloom@<latest>`
+- manual upgrade command: `agentloom upgrade`
+- disable auto checks via:
 
 ```bash
 AGENTLOOM_DISABLE_UPDATE_NOTIFIER=1

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runInitCommand } from "./commands/init.js";
 import { runMcpCommand } from "./commands/mcp.js";
 import { runSkillCommand } from "./commands/skills.js";
 import { runSyncCommand } from "./commands/sync.js";
+import { runUpgradeCommand } from "./commands/upgrade.js";
 import { runUpdateCommand } from "./commands/update.js";
 import { formatUnknownCommandError, getRootHelpText } from "./core/copy.js";
 import { maybePromptManageAgentsBootstrap } from "./core/manage-agents-bootstrap.js";
@@ -36,23 +37,24 @@ export async function runCli(argv) {
     }
     const parsed = parseArgs(argv);
     const cwd = process.cwd();
-    const shouldBootstrapManageAgents = await maybePromptManageAgentsBootstrap({
-        command,
-        help: Boolean(parsed.help),
-        yes: Boolean(parsed.yes),
-        cwd,
-    });
     const route = parseCommandRoute(argv);
     if (!parsed.help) {
         await maybeNotifyVersionUpdate({
             command,
+            argv,
             currentVersion: version,
         });
     }
     if (!route) {
         throw new Error(formatUnknownCommandError(command));
     }
-    await runRoutedCommand(route, parsed, cwd, command);
+    const shouldBootstrapManageAgents = await maybePromptManageAgentsBootstrap({
+        command,
+        help: Boolean(parsed.help),
+        yes: Boolean(parsed.yes),
+        cwd,
+    });
+    await runRoutedCommand(route, parsed, cwd, command, version);
     if (shouldBootstrapManageAgents) {
         const bootstrapArgs = buildManageAgentsBootstrapArgs(parsed, cwd);
         await runSkillCommand(parseArgs(bootstrapArgs), cwd);
@@ -61,7 +63,7 @@ export async function runCli(argv) {
 function printHelp() {
     console.log(getRootHelpText());
 }
-async function runRoutedCommand(route, parsed, cwd, command) {
+async function runRoutedCommand(route, parsed, cwd, command, version) {
     if (!route) {
         throw new Error(formatUnknownCommandError(command));
     }
@@ -76,6 +78,9 @@ async function runRoutedCommand(route, parsed, cwd, command) {
             case "update":
                 await runUpdateCommand(parsed, cwd);
                 return;
+            case "upgrade":
+                await runUpgradeCommand(parsed, version);
+                return;
             case "sync":
                 await runSyncCommand(parsed, cwd);
                 return;

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from "minimist";
+export declare function runUpgradeCommand(argv: ParsedArgs, currentVersion: string): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,19 @@
+import { getUpgradeHelpText } from "../core/copy.js";
+import { upgradeToLatest } from "../core/version-notifier.js";
+export async function runUpgradeCommand(argv, currentVersion) {
+    if (argv.help) {
+        console.log(getUpgradeHelpText());
+        return;
+    }
+    const result = await upgradeToLatest({ currentVersion });
+    if (result === "updated")
+        return;
+    if (result === "already-latest") {
+        console.log(`agentloom ${currentVersion} is already up to date.`);
+        return;
+    }
+    if (result === "unavailable") {
+        throw new Error("Unable to reach npm to check the latest agentloom release.");
+    }
+    throw new Error("Automatic upgrade failed.");
+}

package/dist/core/copy.d.ts

@@ -7,6 +7,7 @@ export declare function getRootHelpText(): string;
 export declare function getFindHelpText(): string;
 export declare function getAddHelpText(): string;
 export declare function getUpdateHelpText(): string;
+export declare function getUpgradeHelpText(): string;
 export declare function getSyncHelpText(): string;
 export declare function getInitHelpText(): string;
 export declare function getCommandHelpText(): string;

package/dist/core/copy.js

@@ -12,6 +12,7 @@ Aggregate commands:
   init                       Bootstrap canonical files, migrate providers, then sync
   find <query>               Search remote + local entities
   update [source]            Refresh lockfile-managed imports
+  upgrade                    Install the latest CLI release
   sync                       Migrate provider configs then generate provider outputs
   delete <source|name>       Delete imported entities by source or name
 
@@ -113,6 +114,18 @@ Example:
   agentloom update farnoodma/agents --providers codex,cursor
 `;
 }
+export function getUpgradeHelpText() {
+    return `Install the latest agentloom release.
+
+Usage:
+  agentloom upgrade
+
+Behavior:
+  - Checks npm for the newest published version
+  - Upgrades immediately without interactive prompts
+  - Reports when the current version is already up to date
+`;
+}
 export function getSyncHelpText() {
     return `Migrate provider configs into canonical .agents data, then generate provider-specific outputs.
 

package/dist/core/lockfile.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { readJsonIfExists, writeJsonAtomic } from "./fs.js";
 const EMPTY_LOCK = {
     version: 1,
@@ -10,7 +11,7 @@ export function readLockfile(paths) {
     }
     return {
         version: 1,
-        entries: lock.entries.map((entry) => ({
+        entries: lock.entries.map((entry) => normalizeLockEntryForRuntime(paths, {
             ...entry,
             importedAgents: Array.isArray(entry.importedAgents)
                 ? entry.importedAgents
@@ -66,7 +67,10 @@ function normalizeRenameMap(value) {
     return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
 export function writeLockfile(paths, lockfile) {
-    writeJsonAtomic(paths.lockPath, lockfile);
+    writeJsonAtomic(paths.lockPath, {
+        version: 1,
+        entries: lockfile.entries.map((entry) => normalizeLockEntryForDisk(paths, entry)),
+    });
 }
 export function upsertLockEntry(lockfile, entry) {
     const index = lockfile.entries.findIndex((item) => item.source === entry.source &&
@@ -106,3 +110,31 @@ function normalizeSelectionForKey(value) {
         ...new Set(value.map((item) => item.trim().toLowerCase()).filter(Boolean)),
     ].sort();
 }
+function normalizeLockEntryForRuntime(paths, entry) {
+    if (paths.scope !== "local" || entry.sourceType !== "local") {
+        return entry;
+    }
+    if (path.isAbsolute(entry.source)) {
+        return entry;
+    }
+    return {
+        ...entry,
+        source: path.resolve(paths.workspaceRoot, entry.source),
+    };
+}
+function normalizeLockEntryForDisk(paths, entry) {
+    if (paths.scope !== "local" || entry.sourceType !== "local") {
+        return entry;
+    }
+    if (!path.isAbsolute(entry.source)) {
+        return {
+            ...entry,
+            source: entry.source || ".",
+        };
+    }
+    const relativeSource = path.relative(paths.workspaceRoot, entry.source);
+    return {
+        ...entry,
+        source: relativeSource || ".",
+    };
+}

package/dist/core/manage-agents-bootstrap.js

@@ -9,6 +9,7 @@ const SKIP_COMMANDS = new Set([
     "version",
     "--version",
     "-v",
+    "upgrade",
 ]);
 export function getGlobalManageAgentsSkillPath(homeDir = os.homedir()) {
     return path.join(homeDir, ".agents", "skills", "manage-agents", "SKILL.md");

package/dist/core/router.d.ts

@@ -1,5 +1,5 @@
 import type { EntityType } from "../types.js";
-export type AggregateVerb = "add" | "find" | "update" | "sync" | "delete" | "init";
+export type AggregateVerb = "add" | "find" | "update" | "upgrade" | "sync" | "delete" | "init";
 export type EntityVerb = "add" | "list" | "delete" | "find" | "update" | "sync";
 export type McpServerVerb = "add" | "list" | "delete";
 export type CommandRoute = {

package/dist/core/router.js

@@ -2,6 +2,7 @@ const AGGREGATE_VERBS = new Set([
     "add",
     "find",
     "update",
+    "upgrade",
     "sync",
     "delete",
     "init",

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

@@ -1,9 +1,19 @@
 type MaybeNotifyOptions = {
     command: string;
+    argv: string[];
     packageName?: string;
     currentVersion: string;
 };
+export type UpgradeResult = "updated" | "already-latest" | "failed" | "unavailable";
 export declare function maybeNotifyVersionUpdate(options: MaybeNotifyOptions): Promise<void>;
+export declare function upgradeToLatest(options: {
+    currentVersion: string;
+    packageName?: string;
+}): Promise<UpgradeResult>;
 export declare function isNewerVersion(candidate: string, current: string): boolean;
-export declare function promptAndUpdate(current: string, latest: string): Promise<"updated" | "declined" | "failed">;
+export declare function promptAndUpdate(current: string, latest: string, options?: {
+    packageName?: string;
+    rerunArgs?: string[];
+}): Promise<"updated" | "already-latest" | "failed">;
+export declare function maybeConfirmAutoUpgrade(current: string, latest: string): Promise<boolean>;
 export {};

package/dist/core/version-notifier.js

@@ -6,50 +6,73 @@ import path from "node:path";
 import { confirm, isCancel } from "@clack/prompts";
 import { ensureDir, writeJsonAtomic } from "./fs.js";
 const UPDATE_CACHE_PATH = path.join(os.homedir(), ".agents", ".agentloom-version-cache.json");
-const CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
+const CHECK_INTERVAL_MS = 2 * 60 * 60 * 1000;
 const REQUEST_TIMEOUT_MS = 1800;
+const DISABLE_UPDATE_ENV = "AGENTLOOM_DISABLE_UPDATE_NOTIFIER";
+const SKIP_COMMANDS = new Set([
+    "help",
+    "--help",
+    "-h",
+    "version",
+    "--version",
+    "-v",
+    "upgrade",
+]);
 export async function maybeNotifyVersionUpdate(options) {
-    if (process.env.AGENTLOOM_DISABLE_UPDATE_NOTIFIER === "1")
+    if (process.env[DISABLE_UPDATE_ENV] === "1")
         return;
-    if (!process.stdout.isTTY || !process.stderr.isTTY)
+    const loweredCommand = options.command.trim().toLowerCase();
+    if (SKIP_COMMANDS.has(loweredCommand))
         return;
-    const loweredCommand = options.command.toLowerCase();
-    if (loweredCommand === "help" ||
-        loweredCommand === "--help" ||
-        loweredCommand === "-h" ||
-        loweredCommand === "version" ||
-        loweredCommand === "--version" ||
-        loweredCommand === "-v") {
-        return;
-    }
     const packageName = options.packageName ?? "agentloom";
     const cache = readVersionCache();
-    if (cache.latestVersion &&
-        isNewerVersion(cache.latestVersion, options.currentVersion) &&
-        cache.lastNotifiedVersion !== cache.latestVersion) {
-        await promptAndUpdate(options.currentVersion, cache.latestVersion);
-        cache.lastNotifiedVersion = cache.latestVersion;
-        writeVersionCache(cache);
-    }
+    const latest = await resolveLatestVersion({
+        packageName,
+        cache,
+        forceFetch: false,
+    });
+    if (!latest)
+        return;
+    if (!isNewerVersion(latest, options.currentVersion))
+        return;
     const now = Date.now();
-    const lastChecked = parseTime(cache.lastCheckedAt);
-    if (lastChecked && now - lastChecked < CHECK_INTERVAL_MS) {
+    if (!shouldAttemptAutoUpgrade(cache, latest, now)) {
         return;
     }
-    const latest = await fetchLatestVersion(packageName);
-    if (!latest) {
-        cache.lastCheckedAt = new Date(now).toISOString();
+    const approved = await maybeConfirmAutoUpgrade(options.currentVersion, latest);
+    if (!approved) {
+        recordUpgradeAttempt(cache, latest, now);
         writeVersionCache(cache);
         return;
     }
-    cache.lastCheckedAt = new Date(now).toISOString();
-    cache.latestVersion = latest;
-    if (isNewerVersion(latest, options.currentVersion) &&
-        cache.lastNotifiedVersion !== latest) {
-        await promptAndUpdate(options.currentVersion, latest);
-        cache.lastNotifiedVersion = latest;
+    // Persist attempt before upgrade/rerun, because rerun success paths can exit the process.
+    recordUpgradeAttempt(cache, latest, now);
+    writeVersionCache(cache);
+    await promptAndUpdate(options.currentVersion, latest, {
+        packageName,
+        rerunArgs: options.argv,
+    });
+}
+export async function upgradeToLatest(options) {
+    const packageName = options.packageName ?? "agentloom";
+    const cache = readVersionCache();
+    const latest = await resolveLatestVersion({
+        packageName,
+        cache,
+        forceFetch: true,
+    });
+    if (!latest)
+        return "unavailable";
+    if (!isNewerVersion(latest, options.currentVersion)) {
+        return "already-latest";
     }
+    const result = await promptAndUpdate(options.currentVersion, latest, {
+        packageName,
+    });
+    const now = Date.now();
+    recordUpgradeAttempt(cache, latest, now);
     writeVersionCache(cache);
+    return result;
 }
 export function isNewerVersion(candidate, current) {
     const next = parseSemver(candidate);
@@ -111,24 +134,54 @@ function fetchLatestVersion(packageName) {
         req.on("error", () => resolve(null));
     });
 }
-export async function promptAndUpdate(current, latest) {
-    const accepted = await confirm({
-        message: `Update available: ${current} → ${latest}. Update now?`,
-        initialValue: true,
+export async function promptAndUpdate(current, latest, options = {}) {
+    if (!isNewerVersion(latest, current))
+        return "already-latest";
+    const packageName = options.packageName ?? "agentloom";
+    const rerunArgs = options.rerunArgs ?? [];
+    if (rerunArgs.length > 0 && isLikelyNpxExecution()) {
+        if (!canRunPackageViaNpx(packageName, latest)) {
+            console.error("\nAutomatic npx upgrade is currently unavailable; continuing with current version.\n");
+            return "failed";
+        }
+        console.log(`\nUpdate available: ${current} → ${latest}. Re-running with npx ${packageName}@${latest}...\n`);
+        const rerun = spawnSync("npx", ["--yes", `${packageName}@${latest}`, ...rerunArgs], {
+            stdio: "inherit",
+            env: buildChildEnv(),
+        });
+        if (rerun.error || rerun.status === null) {
+            console.error("\nAutomatic npx rerun failed after upgrade. Please run your command again.\n");
+            process.exit(1);
+            return "failed"; // unreachable, but satisfies type checker
+        }
+        process.exit(rerun.status);
+        return rerun.status === 0 ? "updated" : "failed"; // unreachable, but satisfies type checker
+    }
+    console.log(`\nUpdating ${packageName} ${current} → ${latest}...\n`);
+    const install = spawnSync("npm", ["i", "-g", `${packageName}@${latest}`], {
+        stdio: "inherit",
     });
-    if (isCancel(accepted) || !accepted)
-        return "declined";
-    console.log(`\nUpdating agentloom to ${latest}...\n`);
-    const result = spawnSync("npm", ["i", "-g", "agentloom"], {
+    if (install.status !== 0) {
+        console.error("\nAutomatic upgrade failed. Run `agentloom upgrade` to retry.\n");
+        return "failed";
+    }
+    if (rerunArgs.length === 0) {
+        console.log(`\nUpdated to ${latest}.\n`);
+        return "updated";
+    }
+    console.log(`\nUpdated to ${latest}. Re-running your command...\n`);
+    const invocation = buildRerunInvocation(rerunArgs);
+    const rerun = spawnSync(invocation.command, invocation.args, {
         stdio: "inherit",
+        env: buildChildEnv(),
     });
-    if (result.status === 0) {
-        console.log(`\nUpdated to ${latest}. Please re-run your command.\n`);
-        process.exit(0);
-        return "updated"; // unreachable, but satisfies type checker
+    if (rerun.error || rerun.status === null) {
+        console.error("\nAutomatic rerun failed after upgrade. Please run your command again.\n");
+        process.exit(1);
+        return "failed"; // unreachable, but satisfies type checker
     }
-    console.error(`\nUpdate failed. You can update manually: npm i -g agentloom\n`);
-    return "failed";
+    process.exit(rerun.status);
+    return "updated"; // unreachable, but satisfies type checker
 }
 function readVersionCache() {
     try {
@@ -158,3 +211,85 @@ function parseTime(value) {
         return null;
     return parsed;
 }
+async function resolveLatestVersion(options) {
+    const now = Date.now();
+    const lastChecked = parseTime(options.cache.lastCheckedAt);
+    const shouldFetch = options.forceFetch ||
+        !lastChecked ||
+        now - lastChecked >= CHECK_INTERVAL_MS;
+    if (!shouldFetch) {
+        return options.cache.latestVersion ?? null;
+    }
+    const fetched = await fetchLatestVersion(options.packageName);
+    options.cache.lastCheckedAt = new Date(now).toISOString();
+    if (fetched) {
+        options.cache.latestVersion = fetched;
+    }
+    writeVersionCache(options.cache);
+    if (options.forceFetch) {
+        return fetched ?? null;
+    }
+    return fetched ?? options.cache.latestVersion ?? null;
+}
+function shouldAttemptAutoUpgrade(cache, latest, now) {
+    const lastAttemptVersion = cache.lastUpgradeAttemptVersion ?? cache.lastAutoUpgradeVersion;
+    if (lastAttemptVersion !== latest)
+        return true;
+    const lastAttempt = parseTime(cache.lastUpgradeAttemptAt ?? cache.lastAutoUpgradeAt);
+    if (!lastAttempt)
+        return true;
+    return now - lastAttempt >= CHECK_INTERVAL_MS;
+}
+function isLikelyNpxExecution() {
+    const npmCommand = process.env.npm_command?.trim().toLowerCase();
+    if (npmCommand === "exec")
+        return true;
+    const argv1 = process.argv[1];
+    if (typeof argv1 !== "string" || argv1.length === 0)
+        return false;
+    return argv1.includes(`${path.sep}_npx${path.sep}`);
+}
+function buildChildEnv() {
+    return {
+        ...process.env,
+        [DISABLE_UPDATE_ENV]: "1",
+    };
+}
+export async function maybeConfirmAutoUpgrade(current, latest) {
+    if (!isInteractiveTty())
+        return true;
+    const approved = await confirm({
+        message: `Update available: ${current} → ${latest}. Upgrade now and re-run your command?`,
+        initialValue: true,
+    });
+    if (isCancel(approved) || approved !== true)
+        return false;
+    return true;
+}
+function isInteractiveTty() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY);
+}
+function recordUpgradeAttempt(cache, latest, now) {
+    cache.lastUpgradeAttemptVersion = latest;
+    cache.lastUpgradeAttemptAt = new Date(now).toISOString();
+}
+function canRunPackageViaNpx(packageName, version) {
+    const probe = spawnSync("npx", ["--yes", `${packageName}@${version}`, "--version"], {
+        stdio: "ignore",
+        env: buildChildEnv(),
+    });
+    return !probe.error && probe.status === 0;
+}
+function buildRerunInvocation(rerunArgs) {
+    const scriptPath = process.argv[1];
+    if (typeof scriptPath === "string" && scriptPath.trim().length > 0) {
+        return {
+            command: process.execPath,
+            args: [...process.execArgv, scriptPath, ...rerunArgs],
+        };
+    }
+    return {
+        command: "agentloom",
+        args: rerunArgs,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentloom",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Unified agent and MCP sync CLI for multi-provider AI tooling",
   "type": "module",
   "bin": {