agentloom 0.1.2 → 0.1.4

package/README.md

@@ -1,15 +1,16 @@
 # agentloom
 
-`agentloom` is a unified CLI for managing agent definitions and MCP configuration across multiple AI coding tools.
+`agentloom` is a unified CLI for managing agent definitions and MCP configuration across multiple AI coding tools — Cursor, Claude, Copilot, Codex, OpenCode, Gemini, and Pi.
 
-It uses `.agents` as the canonical source of truth and syncs provider-native files for:
+For monorepo-level documentation and architecture context, see the [root README](../../README.md).
 
-- Cursor
-- Claude
-- Codex
-- OpenCode
-- Gemini
-- Copilot
+## Getting started
+
+```bash
+npx agentloom init
+```
+
+That's all you need. Agentloom picks up your existing provider configs, migrates them into a unified `.agents/` directory, and syncs everything back out to all your tools. From here on, manage your agents, commands, skills, and MCP servers in one place and run `agentloom sync` whenever you make changes.
 
 ## Install
 
@@ -54,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>`
 
@@ -117,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
@@ -130,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

@@ -5,9 +5,11 @@ import { runAddCommand } from "./commands/add.js";
 import { runCommandCommand } from "./commands/command.js";
 import { runDeleteCommand } from "./commands/delete.js";
 import { runFindCommand } from "./commands/find.js";
+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";
@@ -35,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);
@@ -60,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));
     }
@@ -75,12 +78,18 @@ 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;
             case "delete":
                 await runDeleteCommand(parsed, cwd);
                 return;
+            case "init":
+                await runInitCommand(parsed, cwd);
+                return;
             default:
                 throw new Error(formatUnknownCommandError(command));
         }

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,14 @@
+import { getInitHelpText } from "../core/copy.js";
+import { runScopedSyncCommand } from "./sync.js";
+export async function runInitCommand(argv, cwd) {
+    if (argv.help) {
+        console.log(getInitHelpText());
+        return;
+    }
+    await runScopedSyncCommand({
+        argv,
+        cwd,
+        target: "all",
+        skipSync: Boolean(argv["no-sync"]),
+    });
+}

package/dist/commands/mcp.js

@@ -1,3 +1,4 @@
+import { ALL_PROVIDERS } from "../types.js";
 import { getStringArrayFlag, parseProvidersFlag } from "../core/argv.js";
 import { formatUsageError, getMcpAddHelpText, getMcpDeleteHelpText, getMcpHelpText, getMcpListHelpText, getMcpServerHelpText, } from "../core/copy.js";
 import { readCanonicalMcp, writeCanonicalMcp } from "../core/mcp.js";
@@ -244,15 +245,7 @@ function runMcpAdd(paths, argv, name) {
     }
     else {
         const providerMap = {};
-        const allProviders = [
-            "cursor",
-            "claude",
-            "codex",
-            "opencode",
-            "gemini",
-            "copilot",
-        ];
-        for (const provider of allProviders) {
+        for (const provider of ALL_PROVIDERS) {
             providerMap[provider] = providers.includes(provider)
                 ? { ...baseConfig }
                 : false;

package/dist/commands/skills.js

@@ -1,12 +1,11 @@
 import path from "node:path";
-import { parseProvidersFlag } from "../core/argv.js";
 import { formatUsageError } from "../core/copy.js";
-import { applySkillProviderSideEffects, parseSkillsDir, } from "../core/skills.js";
-import { formatSyncSummary, resolveProvidersForSync, syncFromCanonical, } from "../sync/index.js";
+import { parseSkillsDir } from "../core/skills.js";
 import { runScopedAddCommand } from "./add.js";
 import { runScopedDeleteCommand } from "./delete.js";
-import { getNonInteractiveMode, resolvePathsForCommand, } from "./entity-utils.js";
+import { resolvePathsForCommand } from "./entity-utils.js";
 import { runScopedFindCommand } from "./find.js";
+import { runScopedSyncCommand } from "./sync.js";
 import { runScopedUpdateCommand } from "./update.js";
 export async function runSkillCommand(argv, cwd) {
     const action = argv._[1];
@@ -79,29 +78,9 @@ export async function runSkillCommand(argv, cwd) {
         });
         return;
     }
-    const paths = await resolvePathsForCommand(argv, cwd);
-    const nonInteractive = getNonInteractiveMode(argv);
-    const explicitProviders = parseProvidersFlag(argv.providers);
-    const providers = await resolveProvidersForSync({
-        paths,
-        explicitProviders,
-        nonInteractive,
-    });
-    applySkillProviderSideEffects({
-        paths,
-        providers,
-        dryRun: Boolean(argv["dry-run"]),
-        warn(message) {
-            console.warn(`Warning: ${message}`);
-        },
-    });
-    const summary = await syncFromCanonical({
-        paths,
-        providers,
-        yes: Boolean(argv.yes),
-        nonInteractive,
-        dryRun: Boolean(argv["dry-run"]),
+    await runScopedSyncCommand({
+        argv,
+        cwd,
         target: "skill",
     });
-    console.log(formatSyncSummary(summary, paths.agentsRoot));
 }

package/dist/commands/sync.d.ts

@@ -5,4 +5,5 @@ export declare function runScopedSyncCommand(options: {
     argv: ParsedArgs;
     cwd: string;
     target: EntityType | "all";
+    skipSync?: boolean;
 }): Promise<void>;

package/dist/commands/sync.js

@@ -1,7 +1,11 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { parseProvidersFlag } from "../core/argv.js";
 import { getSyncHelpText } from "../core/copy.js";
+import { formatMigrationSummary, initializeCanonicalLayout, migrateProviderStateToCanonical, MigrationConflictError, } from "../core/migration.js";
 import { getNonInteractiveMode, resolvePathsForCommand, } from "./entity-utils.js";
-import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+import { formatSyncSummary, resolveProvidersForSync, syncFromCanonical, } from "../sync/index.js";
 export async function runSyncCommand(argv, cwd) {
     if (argv.help) {
         console.log(getSyncHelpText());
@@ -14,14 +18,81 @@ export async function runSyncCommand(argv, cwd) {
     });
 }
 export async function runScopedSyncCommand(options) {
-    const paths = await resolvePathsForCommand(options.argv, options.cwd);
-    const summary = await syncFromCanonical({
-        paths,
-        providers: parseProvidersFlag(options.argv.providers),
-        yes: Boolean(options.argv.yes),
-        nonInteractive: getNonInteractiveMode(options.argv),
-        dryRun: Boolean(options.argv["dry-run"]),
-        target: options.target,
-    });
-    console.log(formatSyncSummary(summary, paths.agentsRoot));
+    const nonInteractive = getNonInteractiveMode(options.argv);
+    let cleanupDryRunPaths;
+    try {
+        const paths = await resolvePathsForCommand(options.argv, options.cwd);
+        const explicitProviders = parseProvidersFlag(options.argv.providers);
+        const providers = await resolveProvidersForSync({
+            paths,
+            explicitProviders,
+            nonInteractive,
+        });
+        const dryRun = Boolean(options.argv["dry-run"]);
+        const effectivePaths = dryRun
+            ? createDryRunCanonicalPaths(paths)
+            : { paths, cleanup: undefined };
+        cleanupDryRunPaths = effectivePaths.cleanup;
+        initializeCanonicalLayout(effectivePaths.paths, providers);
+        const migrationSummary = await migrateProviderStateToCanonical({
+            paths: effectivePaths.paths,
+            providers,
+            target: options.target,
+            yes: Boolean(options.argv.yes),
+            nonInteractive,
+            dryRun,
+            materializeCanonical: dryRun,
+        });
+        console.log(formatMigrationSummary(migrationSummary));
+        if (options.skipSync) {
+            return;
+        }
+        const syncSummary = await syncFromCanonical({
+            paths: effectivePaths.paths,
+            providers,
+            yes: Boolean(options.argv.yes),
+            nonInteractive,
+            dryRun,
+            target: options.target,
+        });
+        console.log("");
+        console.log(formatSyncSummary(syncSummary, paths.agentsRoot));
+    }
+    catch (error) {
+        if (error instanceof MigrationConflictError) {
+            console.error(error.message);
+            process.exit(2);
+        }
+        throw error;
+    }
+    finally {
+        cleanupDryRunPaths?.();
+    }
+}
+function createDryRunCanonicalPaths(paths) {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentloom-dry-run-"));
+    const tempAgentsRoot = path.join(tempRoot, ".agents");
+    if (fs.existsSync(paths.agentsRoot) &&
+        fs.statSync(paths.agentsRoot).isDirectory()) {
+        fs.cpSync(paths.agentsRoot, tempAgentsRoot, {
+            recursive: true,
+            force: true,
+        });
+    }
+    return {
+        paths: {
+            ...paths,
+            agentsRoot: tempAgentsRoot,
+            agentsDir: path.join(tempAgentsRoot, "agents"),
+            commandsDir: path.join(tempAgentsRoot, "commands"),
+            skillsDir: path.join(tempAgentsRoot, "skills"),
+            mcpPath: path.join(tempAgentsRoot, "mcp.json"),
+            lockPath: path.join(tempAgentsRoot, "agents.lock.json"),
+            settingsPath: path.join(tempAgentsRoot, "settings.local.json"),
+            manifestPath: path.join(tempAgentsRoot, ".sync-manifest.json"),
+        },
+        cleanup() {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        },
+    };
 }

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/argv.js

@@ -1,4 +1,5 @@
 import minimist from "minimist";
+import { ALL_PROVIDERS } from "../types.js";
 export function parseArgs(argv) {
     const parsed = minimist(argv, {
         boolean: ["global", "local", "yes", "no-sync", "dry-run", "json", "help"],
@@ -50,16 +51,11 @@ export function parseProvidersFlag(input) {
         .map((item) => item.toLowerCase());
     const validProviders = [];
     for (const provider of parsed) {
-        if (provider === "cursor" ||
-            provider === "claude" ||
-            provider === "codex" ||
-            provider === "opencode" ||
-            provider === "gemini" ||
-            provider === "copilot") {
+        if (ALL_PROVIDERS.includes(provider)) {
             validProviders.push(provider);
             continue;
         }
-        throw new Error(`Unknown provider: ${provider}. Expected one of: cursor, claude, codex, opencode, gemini, copilot.`);
+        throw new Error(`Unknown provider: ${provider}. Expected one of: ${ALL_PROVIDERS.join(", ")}.`);
     }
     return [...new Set(validProviders)];
 }

package/dist/core/copy.d.ts

@@ -7,7 +7,9 @@ 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;
 export declare function getCommandAddHelpText(): string;
 export declare function getCommandListHelpText(): string;

package/dist/core/copy.js

@@ -1,4 +1,5 @@
-const PROVIDERS_CSV = "cursor,claude,codex,opencode,gemini,copilot";
+import { ALL_PROVIDERS } from "../types.js";
+const PROVIDERS_CSV = ALL_PROVIDERS.join(",");
 export function getRootHelpText() {
     return `agentloom - unified canonical agent package manager
 
