agentloom 0.1.0

package/dist/commands/update.js

@@ -0,0 +1,71 @@
+import { importSource, NonInteractiveConflictError } from "../core/importer.js";
+import { readLockfile } from "../core/lockfile.js";
+import { resolveScope } from "../core/scope.js";
+import { prepareSource } from "../core/sources.js";
+import { parseProvidersFlag } from "../core/argv.js";
+import { getUpdateHelpText } from "../core/copy.js";
+import { formatSyncSummary, syncFromCanonical } from "../sync/index.js";
+export async function runUpdateCommand(argv, cwd) {
+    if (argv.help) {
+        console.log(getUpdateHelpText());
+        return;
+    }
+    const nonInteractive = !(process.stdin.isTTY && process.stdout.isTTY);
+    const paths = await resolveScope({
+        cwd,
+        global: Boolean(argv.global),
+        local: Boolean(argv.local),
+        interactive: !nonInteractive,
+    });
+    const lockfile = readLockfile(paths);
+    if (lockfile.entries.length === 0) {
+        console.log(`No lock entries found in ${paths.lockPath}.`);
+        return;
+    }
+    let updated = 0;
+    let skipped = 0;
+    for (const entry of lockfile.entries) {
+        const probe = prepareSource({
+            source: entry.source,
+            ref: entry.requestedRef,
+            subdir: entry.subdir,
+        });
+        const hasNewCommit = probe.resolvedCommit !== entry.resolvedCommit;
+        probe.cleanup();
+        if (!hasNewCommit) {
+            skipped += 1;
+            continue;
+        }
+        try {
+            await importSource({
+                source: entry.source,
+                ref: entry.requestedRef,
+                subdir: entry.subdir,
+                yes: Boolean(argv.yes),
+                nonInteractive,
+                paths,
+            });
+            updated += 1;
+        }
+        catch (err) {
+            if (err instanceof NonInteractiveConflictError) {
+                console.error(err.message);
+                process.exit(2);
+            }
+            throw err;
+        }
+    }
+    console.log(`Updated entries: ${updated}`);
+    console.log(`Unchanged entries: ${skipped}`);
+    if (updated > 0 && !argv["no-sync"]) {
+        const syncSummary = await syncFromCanonical({
+            paths,
+            providers: parseProvidersFlag(argv.providers),
+            yes: Boolean(argv.yes),
+            nonInteractive,
+            dryRun: Boolean(argv["dry-run"]),
+        });
+        console.log("");
+        console.log(formatSyncSummary(syncSummary, paths.agentsRoot));
+    }
+}

package/dist/core/agents.d.ts

@@ -0,0 +1,7 @@
+import type { AgentFrontmatter, CanonicalAgent, Provider } from "../types.js";
+export declare function parseAgentsDir(agentsDir: string): CanonicalAgent[];
+export declare function parseAgentMarkdown(raw: string, sourcePath: string, fileName?: string): CanonicalAgent;
+export declare function buildAgentMarkdown(frontmatter: AgentFrontmatter, body: string): string;
+export declare function targetFileNameForAgent(agent: CanonicalAgent): string;
+export declare function getProviderConfig(frontmatter: AgentFrontmatter, provider: Provider): Record<string, unknown> | null;
+export declare function isProviderEnabled(frontmatter: AgentFrontmatter, provider: Provider): boolean;

