agentloom 0.1.0

package/dist/core/importer.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cancel, isCancel, select, text as promptText } from "@clack/prompts";
+import { buildAgentMarkdown, parseAgentsDir, targetFileNameForAgent, } from "./agents.js";
+import { ensureDir, hashContent, readJsonIfExists, relativePosix, slugify, writeTextAtomic, } from "./fs.js";
+import { readLockfile, upsertLockEntry, writeLockfile } from "./lockfile.js";
+import { readCanonicalMcp, writeCanonicalMcp } from "./mcp.js";
+import { discoverSourceAgentsDir, discoverSourceMcpPath, prepareSource, } from "./sources.js";
+export class NonInteractiveConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NonInteractiveConflictError";
+    }
+}
+export async function importSource(options) {
+    const prepared = prepareSource({
+        source: options.source,
+        ref: options.ref,
+        subdir: options.subdir,
+    });
+    try {
+        const sourceAgentsDir = discoverSourceAgentsDir(prepared.importRoot);
+        const sourceMcpPath = discoverSourceMcpPath(prepared.importRoot);
+        const sourceAgents = parseAgentsDir(sourceAgentsDir);
+        if (sourceAgents.length === 0) {
+            throw new Error(`No agent files found in ${sourceAgentsDir}.`);
+        }
+        ensureDir(options.paths.agentsDir);
+        const importedAgents = [];
+        const importedAgentHashes = [];
+        for (const [index, agent] of sourceAgents.entries()) {
+            let targetFileName = targetFileNameForAgent(agent);
+            if (options.rename && sourceAgents.length === 1) {
+                targetFileName = `${slugify(options.rename) || "agent"}.md`;
+            }
+            const resolvedFileName = await resolveAgentConflict({
+                targetFileName,
+                agentContent: buildAgentMarkdown(agent.frontmatter, agent.body),
+                paths: options.paths,
+                yes: !!options.yes,
+                nonInteractive: !!options.nonInteractive,
+                promptLabel: `${agent.name} (${index + 1}/${sourceAgents.length})`,
+            });
+            if (!resolvedFileName)
+                continue;
+            const targetPath = path.join(options.paths.agentsDir, resolvedFileName);
+            const content = buildAgentMarkdown(agent.frontmatter, agent.body);
+            writeTextAtomic(targetPath, content);
+            importedAgents.push(relativePosix(options.paths.agentsRoot, targetPath));
+            importedAgentHashes.push(hashContent(content));
+        }
+        const importedMcpServers = [];
+        if (sourceMcpPath) {
+            const sourceMcp = normalizeMcp(readJsonIfExists(sourceMcpPath));
+            const targetMcp = readCanonicalMcp(options.paths);
+            const merged = await resolveMcpConflict({
+                sourceMcp,
+                targetMcp,
+                yes: !!options.yes,
+                nonInteractive: !!options.nonInteractive,
+            });
+            writeCanonicalMcp(options.paths, merged);
+            importedMcpServers.push(...Object.keys(sourceMcp.mcpServers));
+        }
+        const lockfile = readLockfile(options.paths);
+        const contentHash = hashContent(JSON.stringify({
+            agents: importedAgentHashes,
+            mcp: importedMcpServers,
+        }));
+        const lockEntry = {
+            source: prepared.spec.source,
+            sourceType: prepared.spec.type,
+            requestedRef: options.ref,
+            resolvedCommit: prepared.resolvedCommit,
+            subdir: options.subdir,
+            importedAt: new Date().toISOString(),
+            importedAgents,
+            importedMcpServers,
+            contentHash,
+        };
+        upsertLockEntry(lockfile, lockEntry);
+        writeLockfile(options.paths, lockfile);
+        return {
+            source: prepared.spec.source,
+            sourceType: prepared.spec.type,
+            importedAgents,
+            importedMcpServers,
+            resolvedCommit: prepared.resolvedCommit,
+        };
+    }
+    finally {
+        prepared.cleanup();
+    }
+}
+async function resolveAgentConflict(options) {
+    const targetPath = path.join(options.paths.agentsDir, options.targetFileName);
+    if (!fs.existsSync(targetPath))
+        return options.targetFileName;
+    const existing = fs.readFileSync(targetPath, "utf8");
+    if (existing === options.agentContent)
+        return options.targetFileName;
+    if (options.yes) {
+        return options.targetFileName;
+    }
+    if (options.nonInteractive) {
+        throw new NonInteractiveConflictError(`Conflict for ${options.targetFileName}. Use --yes or run interactively.`);
+    }
+    const choice = await select({
+        message: `Agent conflict for ${options.promptLabel}`,
+        options: [
+            { value: "overwrite", label: `Overwrite ${options.targetFileName}` },
+            { value: "skip", label: "Skip this agent" },
+            { value: "rename", label: "Rename imported agent" },
+        ],
+    });
+    if (isCancel(choice)) {
+        cancel("Operation cancelled.");
+        process.exit(1);
+    }
+    if (choice === "skip")
+        return null;
+    if (choice === "rename") {
+        const entered = await promptText({
+            message: `New filename (without extension) for ${options.promptLabel}`,
+            placeholder: options.targetFileName.replace(/\.md$/, ""),
+            validate(value) {
+                if (!value.trim())
+                    return "Name is required.";
+                if (/[\\/]/.test(value))
+                    return "Use a simple filename.";
+                return undefined;
+            },
+        });
+        if (isCancel(entered)) {
+            cancel("Operation cancelled.");
+            process.exit(1);
+        }
+        const renamedFileName = `${slugify(String(entered)) || "agent"}.md`;
+        return resolveAgentConflict({
+            ...options,
+            targetFileName: renamedFileName,
+        });
+    }
+    return options.targetFileName;
+}
+function normalizeMcp(raw) {
+    if (!raw) {
+        return {
+            version: 1,
+            mcpServers: {},
+        };
+    }
+    if (typeof raw.mcpServers === "object" && raw.mcpServers !== null) {
+        return {
+            version: 1,
+            mcpServers: raw.mcpServers,
+        };
+    }
+    return {
+        version: 1,
+        mcpServers: {},
+    };
+}
+async function resolveMcpConflict(options) {
+    const sourceNames = Object.keys(options.sourceMcp.mcpServers);
+    const targetNames = new Set(Object.keys(options.targetMcp.mcpServers));
+    const overlap = sourceNames.filter((name) => targetNames.has(name));
+    if (overlap.length === 0 || options.yes) {
+        return mergeMcp(options.targetMcp, options.sourceMcp);
+    }
+    if (options.nonInteractive) {
+        throw new NonInteractiveConflictError("MCP server conflicts found. Use --yes or run interactively.");
+    }
+    const choice = await select({
+        message: `MCP conflicts detected for: ${overlap.join(", ")}`,
+        options: [
+            { value: "merge", label: "Merge (source servers override overlaps)" },
+            { value: "replace", label: "Replace destination MCP with source MCP" },
+        ],
+    });
+    if (isCancel(choice)) {
+        cancel("Operation cancelled.");
+        process.exit(1);
+    }
+    if (choice === "replace") {
+        return {
+            version: 1,
+            mcpServers: { ...options.sourceMcp.mcpServers },
+        };
+    }
+    return mergeMcp(options.targetMcp, options.sourceMcp);
+}
+function mergeMcp(target, source) {
+    return {
+        version: 1,
+        mcpServers: {
+            ...target.mcpServers,
+            ...source.mcpServers,
+        },
+    };
+}