@@ -8,9 +9,11 @@ Usage:
 
 Aggregate commands:
   add <source>               Import agents/commands/mcp/skills from a source
+  init                       Bootstrap canonical files, migrate providers, then sync
   find <query>               Search remote + local entities
   update [source]            Refresh lockfile-managed imports
-  sync                       Generate provider-specific outputs
+  upgrade                    Install the latest CLI release
+  sync                       Migrate provider configs then generate provider outputs
   delete <source|name>       Delete imported entities by source or name
 
 Entity commands:
@@ -111,8 +114,20 @@ 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 `Generate provider-specific files from canonical .agents data.
+    return `Migrate provider configs into canonical .agents data, then generate provider-specific outputs.
 
 Usage:
   agentloom sync [options]
@@ -125,6 +140,20 @@ Options:
   --dry-run                  Show file changes without writing
 `;
 }
+export function getInitHelpText() {
+    return `Bootstrap canonical .agents files, migrate provider configs into canonical state, and sync providers.
+
+Usage:
+  agentloom init [options]
+
+Options:
+  --local | --global         Choose canonical scope (interactive prompts when omitted)
+  --providers <csv>          Limit providers (${PROVIDERS_CSV})
+  --yes                      Skip interactive conflict prompts and fail fast in non-interactive flows
+  --no-sync                  Skip sync after canonical bootstrap + migration
+  --dry-run                  Show planned migration/sync changes without writing
+`;
+}
 export function getCommandHelpText() {
     return `Manage canonical command entities.
 

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/migration.d.ts

@@ -0,0 +1,28 @@
+import type { EntityType, Provider, ScopePaths } from "../types.js";
+export interface MigrationOptions {
+    paths: ScopePaths;
+    providers: Provider[];
+    target: EntityType | "all";
+    yes?: boolean;
+    nonInteractive?: boolean;
+    dryRun?: boolean;
+    materializeCanonical?: boolean;
+}
+export interface MigrationEntitySummary {
+    detected: number;
+    imported: number;
+    conflicts: number;
+    skipped: number;
+}
+export interface MigrationSummary {
+    providers: Provider[];
+    target: EntityType | "all";
+    entities: Record<EntityType, MigrationEntitySummary>;
+}
+export declare class MigrationConflictError extends Error {
+    constructor(message: string);
+}
+export declare function createEmptyMigrationSummary(providers: Provider[], target: EntityType | "all"): MigrationSummary;
+export declare function initializeCanonicalLayout(paths: ScopePaths, providers?: Provider[]): void;
+export declare function migrateProviderStateToCanonical(options: MigrationOptions): Promise<MigrationSummary>;
+export declare function formatMigrationSummary(summary: MigrationSummary): string;