package/dist/core/agents.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import YAML from "yaml";
+import { isObject, slugify } from "./fs.js";
+export function parseAgentsDir(agentsDir) {
+    if (!fs.existsSync(agentsDir))
+        return [];
+    const files = fs
+        .readdirSync(agentsDir)
+        .filter((entry) => entry.endsWith(".md"))
+        .sort();
+    return files.map((entry) => {
+        const filePath = path.join(agentsDir, entry);
+        const raw = fs.readFileSync(filePath, "utf8");
+        return parseAgentMarkdown(raw, filePath, entry);
+    });
+}
+export function parseAgentMarkdown(raw, sourcePath, fileName = path.basename(sourcePath)) {
+    const parsed = matter(raw);
+    if (!isObject(parsed.data)) {
+        throw new Error(`Invalid frontmatter in ${sourcePath}: expected object.`);
+    }
+    const frontmatter = parsed.data;
+    if (typeof frontmatter.name !== "string" || frontmatter.name.trim() === "") {
+        throw new Error(`Invalid frontmatter in ${sourcePath}: missing \`name\`.`);
+    }
+    if (typeof frontmatter.description !== "string" ||
+        frontmatter.description.trim() === "") {
+        throw new Error(`Invalid frontmatter in ${sourcePath}: missing \`description\`.`);
+    }
+    const normalizedName = frontmatter.name.trim();
+    const normalizedDescription = frontmatter.description.trim();
+    const body = parsed.content.trimStart();
+    return {
+        name: normalizedName,
+        description: normalizedDescription,
+        body,
+        frontmatter: {
+            ...frontmatter,
+            name: normalizedName,
+            description: normalizedDescription,
+        },
+        sourcePath,
+        fileName,
+    };
+}
+export function buildAgentMarkdown(frontmatter, body) {
+    const fm = YAML.stringify(frontmatter).trimEnd();
+    const normalizedBody = body.trimStart();
+    return `---\n${fm}\n---\n\n${normalizedBody}${normalizedBody.endsWith("\n") ? "" : "\n"}`;
+}
+export function targetFileNameForAgent(agent) {
+    const slug = slugify(agent.name);
+    return `${slug || "agent"}.md`;
+}
+export function getProviderConfig(frontmatter, provider) {
+    const value = frontmatter[provider];
+    if (value === false)
+        return null;
+    if (isObject(value))
+        return value;
+    return {};
+}
+export function isProviderEnabled(frontmatter, provider) {
+    return frontmatter[provider] !== false;
+}

package/dist/core/argv.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedArgs } from "minimist";
+import type { Provider } from "../types.js";
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function parseProvidersFlag(input: unknown): Provider[] | undefined;
+export declare function getStringArrayFlag(value: unknown, fallback?: string[]): string[];

package/dist/core/argv.js

