agentloom 0.1.0

package/dist/core/version-notifier.js

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+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 REQUEST_TIMEOUT_MS = 1800;
+export async function maybeNotifyVersionUpdate(options) {
+    if (process.env.AGENTLOOM_DISABLE_UPDATE_NOTIFIER === "1")
+        return;
+    if (!process.stdout.isTTY || !process.stderr.isTTY)
+        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) {
+        printNotice(options.currentVersion, cache.latestVersion);
+        cache.lastNotifiedVersion = cache.latestVersion;
+        writeVersionCache(cache);
+    }
+    const now = Date.now();
+    const lastChecked = parseTime(cache.lastCheckedAt);
+    if (lastChecked && now - lastChecked < CHECK_INTERVAL_MS) {
+        return;
+    }
+    const latest = await fetchLatestVersion(packageName);
+    if (!latest) {
+        cache.lastCheckedAt = new Date(now).toISOString();
+        writeVersionCache(cache);
+        return;
+    }
+    cache.lastCheckedAt = new Date(now).toISOString();
+    cache.latestVersion = latest;
+    if (isNewerVersion(latest, options.currentVersion) &&
+        cache.lastNotifiedVersion !== latest) {
+        printNotice(options.currentVersion, latest);
+        cache.lastNotifiedVersion = latest;
+    }
+    writeVersionCache(cache);
+}
+export function isNewerVersion(candidate, current) {
+    const next = parseSemver(candidate);
+    const base = parseSemver(current);
+    if (!next || !base)
+        return false;
+    for (let index = 0; index < 3; index += 1) {
+        if (next[index] > base[index])
+            return true;
+        if (next[index] < base[index])
+            return false;
+    }
+    return false;
+}
+function parseSemver(input) {
+    const normalized = input.replace(/^v/i, "").split("-")[0];
+    const parts = normalized.split(".");
+    if (parts.length < 3)
+        return null;
+    const numbers = parts.slice(0, 3).map((part) => Number(part));
+    if (numbers.some((num) => Number.isNaN(num) || num < 0))
+        return null;
+    return [numbers[0], numbers[1], numbers[2]];
+}
+function fetchLatestVersion(packageName) {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`;
+    return new Promise((resolve) => {
+        const req = https.get(url, {
+            headers: {
+                Accept: "application/json",
+            },
+        }, (res) => {
+            if (!res.statusCode || res.statusCode < 200 || res.statusCode >= 300) {
+                resolve(null);
+                return;
+            }
+            const chunks = [];
+            res.on("data", (chunk) => {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            });
+            res.on("end", () => {
+                try {
+                    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                    if (typeof parsed.version === "string" && parsed.version.trim()) {
+                        resolve(parsed.version.trim());
+                        return;
+                    }
+                }
+                catch {
+                    // ignore parse errors
+                }
+                resolve(null);
+            });
+        });
+        req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.on("error", () => resolve(null));
+    });
+}
+function printNotice(current, latest) {
+    console.error(`\nUpdate available for agentloom: ${current} -> ${latest}\nRun: npm i -g agentloom\n`);
+}
+function readVersionCache() {
+    try {
+        if (!fs.existsSync(UPDATE_CACHE_PATH))
+            return {};
+        const parsed = JSON.parse(fs.readFileSync(UPDATE_CACHE_PATH, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeVersionCache(cache) {
+    try {
+        ensureDir(path.dirname(UPDATE_CACHE_PATH));
+        writeJsonAtomic(UPDATE_CACHE_PATH, cache);
+    }
+    catch {
+        // best-effort only
+    }
+}
+function parseTime(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed))
+        return null;
+    return parsed;
+}

package/dist/core/version.d.ts

@@ -0,0 +1 @@
+export declare function getCliVersion(): string;

package/dist/core/version.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+let cachedVersion = null;
+function readPackageVersion() {
+    try {
+        const packageUrl = new URL("../../package.json", import.meta.url);
+        const raw = fs.readFileSync(packageUrl, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim()) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0";
+}
+export function getCliVersion() {
+    if (typeof process.env.npm_package_version === "string") {
+        return process.env.npm_package_version;
+    }
+    if (cachedVersion === null) {
+        cachedVersion = readPackageVersion();
+    }
+    return cachedVersion;
+}

package/dist/sync/index.d.ts

@@ -0,0 +1,15 @@
+import type { Provider, ScopePaths } from "../types.js";
+export interface SyncOptions {
+    paths: ScopePaths;
+    providers?: Provider[];
+    yes?: boolean;
+    nonInteractive?: boolean;
+    dryRun?: boolean;
+}
+export interface SyncSummary {
+    providers: Provider[];
+    generatedFiles: string[];
+    removedFiles: string[];
+}
+export declare function syncFromCanonical(options: SyncOptions): Promise<SyncSummary>;
+export declare function formatSyncSummary(summary: SyncSummary, agentsRoot: string): string;

package/dist/sync/index.js

@@ -0,0 +1,482 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { confirm, isCancel } from "@clack/prompts";
+import TOML from "@iarna/toml";
+import YAML from "yaml";
+import { getProviderConfig, isProviderEnabled, parseAgentsDir, } from "../core/agents.js";
+import { ensureDir, isObject, readJsonIfExists, relativePosix, removeFileIfExists, slugify, toPosixPath, writeJsonAtomic, writeTextAtomic, } from "../core/fs.js";
+import { readManifest, writeManifest } from "../core/manifest.js";
+import { readCanonicalMcp, resolveMcpForProvider } from "../core/mcp.js";
+import { getGlobalSettingsPath, readSettings, updateLastScope, } from "../core/settings.js";
+export async function syncFromCanonical(options) {
+    const agents = parseAgentsDir(options.paths.agentsDir);
+    const mcp = readCanonicalMcp(options.paths);
+    const manifest = readManifest(options.paths);
+    const settings = readSettings(options.paths.settingsPath);
+    const providers = resolveProviders(options.providers, settings);
+    const nextManifest = {
+        version: 1,
+        generatedFiles: [],
+        codex: {
+            roles: [],
+            mcpServers: [],
+        },
+    };
+    const generated = new Set();
+    for (const provider of providers) {
+        syncProviderAgents({
+            provider,
+            paths: options.paths,
+            agents,
+            generated,
+            dryRun: !!options.dryRun,
+        });
+    }
+    syncProviderMcp({
+        providers,
+        paths: options.paths,
+        agents,
+        mcp,
+        generated,
+        manifest,
+        nextManifest,
+        dryRun: !!options.dryRun,
+    });
+    nextManifest.generatedFiles = [...generated].sort();
+    const removedFiles = await removeStaleGeneratedFiles({
+        oldManifest: manifest,
+        newManifest: nextManifest,
+        dryRun: !!options.dryRun,
+        yes: !!options.yes,
+        nonInteractive: !!options.nonInteractive,
+    });
+    if (!options.dryRun) {
+        writeManifest(options.paths, nextManifest);
+        updateLastScope(options.paths.settingsPath, options.paths.scope, providers);
+        updateLastScope(getGlobalSettingsPath(options.paths.homeDir), options.paths.scope);
+    }
+    return {
+        providers,
+        generatedFiles: nextManifest.generatedFiles,
+        removedFiles,
+    };
+}
+function resolveProviders(explicitProviders, settings) {
+    if (explicitProviders && explicitProviders.length > 0) {
+        return [...new Set(explicitProviders)];
+    }
+    if (settings.defaultProviders && settings.defaultProviders.length > 0) {
+        return [...new Set(settings.defaultProviders)];
+    }
+    return ["cursor", "claude", "codex", "opencode", "gemini", "copilot"];
+}
+function syncProviderAgents(options) {
+    const providerDir = getProviderAgentsDir(options.paths, options.provider);
+    for (const agent of options.agents) {
+        if (!isProviderEnabled(agent.frontmatter, options.provider))
+            continue;
+        const providerConfig = getProviderConfig(agent.frontmatter, options.provider);
+        if (providerConfig === null)
+            continue;
+        if (options.provider === "codex") {
+            continue;
+        }
+        const fileName = options.provider === "copilot"
+            ? `${slugify(agent.name) || "agent"}.agent.md`
+            : options.provider === "cursor"
+                ? `${slugify(agent.name) || "agent"}.mdc`
+                : `${slugify(agent.name) || "agent"}.md`;
+        const outputPath = path.join(providerDir, fileName);
+        const content = buildProviderAgentContent(options.provider, agent, providerConfig ?? {});
+        if (!options.dryRun) {
+            ensureDir(path.dirname(outputPath));
+            writeTextAtomic(outputPath, content);
+        }
+        options.generated.add(outputPath);
+    }
+}
+function buildProviderAgentContent(provider, agent, providerConfig) {
+    if (provider === "cursor") {
+        const frontmatter = {
+            description: agent.description,
+            alwaysApply: false,
+            ...providerConfig,
+        };
+        const fm = YAML.stringify(frontmatter).trimEnd();
+        return `---\n${fm}\n---\n\n${agent.body.trimStart()}${agent.body.endsWith("\n") ? "" : "\n"}`;
+    }
+    const frontmatter = {
+        name: agent.name,
+        description: agent.description,
+        ...providerConfig,
+    };
+    const fm = YAML.stringify(frontmatter).trimEnd();
+    return `---\n${fm}\n---\n\n${agent.body.trimStart()}${agent.body.endsWith("\n") ? "" : "\n"}`;
+}
+function getProviderAgentsDir(paths, provider) {
+    const workspaceRoot = paths.workspaceRoot;
+    const home = paths.homeDir;
+    switch (provider) {
+        case "cursor":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".cursor", "rules")
+                : path.join(home, ".cursor", "rules");
+        case "claude":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".claude", "agents")
+                : path.join(home, ".claude", "agents");
+        case "codex":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".codex", "agents")
+                : path.join(home, ".codex", "agents");
+        case "opencode":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".opencode", "agents")
+                : path.join(home, ".config", "opencode", "agents");
+        case "gemini":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".gemini", "agents")
+                : path.join(home, ".gemini", "agents");
+        case "copilot":
+            return paths.scope === "local"
+                ? path.join(workspaceRoot, ".github", "agents")
+                : path.join(home, ".vscode", "chatmodes");
+        default:
+            return path.join(workspaceRoot, ".agents", "unknown");
+    }
+}
+function syncProviderMcp(options) {
+    for (const provider of options.providers) {
+        const resolved = resolveMcpForProvider(options.mcp, provider);
+        if (provider === "cursor") {
+            const outputPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".cursor", "mcp.json")
+                : path.join(options.paths.homeDir, ".cursor", "mcp.json");
+            const payload = {
+                mcpServers: mapMcpServers(resolved, ["url", "command", "args", "env"]),
+            };
+            maybeWriteJson(outputPath, payload, options.dryRun);
+            options.generated.add(outputPath);
+            continue;
+        }
+        if (provider === "claude") {
+            const mcpPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".mcp.json")
+                : path.join(options.paths.homeDir, ".mcp.json");
+            const settingsPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".claude", "settings.json")
+                : path.join(options.paths.homeDir, ".claude.json");
+            const claudeServers = mapMcpServers(resolved, [
+                "type",
+                "url",
+                "command",
+                "args",
+                "env",
+            ]);
+            for (const [serverName, config] of Object.entries(claudeServers)) {
+                if (!("type" in config) && typeof config.url === "string") {
+                    config.type = "http";
+                }
+            }
+            maybeWriteJson(mcpPath, { mcpServers: claudeServers }, options.dryRun);
+            options.generated.add(mcpPath);
+            const settings = readJsonIfExists(settingsPath) ?? {};
+            settings.enabledMcpjsonServers = Object.keys(claudeServers).sort();
+            maybeWriteJson(settingsPath, settings, options.dryRun);
+            options.generated.add(settingsPath);
+            continue;
+        }
+        if (provider === "codex") {
+            syncCodex({
+                paths: options.paths,
+                agents: options.agents,
+                resolvedMcp: resolved,
+                generated: options.generated,
+                manifest: options.manifest,
+                nextManifest: options.nextManifest,
+                dryRun: options.dryRun,
+            });
+            continue;
+        }
+        if (provider === "opencode") {
+            const outputPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".opencode", "opencode.json")
+                : path.join(options.paths.homeDir, ".config", "opencode", "opencode.json");
+            const existing = readJsonIfExists(outputPath) ?? {};
+            const mcp = {};
+            for (const [serverName, config] of Object.entries(resolved)) {
+                if (typeof config.url === "string") {
+                    mcp[serverName] = {
+                        type: "remote",
+                        url: config.url,
+                    };
+                }
+                else {
+                    mcp[serverName] = {
+                        type: "local",
+                        command: config.command,
+                        args: Array.isArray(config.args) ? config.args : undefined,
+                    };
+                }
+                if (isObject(config.env)) {
+                    mcp[serverName].environment = config.env;
+                }
+            }
+            const payload = {
+                ...existing,
+                mcp,
+            };
+            maybeWriteJson(outputPath, payload, options.dryRun);
+            options.generated.add(outputPath);
+            continue;
+        }
+        if (provider === "gemini") {
+            const outputPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".gemini", "settings.json")
+                : path.join(options.paths.homeDir, ".gemini", "settings.json");
+            const existing = readJsonIfExists(outputPath) ?? {};
+            const experimental = isObject(existing.experimental)
+                ? { ...existing.experimental }
+                : {};
+            experimental.enableAgents = true;
+            const mcpServers = {};
+            for (const [serverName, config] of Object.entries(resolved)) {
+                const mapped = {};
+                if (typeof config.url === "string")
+                    mapped.httpUrl = config.url;
+                if (typeof config.command === "string")
+                    mapped.command = config.command;
+                if (Array.isArray(config.args))
+                    mapped.args = config.args;
+                if (isObject(config.env))
+                    mapped.env = config.env;
+                mcpServers[serverName] = mapped;
+            }
+            const payload = {
+                ...existing,
+                experimental,
+                mcpServers,
+            };
+            maybeWriteJson(outputPath, payload, options.dryRun);
+            options.generated.add(outputPath);
+            continue;
+        }
+        if (provider === "copilot") {
+            const profileMcpPath = options.paths.scope === "local"
+                ? path.join(options.paths.workspaceRoot, ".vscode", "mcp.json")
+                : path.join(options.paths.homeDir, ".vscode", "mcp.json");
+            const copilotServers = mapMcpServers(resolved, [
+                "type",
+                "url",
+                "command",
+                "args",
+                "env",
+                "tools",
+            ]);
+            for (const config of Object.values(copilotServers)) {
+                if (!Array.isArray(config.tools)) {
+                    config.tools = ["*"];
+                }
+                if (!config.type) {
+                    config.type = config.url ? "http" : "local";
+                }
+            }
+            maybeWriteJson(profileMcpPath, { mcpServers: copilotServers }, options.dryRun);
+            options.generated.add(profileMcpPath);
+            if (options.paths.scope === "global") {
+                const settingsPath = getVsCodeSettingsPath(options.paths.homeDir);
+                const settings = readJsonIfExists(settingsPath) ?? {};
+                settings["mcp.servers"] = copilotServers;
+                maybeWriteJson(settingsPath, settings, options.dryRun);
+                options.generated.add(settingsPath);
+            }
+        }
+    }
+}
+function syncCodex(options) {
+    const codexDir = options.paths.scope === "local"
+        ? path.join(options.paths.workspaceRoot, ".codex")
+        : path.join(options.paths.homeDir, ".codex");
+    const codexConfigPath = path.join(codexDir, "config.toml");
+    const codexAgentsDir = path.join(codexDir, "agents");
+    const rawConfig = fs.existsSync(codexConfigPath)
+        ? fs.readFileSync(codexConfigPath, "utf8")
+        : "";
+    const parsed = rawConfig.trim()
+        ? TOML.parse(rawConfig)
+        : {};
+    const features = isObject(parsed.features) ? { ...parsed.features } : {};
+    features.multi_agent = true;
+    parsed.features = features;
+    const agentsTable = isObject(parsed.agents) ? { ...parsed.agents } : {};
+    const previousRoles = new Set(options.manifest.codex?.roles ?? []);
+    const nextRoles = [];
+    const enabledCodexRoles = new Set(options.agents
+        .filter((agent) => isProviderEnabled(agent.frontmatter, "codex"))
+        .map((agent) => slugify(agent.name))
+        .filter((role) => role.length > 0));
+    for (const oldRole of previousRoles) {
+        if (!enabledCodexRoles.has(oldRole)) {
+            delete agentsTable[oldRole];
+        }
+    }
+    for (const agent of options.agents) {
+        if (!isProviderEnabled(agent.frontmatter, "codex"))
+            continue;
+        const codexConfig = getProviderConfig(agent.frontmatter, "codex") ?? {};
+        const role = slugify(agent.name);
+        if (!role)
+            continue;
+        const roleTomlPath = path.join(codexAgentsDir, `${role}.toml`);
+        const roleInstructionsPath = path.join(codexAgentsDir, `${role}.instructions.md`);
+        const roleToml = buildCodexRoleToml(roleInstructionsPath, codexConfig);
+        if (!options.dryRun) {
+            ensureDir(codexAgentsDir);
+            writeTextAtomic(roleInstructionsPath, `${agent.body.trimStart()}\n`);
+            writeTextAtomic(roleTomlPath, TOML.stringify(roleToml));
+        }
+        options.generated.add(roleTomlPath);
+        options.generated.add(roleInstructionsPath);
+        agentsTable[role] = {
+            description: agent.description,
+            config_file: `./agents/${role}.toml`,
+        };
+        nextRoles.push(role);
+    }
+    parsed.agents = agentsTable;
+    const previousServers = new Set(options.manifest.codex?.mcpServers ?? []);
+    const mcpServers = isObject(parsed.mcp_servers)
+        ? { ...parsed.mcp_servers }
+        : {};
+    for (const oldServer of previousServers) {
+        if (!Object.prototype.hasOwnProperty.call(options.resolvedMcp, oldServer)) {
+            delete mcpServers[oldServer];
+        }
+    }
+    for (const [serverName, config] of Object.entries(options.resolvedMcp)) {
+        const mapped = {};
+        if (typeof config.url === "string")
+            mapped.url = config.url;
+        if (typeof config.command === "string")
+            mapped.command = config.command;
+        if (Array.isArray(config.args))
+            mapped.args = config.args;
+        if (isObject(config.env))
+            mapped.env = config.env;
+        mcpServers[serverName] = mapped;
+    }
+    parsed.mcp_servers = mcpServers;
+    if (!options.dryRun) {
+        ensureDir(codexDir);
+        writeTextAtomic(codexConfigPath, TOML.stringify(parsed));
+    }
+    options.generated.add(codexConfigPath);
+    options.nextManifest.codex = {
+        roles: nextRoles.sort(),
+        mcpServers: Object.keys(options.resolvedMcp).sort(),
+    };
+}
+function buildCodexRoleToml(roleInstructionsPath, providerConfig) {
+    const roleToml = {
+        model_instructions_file: `./${path.basename(roleInstructionsPath)}`,
+    };
+    if (typeof providerConfig.model === "string") {
+        roleToml.model = providerConfig.model;
+    }
+    if (typeof providerConfig.reasoningEffort === "string") {
+        roleToml.model_reasoning_effort = providerConfig.reasoningEffort;
+    }
+    if (typeof providerConfig.approvalPolicy === "string") {
+        roleToml.approval_policy = providerConfig.approvalPolicy;
+    }
+    if (typeof providerConfig.sandboxMode === "string") {
+        roleToml.sandbox_mode = providerConfig.sandboxMode;
+    }
+    if (typeof providerConfig.webSearch === "boolean") {
+        roleToml.tools = {
+            web_search: providerConfig.webSearch,
+        };
+    }
+    return roleToml;
+}
+function mapMcpServers(servers, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    const mapped = {};
+    for (const [name, config] of Object.entries(servers)) {
+        const next = {};
+        for (const [key, value] of Object.entries(config)) {
+            if (allowed.has(key)) {
+                next[key] = value;
+            }
+        }
+        mapped[name] = next;
+    }
+    return mapped;
+}
+function maybeWriteJson(filePath, payload, dryRun) {
+    if (dryRun)
+        return;
+    ensureDir(path.dirname(filePath));
+    writeJsonAtomic(filePath, payload);
+}
+async function removeStaleGeneratedFiles(options) {
+    const oldSet = new Set(options.oldManifest.generatedFiles);
+    const newSet = new Set(options.newManifest.generatedFiles);
+    const stale = [...oldSet].filter((filePath) => !newSet.has(filePath));
+    const removed = [];
+    for (const filePath of stale) {
+        if (!fs.existsSync(filePath))
+            continue;
+        if (options.dryRun) {
+            removed.push(filePath);
+            continue;
+        }
+        if (!options.yes && !options.nonInteractive) {
+            const shouldDelete = await confirm({
+                message: `Remove stale generated file ${toPosixPath(filePath)}?`,
+                initialValue: true,
+            });
+            if (isCancel(shouldDelete)) {
+                continue;
+            }
+            if (!shouldDelete) {
+                continue;
+            }
+        }
+        removeFileIfExists(filePath);
+        removed.push(filePath);
+    }
+    return removed;
+}
+function getVsCodeSettingsPath(homeDir) {
+    switch (os.platform()) {
+        case "darwin":
+            return path.join(homeDir, "Library", "Application Support", "Code", "User", "settings.json");
+        case "win32": {
+            const appData = process.env.APPDATA;
+            if (!appData) {
+                return path.join(homeDir, "AppData", "Roaming", "Code", "User", "settings.json");
+            }
+            return path.join(appData, "Code", "User", "settings.json");
+        }
+        default:
+            return path.join(homeDir, ".config", "Code", "User", "settings.json");
+    }
+}
+export function formatSyncSummary(summary, agentsRoot) {
+    const generated = summary.generatedFiles
+        .map((filePath) => relativePosix(agentsRoot, filePath))
+        .sort();
+    const removed = summary.removedFiles
+        .map((filePath) => relativePosix(agentsRoot, filePath))
+        .sort();
+    const lines = [
+        `Providers: ${summary.providers.join(", ")}`,
+        `Generated/updated files: ${generated.length}`,
+    ];
+    if (removed.length > 0) {
+        lines.push(`Removed stale files: ${removed.length}`);
+    }
+    return lines.join("\n");
+}