agentloom 0.1.2 → 0.1.3

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
 

package/dist/cli.js

@@ -5,6 +5,7 @@ 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";
@@ -81,6 +82,9 @@ async function runRoutedCommand(route, parsed, cwd, command) {
             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/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

@@ -8,6 +8,7 @@ export declare function getFindHelpText(): string;
 export declare function getAddHelpText(): string;
 export declare function getUpdateHelpText(): 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,10 @@ 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
+  sync                       Migrate provider configs then generate provider outputs
   delete <source|name>       Delete imported entities by source or name
 
 Entity commands:
@@ -112,7 +114,7 @@ Example:
 `;
 }
 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 +127,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/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;