@@ -0,0 +1,52 @@
+import minimist from "minimist";
+export function parseArgs(argv) {
+    return minimist(argv, {
+        boolean: ["global", "local", "yes", "no-sync", "dry-run", "json", "help"],
+        string: ["ref", "subdir", "providers", "rename", "command", "url"],
+        alias: {
+            g: "global",
+            l: "local",
+            y: "yes",
+            h: "help",
+        },
+        "--": true,
+    });
+}
+export function parseProvidersFlag(input) {
+    if (typeof input !== "string" || input.trim() === "")
+        return undefined;
+    const parsed = input
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map((item) => item.toLowerCase());
+    const validProviders = [];
+    for (const provider of parsed) {
+        if (provider === "cursor" ||
+            provider === "claude" ||
+            provider === "codex" ||
+            provider === "opencode" ||
+            provider === "gemini" ||
+            provider === "copilot") {
+            validProviders.push(provider);
+            continue;
+        }
+        throw new Error(`Unknown provider: ${provider}. Expected one of: cursor, claude, codex, opencode, gemini, copilot.`);
+    }
+    return [...new Set(validProviders)];
+}
+export function getStringArrayFlag(value, fallback = []) {
+    if (Array.isArray(value)) {
+        return value
+            .flatMap((item) => String(item).split(","))
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    return fallback;
+}

package/dist/core/copy.d.ts

@@ -0,0 +1,16 @@
+type UsageErrorInput = {
+    issue: string;
+    usage: string;
+    example?: string;
+};
+export declare function getRootHelpText(): string;
+export declare function getAddHelpText(): string;
+export declare function getUpdateHelpText(): string;
+export declare function getSyncHelpText(): string;
+export declare function getMcpHelpText(): string;
+export declare function getMcpAddHelpText(): string;
+export declare function getMcpListHelpText(): string;
+export declare function getMcpDeleteHelpText(): string;
+export declare function formatUsageError(input: UsageErrorInput): string;
+export declare function formatUnknownCommandError(command: string): string;
+export {};

package/dist/core/copy.js

@@ -0,0 +1,167 @@
+const PROVIDERS_CSV = "cursor,claude,codex,opencode,gemini,copilot";
+export function getRootHelpText() {
+    return `agentloom - unified agent and MCP sync CLI
+
+Usage:
+  agentloom <command> [options]
+
+Commands:
+  skills ...                 Pass through to "npx skills ..." (vercel-labs/skills)
+  add <source>               Import agents and MCP from a repo source
+  update                     Refresh lockfile-managed imports
+  sync                       Generate provider-specific outputs
+  mcp <add|list|delete>      Manage canonical MCP servers
+  help                       Show this help text
+
+Common options:
+  --local                    Use .agents from current workspace
+  --global                   Use ~/.agents
+  --yes                      Skip interactive confirmations
+  --no-sync                  Skip post-change sync (mutating commands)
+  --providers <csv>          Limit sync providers (${PROVIDERS_CSV})
+  --dry-run                  Print planned sync changes without writing files
+
+Examples:
+  agentloom add vercel-labs/skills
+  agentloom add /repo --subdir packages/agents
+  agentloom update --local
+  agentloom sync --providers codex,claude,cursor
+  agentloom mcp add browser-tools --command npx --arg browser-tools-mcp
+  agentloom skills add vercel-labs/skills
+`;
+}
+export function getAddHelpText() {
+    return `Import canonical agents and MCP from a source repository.
+
+Usage:
+  agentloom add <source> [options]
+
+Options:
+  --ref <ref>                Git ref (branch/tag/commit) for remote sources
+  --subdir <path>            Subdirectory inside source repo
+  --rename <name>            Rename imported agent (single-agent import only)
+  --local | --global         Choose destination scope
+  --yes                      Skip conflict prompts (overwrite/merge defaults)
+  --no-sync                  Do not run sync after import
+  --providers <csv>          Providers for post-import sync (${PROVIDERS_CSV})
+  --dry-run                  Show sync plan without writing provider files
+
+Example:
+  agentloom add vercel-labs/skills --subdir skills --providers codex,claude
+`;
+}
+export function getUpdateHelpText() {
+    return `Refresh lockfile-managed sources and re-import updated revisions.
+
+Usage:
+  agentloom update [options]
+
+Options:
+  --local | --global         Choose lockfile scope
+  --yes                      Skip conflict prompts during re-import
+  --no-sync                  Do not run sync after updates
+  --providers <csv>          Providers for post-update sync (${PROVIDERS_CSV})
+  --dry-run                  Show sync plan without writing provider files
+
+Example:
+  agentloom update --local --providers codex,cursor
+`;
+}
+export function getSyncHelpText() {
+    return `Generate provider-specific agent and MCP files from canonical .agents data.
+
+Usage:
+  agentloom sync [options]
+
+Options:
+  --local | --global         Choose canonical scope
+  --providers <csv>          Limit providers (${PROVIDERS_CSV})
+  --yes                      Auto-delete stale generated files
+  --dry-run                  Show file changes without writing
+
+Example:
+  agentloom sync --local --providers codex,claude,cursor --dry-run
+`;
+}
+export function getMcpHelpText() {
+    return `Manage canonical MCP servers in .agents/mcp.json.
+
+Usage:
+  agentloom mcp <command> [options]
+
+Commands:
+  add <name>                 Add or update an MCP server
+  list                       List configured MCP servers
+  delete <name>              Remove an MCP server
+
+Shared options:
+  --local | --global         Choose canonical scope
+  --no-sync                  Skip post-change sync (add/delete only)
+  --providers <csv>          Providers for post-change sync (${PROVIDERS_CSV})
+
+Examples:
+  agentloom mcp add browser --command npx --arg browser-tools-mcp
+  agentloom mcp list --json
+  agentloom mcp delete browser
+`;
+}
+export function getMcpAddHelpText() {
+    return `Add or update an MCP server in canonical .agents/mcp.json.
+
+Usage:
+  agentloom mcp add <name> (--url <url> | --command <cmd>) [options]
+
+Options:
+  --arg <value>              Repeatable command argument
+  --env KEY=VALUE            Repeatable environment variable
+  --providers <csv>          Provider-specific server assignment (${PROVIDERS_CSV})
+  --local | --global         Choose canonical scope
+  --no-sync                  Skip post-change sync
+
+Examples:
+  agentloom mcp add browser --command npx --arg browser-tools-mcp
+  agentloom mcp add docs --url https://example.com/mcp --providers codex,claude
+`;
+}
+export function getMcpListHelpText() {
+    return `List canonical MCP servers.
+
+Usage:
+  agentloom mcp list [options]
+
+Options:
+  --json                     Print raw JSON
+  --local | --global         Choose canonical scope
+
+Example:
+  agentloom mcp list --json
+`;
+}
+export function getMcpDeleteHelpText() {
+    return `Delete an MCP server from canonical .agents/mcp.json.
+
+Usage:
+  agentloom mcp delete <name> [options]
+
+Options:
+  --local | --global         Choose canonical scope
+  --no-sync                  Skip post-change sync
+
+Example:
+  agentloom mcp delete browser
+`;
+}
+export function formatUsageError(input) {
+    const lines = [`Issue: ${input.issue}`, `Usage: ${input.usage}`];
+    if (input.example) {
+        lines.push(`Example: ${input.example}`);
+    }
+    return lines.join("\n");
+}
+export function formatUnknownCommandError(command) {
+    return formatUsageError({
+        issue: `Unknown command "${command}".`,
+        usage: "agentloom --help",
+        example: "agentloom sync --local",
+    });
+}

package/dist/core/fs.d.ts

@@ -0,0 +1,13 @@
+export declare function ensureDir(dirPath: string): void;
+export declare function readTextIfExists(filePath: string): string | null;
+export declare function readJsonIfExists<T>(filePath: string): T | null;
+export declare function writeJsonAtomic(filePath: string, value: unknown): void;
+export declare function writeTextAtomic(filePath: string, content: string): void;
+export declare function listMarkdownFiles(dirPath: string): string[];
+export declare function hashContent(input: string): string;
+export declare function hashFiles(filePaths: string[]): string;
+export declare function slugify(input: string): string;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function toPosixPath(filePath: string): string;
+export declare function relativePosix(fromPath: string, toPath: string): string;
+export declare function removeFileIfExists(filePath: string): void;

package/dist/core/fs.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+export function readTextIfExists(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    return fs.readFileSync(filePath, "utf8");
+}
+export function readJsonIfExists(filePath) {
+    const text = readTextIfExists(filePath);
+    if (text === null)
+        return null;
+    return JSON.parse(text);
+}
+export function writeJsonAtomic(filePath, value) {
+    writeTextAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function writeTextAtomic(filePath, content) {
+    ensureDir(path.dirname(filePath));
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tempPath, content, "utf8");
+    fs.renameSync(tempPath, filePath);
+}
+export function listMarkdownFiles(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    return fs
+        .readdirSync(dirPath)
+        .filter((entry) => entry.endsWith(".md") || entry.endsWith(".mdc"))
+        .map((entry) => path.join(dirPath, entry));
+}
+export function hashContent(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function hashFiles(filePaths) {
+    const hasher = createHash("sha256");
+    for (const filePath of [...filePaths].sort()) {
+        hasher.update(filePath);
+        hasher.update("\0");
+        hasher.update(fs.readFileSync(filePath));
+        hasher.update("\0");
+    }
+    return hasher.digest("hex");
+}
+export function slugify(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function toPosixPath(filePath) {
+    return filePath.split(path.sep).join("/");
+}
+export function relativePosix(fromPath, toPath) {
+    return toPosixPath(path.relative(fromPath, toPath));
+}
+export function removeFileIfExists(filePath) {
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}

package/dist/core/importer.d.ts

@@ -0,0 +1,21 @@
+import type { ScopePaths } from "../types.js";
+export declare class NonInteractiveConflictError extends Error {
+    constructor(message: string);
+}
+export interface ImportOptions {
+    source: string;
+    ref?: string;
+    subdir?: string;
+    rename?: string;
+    yes?: boolean;
+    nonInteractive?: boolean;
+    paths: ScopePaths;
+}
+export interface ImportSummary {
+    source: string;
+    sourceType: "local" | "github" | "git";
+    importedAgents: string[];
+    importedMcpServers: string[];
+    resolvedCommit: string;
+}
+export declare function importSource(options: ImportOptions): Promise<ImportSummary>;