package/dist/core/lockfile.d.ts

@@ -0,0 +1,4 @@
+import type { AgentsLockFile, LockEntry, ScopePaths } from "../types.js";
+export declare function readLockfile(paths: ScopePaths): AgentsLockFile;
+export declare function writeLockfile(paths: ScopePaths, lockfile: AgentsLockFile): void;
+export declare function upsertLockEntry(lockfile: AgentsLockFile, entry: LockEntry): void;

package/dist/core/lockfile.js

@@ -0,0 +1,25 @@
+import { readJsonIfExists, writeJsonAtomic } from "./fs.js";
+const EMPTY_LOCK = {
+    version: 1,
+    entries: [],
+};
+export function readLockfile(paths) {
+    const lock = readJsonIfExists(paths.lockPath);
+    if (!lock || lock.version !== 1 || !Array.isArray(lock.entries)) {
+        return { ...EMPTY_LOCK };
+    }
+    return lock;
+}
+export function writeLockfile(paths, lockfile) {
+    writeJsonAtomic(paths.lockPath, lockfile);
+}
+export function upsertLockEntry(lockfile, entry) {
+    const index = lockfile.entries.findIndex((item) => item.source === entry.source &&
+        item.sourceType === entry.sourceType &&
+        item.subdir === entry.subdir);
+    if (index >= 0) {
+        lockfile.entries[index] = entry;
+        return;
+    }
+    lockfile.entries.push(entry);
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { ScopePaths, SyncManifest } from "../types.js";
+export declare function readManifest(paths: ScopePaths): SyncManifest;
+export declare function writeManifest(paths: ScopePaths, manifest: SyncManifest): void;

package/dist/core/manifest.js

@@ -0,0 +1,17 @@
+import { readJsonIfExists, writeJsonAtomic } from "./fs.js";
+const EMPTY_MANIFEST = {
+    version: 1,
+    generatedFiles: [],
+};
+export function readManifest(paths) {
+    const manifest = readJsonIfExists(paths.manifestPath);
+    if (!manifest ||
+        manifest.version !== 1 ||
+        !Array.isArray(manifest.generatedFiles)) {
+        return { ...EMPTY_MANIFEST };
+    }
+    return manifest;
+}
+export function writeManifest(paths, manifest) {
+    writeJsonAtomic(paths.manifestPath, manifest);
+}

package/dist/core/mcp.d.ts

@@ -0,0 +1,4 @@
+import type { CanonicalMcpFile, Provider, ScopePaths } from "../types.js";
+export declare function readCanonicalMcp(paths: Pick<ScopePaths, "mcpPath">): CanonicalMcpFile;
+export declare function writeCanonicalMcp(paths: Pick<ScopePaths, "mcpPath">, value: CanonicalMcpFile): void;
+export declare function resolveMcpForProvider(mcp: CanonicalMcpFile, provider: Provider): Record<string, Record<string, unknown>>;

package/dist/core/mcp.js

@@ -0,0 +1,73 @@
+import { isObject, readJsonIfExists, writeJsonAtomic } from "./fs.js";
+const EMPTY_MCP = {
+    version: 1,
+    mcpServers: {},
+};
+export function readCanonicalMcp(paths) {
+    const parsed = readJsonIfExists(paths.mcpPath);
+    if (!parsed)
+        return { ...EMPTY_MCP };
+    if (isObject(parsed) && isObject(parsed.mcpServers)) {
+        return {
+            version: 1,
+            mcpServers: parsed.mcpServers,
+        };
+    }
+    return {
+        version: 1,
+        mcpServers: {},
+    };
+}
+export function writeCanonicalMcp(paths, value) {
+    writeJsonAtomic(paths.mcpPath, {
+        version: 1,
+        mcpServers: value.mcpServers,
+    });
+}
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const prev = result[key];
+        if (isObject(prev) && isObject(value)) {
+            result[key] = deepMerge(prev, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function normalizeServer(server) {
+    const normalizedBase = {};
+    const providers = isObject(server.providers)
+        ? server.providers
+        : {};
+    if (isObject(server.base)) {
+        Object.assign(normalizedBase, server.base);
+    }
+    for (const [key, value] of Object.entries(server)) {
+        if (key === "base" || key === "providers")
+            continue;
+        normalizedBase[key] = value;
+    }
+    return {
+        base: normalizedBase,
+        providers,
+    };
+}
+export function resolveMcpForProvider(mcp, provider) {
+    const resolved = {};
+    for (const [serverName, rawServer] of Object.entries(mcp.mcpServers)) {
+        const server = normalizeServer(rawServer);
+        const providerOverride = server.providers[provider];
+        if (providerOverride === false)
+            continue;
+        if (isObject(providerOverride)) {
+            resolved[serverName] = deepMerge(server.base, providerOverride);
+        }
+        else {
+            resolved[serverName] = { ...server.base };
+        }
+    }
+    return resolved;
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,9 @@
+import type { Scope, ScopePaths } from "../types.js";
+export interface ScopeResolutionOptions {
+    cwd: string;
+    global?: boolean;
+    local?: boolean;
+    interactive?: boolean;
+}
+export declare function buildScopePaths(cwd: string, scope: Scope): ScopePaths;
+export declare function resolveScope(options: ScopeResolutionOptions): Promise<ScopePaths>;

package/dist/core/scope.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { cancel, isCancel, select } from "@clack/prompts";
+import { getGlobalSettingsPath, readSettings } from "./settings.js";
+export function buildScopePaths(cwd, scope) {
+    const workspaceRoot = cwd;
+    const homeDir = os.homedir();
+    const agentsRoot = scope === "local"
+        ? path.join(workspaceRoot, ".agents")
+        : path.join(homeDir, ".agents");
+    return {
+        scope,
+        workspaceRoot,
+        homeDir,
+        agentsRoot,
+        agentsDir: path.join(agentsRoot, "agents"),
+        mcpPath: path.join(agentsRoot, "mcp.json"),
+        lockPath: path.join(agentsRoot, "agents.lock.json"),
+        settingsPath: path.join(agentsRoot, "settings.local.json"),
+        manifestPath: path.join(agentsRoot, ".sync-manifest.json"),
+    };
+}
+export async function resolveScope(options) {
+    const { cwd } = options;
+    if (options.global && options.local) {
+        throw new Error("Use either --global or --local, not both.");
+    }
+    if (options.global)
+        return buildScopePaths(cwd, "global");
+    if (options.local)
+        return buildScopePaths(cwd, "local");
+    const hasLocalAgents = fs.existsSync(path.join(cwd, ".agents"));
+    if (!hasLocalAgents) {
+        return buildScopePaths(cwd, "global");
+    }
+    const interactive = options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive) {
+        return buildScopePaths(cwd, "local");
+    }
+    const globalSettings = readSettings(getGlobalSettingsPath());
+    const defaultScope = globalSettings.lastScope === "global" ? "global" : "local";
+    const selected = await select({
+        message: "Choose scope for this command",
+        options: [
+            {
+                value: "local",
+                label: ".agents in this repository",
+                hint: defaultScope === "local" ? "default" : undefined,
+            },
+            {
+                value: "global",
+                label: "~/.agents shared config",
+                hint: defaultScope === "global" ? "default" : undefined,
+            },
+        ],
+        initialValue: defaultScope,
+    });
+    if (isCancel(selected)) {
+        cancel("Operation cancelled.");
+        process.exit(1);
+    }
+    return buildScopePaths(cwd, selected);
+}

package/dist/core/settings.d.ts

@@ -0,0 +1,6 @@
+import type { DotagentsSettings, Provider, Scope, ScopePaths } from "../types.js";
+export declare function getGlobalSettingsPath(homeDir?: string): string;
+export declare function readSettings(settingsPath: string): DotagentsSettings;
+export declare function writeSettings(settingsPath: string, settings: DotagentsSettings): void;
+export declare function updateLastScope(settingsPath: string, scope: Scope, providers?: Provider[]): void;
+export declare function settingsPathForScope(paths: ScopePaths): string;

package/dist/core/settings.js

@@ -0,0 +1,54 @@
+import os from "node:os";
+import path from "node:path";
+import { readJsonIfExists, writeJsonAtomic } from "./fs.js";
+const DEFAULT_SETTINGS = {
+    version: 1,
+    defaultProviders: [
+        "cursor",
+        "claude",
+        "codex",
+        "opencode",
+        "gemini",
+        "copilot",
+    ],
+    telemetry: {
+        enabled: true,
+    },
+};
+export function getGlobalSettingsPath(homeDir = os.homedir()) {
+    return path.join(homeDir, ".agents", "settings.local.json");
+}
+export function readSettings(settingsPath) {
+    const settings = readJsonIfExists(settingsPath);
+    if (!settings)
+        return { ...DEFAULT_SETTINGS };
+    return {
+        ...DEFAULT_SETTINGS,
+        ...settings,
+        telemetry: {
+            ...DEFAULT_SETTINGS.telemetry,
+            ...settings.telemetry,
+        },
+        defaultProviders: settings.defaultProviders && settings.defaultProviders.length > 0
+            ? settings.defaultProviders
+            : DEFAULT_SETTINGS.defaultProviders,
+    };
+}
+export function writeSettings(settingsPath, settings) {
+    writeJsonAtomic(settingsPath, settings);
+}
+export function updateLastScope(settingsPath, scope, providers) {
+    const current = readSettings(settingsPath);
+    const next = {
+        ...current,
+        version: 1,
+        lastScope: scope,
+    };
+    if (providers && providers.length > 0) {
+        next.defaultProviders = [...providers];
+    }
+    writeSettings(settingsPath, next);
+}
+export function settingsPathForScope(paths) {
+    return paths.settingsPath;
+}

package/dist/core/sources.d.ts

@@ -0,0 +1,20 @@
+export type SourceType = "local" | "github" | "git";
+export interface SourceSpec {
+    source: string;
+    type: SourceType;
+}
+export interface PreparedSource {
+    spec: SourceSpec;
+    rootPath: string;
+    importRoot: string;
+    resolvedCommit: string;
+    cleanup: () => void;
+}
+export declare function parseSourceSpec(source: string): SourceSpec;
+export declare function prepareSource(options: {
+    source: string;
+    ref?: string;
+    subdir?: string;
+}): PreparedSource;
+export declare function discoverSourceAgentsDir(importRoot: string): string;
+export declare function discoverSourceMcpPath(importRoot: string): string | null;

package/dist/core/sources.js

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function parseSourceSpec(source) {
+    const trimmed = source.trim();
+    if (!trimmed) {
+        throw new Error("Source cannot be empty.");
+    }
+    const resolvedLocalPath = path.resolve(trimmed);
+    if (isExplicitLocalPath(trimmed) || fs.existsSync(resolvedLocalPath)) {
+        return { source: resolvedLocalPath, type: "local" };
+    }
+    if (isGitUrl(trimmed)) {
+        return { source: trimmed, type: "git" };
+    }
+    if (isGitHubSlug(trimmed)) {
+        return { source: trimmed, type: "github" };
+    }
+    return { source: path.resolve(trimmed), type: "local" };
+}
+export function prepareSource(options) {
+    const spec = parseSourceSpec(options.source);
+    if (spec.type === "local") {
+        if (!fs.existsSync(spec.source)) {
+            throw new Error(`Local source not found: ${spec.source}`);
+        }
+        const importRoot = resolveImportRoot(spec.source, options.subdir);
+        const resolvedCommit = resolveLocalCommitOrHash(spec.source);
+        return {
+            spec,
+            rootPath: spec.source,
+            importRoot,
+            resolvedCommit,
+            cleanup: () => undefined,
+        };
+    }
+    const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentloom-"));
+    const cloneUrl = spec.type === "github"
+        ? `https://github.com/${spec.source}.git`
+        : spec.source;
+    runGit(["clone", cloneUrl, tmpRoot]);
+    if (options.ref) {
+        runGit(["-C", tmpRoot, "checkout", options.ref]);
+    }
+    const resolvedCommit = runGit(["-C", tmpRoot, "rev-parse", "HEAD"]).trim();
+    const importRoot = resolveImportRoot(tmpRoot, options.subdir);
+    return {
+        spec,
+        rootPath: tmpRoot,
+        importRoot,
+        resolvedCommit,
+        cleanup: () => {
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        },
+    };
+}
+export function discoverSourceAgentsDir(importRoot) {
+    const direct = path.join(importRoot, "agents");
+    if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+        return direct;
+    }
+    const nested = path.join(importRoot, ".agents", "agents");
+    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
+        return nested;
+    }
+    throw new Error(`No source agents directory found under ${importRoot} (expected agents/ or .agents/agents/).`);
+}
+export function discoverSourceMcpPath(importRoot) {
+    const nested = path.join(importRoot, ".agents", "mcp.json");
+    if (fs.existsSync(nested))
+        return nested;
+    const direct = path.join(importRoot, "mcp.json");
+    if (fs.existsSync(direct))
+        return direct;
+    return null;
+}
+function resolveImportRoot(rootPath, subdir) {
+    if (!subdir)
+        return rootPath;
+    const importRoot = path.resolve(rootPath, subdir);
+    if (!fs.existsSync(importRoot)) {
+        throw new Error(`Subdir does not exist in source: ${subdir}`);
+    }
+    return importRoot;
+}
+function isGitHubSlug(source) {
+    return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(source);
+}
+function isExplicitLocalPath(source) {
+    return (path.isAbsolute(source) ||
+        source.startsWith("./") ||
+        source.startsWith("../") ||
+        source.startsWith(".\\") ||
+        source.startsWith("..\\"));
+}
+function isGitUrl(source) {
+    return (source.startsWith("http://") ||
+        source.startsWith("https://") ||
+        source.startsWith("git@") ||
+        source.endsWith(".git"));
+}
+function resolveLocalCommitOrHash(localPath) {
+    try {
+        return runGit(["-C", localPath, "rev-parse", "HEAD"]).trim();
+    }
+    catch {
+        return `local-${hashLocalPathContents(localPath)}`;
+    }
+}
+function hashLocalPathContents(localPath) {
+    const stat = fs.statSync(localPath);
+    const hasher = createHash("sha256");
+    if (stat.isFile()) {
+        hasher.update("file");
+        hasher.update("\0");
+        hasher.update(fs.readFileSync(localPath));
+        return hasher.digest("hex");
+    }
+    const files = collectFiles(localPath);
+    if (files.length === 0) {
+        hasher.update("empty");
+    }
+    for (const filePath of files) {
+        const relativeFilePath = path
+            .relative(localPath, filePath)
+            .split(path.sep)
+            .join("/");
+        hasher.update(relativeFilePath);
+        hasher.update("\0");
+        hasher.update(fs.readFileSync(filePath));
+        hasher.update("\0");
+    }
+    return hasher.digest("hex");
+}
+function collectFiles(rootPath) {
+    const entries = [];
+    const stack = [rootPath];
+    while (stack.length > 0) {
+        const currentPath = stack.pop();
+        if (!currentPath)
+            continue;
+        const children = fs.readdirSync(currentPath, { withFileTypes: true });
+        for (const child of children) {
+            const childPath = path.join(currentPath, child.name);
+            if (child.isDirectory()) {
+                stack.push(childPath);
+            }
+            else if (child.isFile()) {
+                entries.push(childPath);
+            }
+        }
+    }
+    return entries.sort();
+}
+function runGit(args) {
+    return execFileSync("git", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf8",
+    });
+}

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

@@ -0,0 +1,8 @@
+type MaybeNotifyOptions = {
+    command: string;
+    packageName?: string;
+    currentVersion: string;
+};
+export declare function maybeNotifyVersionUpdate(options: MaybeNotifyOptions): Promise<void>;
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+export {};