agentloom 0.1.0 → 0.1.2

package/dist/core/skills.js

@@ -0,0 +1,328 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { ensureDir, slugify } from "./fs.js";
+export const ROOT_SKILL_ARTIFACT_DIRS = [
+    "references",
+    "assets",
+    "scripts",
+    "templates",
+    "examples",
+];
+export function parseSkillsDir(skillsDir) {
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillDir = path.join(skillsDir, entry.name);
+        const skillFile = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        skills.push({
+            name: entry.name,
+            sourcePath: skillDir,
+            skillPath: skillFile,
+            layout: "nested",
+        });
+    }
+    if (skills.length > 0) {
+        return skills.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    const rootSkillFile = path.join(skillsDir, "SKILL.md");
+    if (!fs.existsSync(rootSkillFile) || !fs.statSync(rootSkillFile).isFile()) {
+        return [];
+    }
+    const raw = fs.readFileSync(rootSkillFile, "utf8");
+    return [
+        {
+            name: extractSkillName(raw) || path.basename(skillsDir),
+            sourcePath: skillsDir,
+            skillPath: rootSkillFile,
+            layout: "root",
+        },
+    ];
+}
+function extractSkillName(raw) {
+    try {
+        const parsed = matter(raw);
+        if (typeof parsed.data.name !== "string")
+            return undefined;
+        const name = parsed.data.name.trim();
+        return name.length > 0 ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeSkillSelector(value) {
+    return slugify(value.trim().replace(/\/+$/, "")).toLowerCase();
+}
+export function resolveSkillSelections(skills, selectors) {
+    const normalizedSelectors = selectors
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .map(normalizeSkillSelector)
+        .filter(Boolean);
+    const selectedMap = new Map();
+    const unmatched = [];
+    for (const selector of normalizedSelectors) {
+        const matches = skills.filter((skill) => normalizeSkillSelector(skill.name) === selector);
+        if (matches.length === 0) {
+            unmatched.push(selector);
+            continue;
+        }
+        for (const match of matches) {
+            selectedMap.set(match.name, match);
+        }
+    }
+    return {
+        selected: [...selectedMap.values()],
+        unmatched,
+    };
+}
+export function copyRootSkillArtifacts(sourceRoot, targetDir) {
+    ensureDir(targetDir);
+    const sourceSkillPath = path.join(sourceRoot, "SKILL.md");
+    if (!fs.existsSync(sourceSkillPath) ||
+        !fs.statSync(sourceSkillPath).isFile()) {
+        throw new Error(`Root skill source is missing SKILL.md at ${sourceSkillPath}.`);
+    }
+    fs.copyFileSync(sourceSkillPath, path.join(targetDir, "SKILL.md"));
+    for (const artifactDirName of ROOT_SKILL_ARTIFACT_DIRS) {
+        const sourceArtifactDir = path.join(sourceRoot, artifactDirName);
+        if (!fs.existsSync(sourceArtifactDir) ||
+            !fs.statSync(sourceArtifactDir).isDirectory()) {
+            continue;
+        }
+        fs.cpSync(sourceArtifactDir, path.join(targetDir, artifactDirName), {
+            recursive: true,
+            force: true,
+        });
+    }
+}
+export function copySkillArtifacts(skill, targetDir) {
+    if (skill.layout === "nested") {
+        fs.cpSync(skill.sourcePath, targetDir, {
+            recursive: true,
+            force: true,
+        });
+        return;
+    }
+    copyRootSkillArtifacts(skill.sourcePath, targetDir);
+}
+export function skillContentMatchesTarget(skill, targetDir) {
+    if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+        return false;
+    }
+    if (skill.layout === "nested") {
+        return directoriesAreEqual(skill.sourcePath, targetDir);
+    }
+    return rootSkillArtifactsEqual(skill.sourcePath, targetDir);
+}
+export function applySkillProviderSideEffects(options) {
+    const pathsToSymlink = resolveProviderSkillsPaths(options.paths, options.providers);
+    if (pathsToSymlink.length === 0)
+        return;
+    const canonicalSkillsDir = options.paths.skillsDir;
+    if (!options.dryRun) {
+        ensureDir(canonicalSkillsDir);
+    }
+    for (const targetSkillsDir of pathsToSymlink) {
+        enforceProviderSkillsSymlink({
+            targetSkillsDir,
+            canonicalSkillsDir,
+            dryRun: Boolean(options.dryRun),
+            warn: options.warn,
+        });
+    }
+}
+function resolveProviderSkillsPaths(paths, providers) {
+    const targets = new Set();
+    const hasClaudeStyleProvider = providers.includes("claude") || providers.includes("copilot");
+    if (hasClaudeStyleProvider) {
+        targets.add(paths.scope === "local"
+            ? path.join(paths.workspaceRoot, ".claude", "skills")
+            : path.join(paths.homeDir, ".claude", "skills"));
+    }
+    if (providers.includes("cursor")) {
+        targets.add(paths.scope === "local"
+            ? path.join(paths.workspaceRoot, ".cursor", "skills")
+            : path.join(paths.homeDir, ".cursor", "skills"));
+    }
+    return [...targets];
+}
+function enforceProviderSkillsSymlink(options) {
+    const resolvedCanonical = realPathOrResolved(options.canonicalSkillsDir);
+    const targetDir = options.targetSkillsDir;
+    if (!fs.existsSync(targetDir)) {
+        if (!options.dryRun) {
+            ensureDir(path.dirname(targetDir));
+            fs.symlinkSync(options.canonicalSkillsDir, targetDir, "dir");
+        }
+        return;
+    }
+    const targetStat = fs.lstatSync(targetDir);
+    if (targetStat.isSymbolicLink()) {
+        const resolvedTarget = realPathOrResolved(targetDir);
+        if (resolvedTarget === resolvedCanonical) {
+            return;
+        }
+        throw new Error(`Expected ${targetDir} to symlink to ${options.canonicalSkillsDir}, but it points to ${resolvedTarget}.`);
+    }
+    if (!targetStat.isDirectory()) {
+        throw new Error(`Cannot manage skills side effects because ${targetDir} exists and is not a directory.`);
+    }
+    migrateProviderSkillsIntoCanonical({
+        providerSkillsDir: targetDir,
+        canonicalSkillsDir: options.canonicalSkillsDir,
+        dryRun: options.dryRun,
+        warn: options.warn,
+    });
+    if (!options.dryRun) {
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        ensureDir(path.dirname(targetDir));
+        fs.symlinkSync(options.canonicalSkillsDir, targetDir, "dir");
+    }
+}
+function migrateProviderSkillsIntoCanonical(options) {
+    const providerSkills = parseSkillsDir(options.providerSkillsDir);
+    for (const skill of providerSkills) {
+        const targetSkillDirName = skill.layout === "nested"
+            ? path.basename(skill.sourcePath)
+            : slugify(skill.name) || "skill";
+        const targetSkillDir = path.join(options.canonicalSkillsDir, targetSkillDirName);
+        if (fs.existsSync(targetSkillDir)) {
+            const sameContent = skill.layout === "nested"
+                ? directoriesAreEqual(skill.sourcePath, targetSkillDir)
+                : rootSkillArtifactsEqual(skill.sourcePath, targetSkillDir);
+            if (!sameContent) {
+                options.warn?.(`Skipped migrating provider skill "${targetSkillDirName}" because canonical skill content already exists.`);
+            }
+            continue;
+        }
+        if (options.dryRun) {
+            continue;
+        }
+        if (skill.layout === "nested") {
+            moveDirectory(skill.sourcePath, targetSkillDir);
+            continue;
+        }
+        copyRootSkillArtifacts(skill.sourcePath, targetSkillDir);
+    }
+}
+function moveDirectory(sourceDir, targetDir) {
+    ensureDir(path.dirname(targetDir));
+    try {
+        fs.renameSync(sourceDir, targetDir);
+        return;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== "EXDEV") {
+            throw error;
+        }
+    }
+    fs.cpSync(sourceDir, targetDir, { recursive: true, force: true });
+    fs.rmSync(sourceDir, { recursive: true, force: true });
+}
+function directoriesAreEqual(leftDir, rightDir) {
+    if (!fs.existsSync(leftDir) || !fs.existsSync(rightDir))
+        return false;
+    const leftEntries = collectFileEntries(leftDir);
+    const rightEntries = collectFileEntries(rightDir);
+    if (leftEntries.length !== rightEntries.length) {
+        return false;
+    }
+    for (let index = 0; index < leftEntries.length; index += 1) {
+        const left = leftEntries[index];
+        const right = rightEntries[index];
+        if (!left || !right || left.relativePath !== right.relativePath) {
+            return false;
+        }
+        if (!left.content.equals(right.content)) {
+            return false;
+        }
+    }
+    return true;
+}
+function rootSkillArtifactsEqual(sourceRoot, targetDir) {
+    const sourceArtifacts = collectRootSkillArtifacts(sourceRoot);
+    const targetArtifacts = collectRootSkillArtifacts(targetDir);
+    if (sourceArtifacts.length !== targetArtifacts.length) {
+        return false;
+    }
+    for (let index = 0; index < sourceArtifacts.length; index += 1) {
+        const left = sourceArtifacts[index];
+        const right = targetArtifacts[index];
+        if (!left || !right || left.relativePath !== right.relativePath) {
+            return false;
+        }
+        if (!left.content.equals(right.content)) {
+            return false;
+        }
+    }
+    return true;
+}
+function collectRootSkillArtifacts(rootDir) {
+    const collected = [];
+    const rootSkillPath = path.join(rootDir, "SKILL.md");
+    if (!fs.existsSync(rootSkillPath) || !fs.statSync(rootSkillPath).isFile()) {
+        return collected;
+    }
+    collected.push({
+        relativePath: "SKILL.md",
+        content: fs.readFileSync(rootSkillPath),
+    });
+    for (const artifactDirName of ROOT_SKILL_ARTIFACT_DIRS) {
+        const artifactDir = path.join(rootDir, artifactDirName);
+        if (!fs.existsSync(artifactDir) ||
+            !fs.statSync(artifactDir).isDirectory()) {
+            continue;
+        }
+        collected.push(...collectFileEntries(artifactDir, artifactDirName));
+    }
+    return collected.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function collectFileEntries(rootDir, prefix = "") {
+    const entries = [];
+    const stack = [
+        {
+            absolute: rootDir,
+            relative: prefix,
+        },
+    ];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const children = fs.readdirSync(current.absolute, { withFileTypes: true });
+        for (const child of children) {
+            const absolutePath = path.join(current.absolute, child.name);
+            const relativePath = current.relative
+                ? path.posix.join(current.relative, child.name)
+                : child.name;
+            if (child.isDirectory()) {
+                stack.push({ absolute: absolutePath, relative: relativePath });
+                continue;
+            }
+            if (!child.isFile())
+                continue;
+            entries.push({
+                relativePath,
+                content: fs.readFileSync(absolutePath),
+            });
+        }
+    }
+    return entries.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function realPathOrResolved(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch {
+        return path.resolve(filePath);
+    }
+}

package/dist/core/sources.d.ts

@@ -16,5 +16,7 @@ export declare function prepareSource(options: {
     ref?: string;
     subdir?: string;
 }): PreparedSource;
-export declare function discoverSourceAgentsDir(importRoot: string): string;
+export declare function discoverSourceAgentsDir(importRoot: string): string | null;
 export declare function discoverSourceMcpPath(importRoot: string): string | null;
+export declare function discoverSourceCommandsDir(importRoot: string): string | null;
+export declare function discoverSourceSkillsDir(importRoot: string): string | null;

package/dist/core/sources.js

@@ -65,7 +65,7 @@ export function discoverSourceAgentsDir(importRoot) {
     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/).`);
+    return null;
 }
 export function discoverSourceMcpPath(importRoot) {
     const nested = path.join(importRoot, ".agents", "mcp.json");
@@ -76,6 +76,36 @@ export function discoverSourceMcpPath(importRoot) {
         return direct;
     return null;
 }
+export function discoverSourceCommandsDir(importRoot) {
+    const nested = path.join(importRoot, ".agents", "commands");
+    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
+        return nested;
+    }
+    const direct = path.join(importRoot, "commands");
+    if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+        return direct;
+    }
+    const prompts = path.join(importRoot, "prompts");
+    if (fs.existsSync(prompts) && fs.statSync(prompts).isDirectory()) {
+        return prompts;
+    }
+    return null;
+}
+export function discoverSourceSkillsDir(importRoot) {
+    const nested = path.join(importRoot, ".agents", "skills");
+    if (fs.existsSync(nested) && fs.statSync(nested).isDirectory()) {
+        return nested;
+    }
+    const direct = path.join(importRoot, "skills");
+    if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+        return direct;
+    }
+    const rootSkill = path.join(importRoot, "SKILL.md");
+    if (fs.existsSync(rootSkill) && fs.statSync(rootSkill).isFile()) {
+        return importRoot;
+    }
+    return null;
+}
 function resolveImportRoot(rootPath, subdir) {
     if (!subdir)
         return rootPath;

package/dist/core/telemetry.d.ts

@@ -0,0 +1,26 @@
+import type { ImportSummary } from "./importer.js";
+export type TelemetrySource = {
+    owner: string;
+    repo: string;
+};
+export type TelemetryItem = {
+    entityType: "agent" | "skill" | "command" | "mcp";
+    name: string;
+    filePath: string;
+};
+export declare function parseGitHubSource(input: string): TelemetrySource | null;
+export declare function buildTelemetryItems(summary: ImportSummary): TelemetryItem[];
+export declare function buildInstallTelemetryPayload(input: {
+    source: TelemetrySource;
+    summary: ImportSummary;
+}): {
+    eventId: `${string}-${string}-${string}-${string}-${string}`;
+    occurredAt: string;
+    cliVersion: string;
+    source: TelemetrySource;
+    items: TelemetryItem[];
+};
+export declare function sendAddTelemetryEvent(input: {
+    rawSource: string;
+    summary: ImportSummary;
+}): Promise<void>;

package/dist/core/telemetry.js

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { getCliVersion } from "./version.js";
+import { parseSourceSpec } from "./sources.js";
+const DEFAULT_TELEMETRY_ENDPOINT = "https://agentloom.sh/api/v1/installs";
+const TELEMETRY_TIMEOUT_MS = 1800;
+export function parseGitHubSource(input) {
+    const spec = parseSourceSpec(input);
+    if (spec.type === "github") {
+        const [owner, repo] = spec.source.split("/");
+        if (!owner || !repo) {
+            return null;
+        }
+        return { owner, repo };
+    }
+    if (spec.type !== "git") {
+        return null;
+    }
+    const gitSource = spec.source.trim();
+    const sshMatch = gitSource.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/i);
+    if (sshMatch) {
+        return {
+            owner: sshMatch[1],
+            repo: sshMatch[2],
+        };
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(gitSource);
+    }
+    catch {
+        return null;
+    }
+    if (parsedUrl.hostname.toLowerCase() !== "github.com") {
+        return null;
+    }
+    const segments = parsedUrl.pathname.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        return null;
+    }
+    const owner = segments[0];
+    const repo = segments[1].replace(/\.git$/i, "");
+    if (!owner || !repo) {
+        return null;
+    }
+    return { owner, repo };
+}
+export function buildTelemetryItems(summary) {
+    const items = [];
+    for (const filePath of summary.importedAgents) {
+        const name = path.basename(filePath, path.extname(filePath));
+        items.push({ entityType: "agent", name, filePath });
+    }
+    for (const filePath of summary.importedCommands) {
+        const name = path.basename(filePath, path.extname(filePath));
+        items.push({ entityType: "command", name, filePath });
+    }
+    for (const serverName of summary.importedMcpServers) {
+        items.push({ entityType: "mcp", name: serverName, filePath: "mcp.json" });
+    }
+    if (summary.telemetrySkills && summary.telemetrySkills.length > 0) {
+        for (const skill of summary.telemetrySkills) {
+            items.push({
+                entityType: "skill",
+                name: skill.name,
+                filePath: skill.filePath.replace(/^\/+/, ""),
+            });
+        }
+    }
+    else {
+        for (const skillName of summary.importedSkills) {
+            items.push({
+                entityType: "skill",
+                name: skillName,
+                filePath: `skills/${skillName}/SKILL.md`,
+            });
+        }
+    }
+    return items;
+}
+export function buildInstallTelemetryPayload(input) {
+    return {
+        eventId: randomUUID(),
+        occurredAt: new Date().toISOString(),
+        cliVersion: getCliVersion(),
+        source: input.source,
+        items: buildTelemetryItems(input.summary),
+    };
+}
+export async function sendAddTelemetryEvent(input) {
+    if (process.env.AGENTLOOM_DISABLE_TELEMETRY === "1") {
+        return;
+    }
+    const source = parseGitHubSource(input.rawSource);
+    if (!source) {
+        return;
+    }
+    const payload = buildInstallTelemetryPayload({
+        source,
+        summary: input.summary,
+    });
+    if (payload.items.length === 0) {
+        return;
+    }
+    const endpoint = process.env.AGENTLOOM_TELEMETRY_ENDPOINT || DEFAULT_TELEMETRY_ENDPOINT;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+    try {
+        await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Telemetry is fail-open by design.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

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

@@ -5,4 +5,5 @@ type MaybeNotifyOptions = {
 };
 export declare function maybeNotifyVersionUpdate(options: MaybeNotifyOptions): Promise<void>;
 export declare function isNewerVersion(candidate: string, current: string): boolean;
+export declare function promptAndUpdate(current: string, latest: string): Promise<"updated" | "declined" | "failed">;
 export {};

package/dist/core/version-notifier.js

@@ -1,7 +1,9 @@
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import https from "node:https";
 import os from "node:os";
 import path from "node:path";
+import { confirm, isCancel } from "@clack/prompts";
 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;
@@ -25,7 +27,7 @@ export async function maybeNotifyVersionUpdate(options) {
     if (cache.latestVersion &&
         isNewerVersion(cache.latestVersion, options.currentVersion) &&
         cache.lastNotifiedVersion !== cache.latestVersion) {
-        printNotice(options.currentVersion, cache.latestVersion);
+        await promptAndUpdate(options.currentVersion, cache.latestVersion);
         cache.lastNotifiedVersion = cache.latestVersion;
         writeVersionCache(cache);
     }
@@ -44,7 +46,7 @@ export async function maybeNotifyVersionUpdate(options) {
     cache.latestVersion = latest;
     if (isNewerVersion(latest, options.currentVersion) &&
         cache.lastNotifiedVersion !== latest) {
-        printNotice(options.currentVersion, latest);
+        await promptAndUpdate(options.currentVersion, latest);
         cache.lastNotifiedVersion = latest;
     }
     writeVersionCache(cache);
@@ -109,8 +111,24 @@ function fetchLatestVersion(packageName) {
         req.on("error", () => resolve(null));
     });
 }
-function printNotice(current, latest) {
-    console.error(`\nUpdate available for agentloom: ${current} -> ${latest}\nRun: npm i -g agentloom\n`);
+export async function promptAndUpdate(current, latest) {
+    const accepted = await confirm({
+        message: `Update available: ${current} → ${latest}. Update now?`,
+        initialValue: true,
+    });
+    if (isCancel(accepted) || !accepted)
+        return "declined";
+    console.log(`\nUpdating agentloom to ${latest}...\n`);
+    const result = spawnSync("npm", ["i", "-g", "agentloom"], {
+        stdio: "inherit",
+    });
+    if (result.status === 0) {
+        console.log(`\nUpdated to ${latest}. Please re-run your command.\n`);
+        process.exit(0);
+        return "updated"; // unreachable, but satisfies type checker
+    }
+    console.error(`\nUpdate failed. You can update manually: npm i -g agentloom\n`);
+    return "failed";
 }
 function readVersionCache() {
     try {

package/dist/sync/index.d.ts

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