loadout-ai 0.1.0

package/dist/src/core/adapters.js

@@ -0,0 +1,254 @@
+import { dirname, join } from "node:path";
+import { planSkillInstall } from "./skills.js";
+import { formatTerminalTable } from "./terminal.js";
+/**
+ * Rules shared by the CLI, planner, and documentation. A capability only
+ * changes state when it is native or has this explicitly tested adaptation.
+ */
+export const COMPATIBILITY_RULES = {
+    native: "Loadout writes the component in a documented, agent-owned layout without translating its format.",
+    adapted: "Loadout uses a reviewed agent-specific layout or config writer and reports the adaptation; plugin runtime behavior is never inferred.",
+    unsupported: "Loadout does not guess a path, translate the component, or write files for this agent/component combination.",
+};
+const unsupported = {
+    skill: "unsupported",
+    rule: "unsupported",
+    command: "unsupported",
+    agent: "unsupported",
+    mcp: "unsupported",
+    plugin: "unsupported",
+    root: "native",
+};
+export const ADAPTER_CAPABILITIES = [
+    {
+        agent: "claude-code",
+        displayName: "Claude Code",
+        components: {
+            ...unsupported,
+            skill: "native",
+            command: "native",
+            agent: "native",
+            plugin: "adapted",
+            mcp: "adapted",
+        },
+        notes: [
+            "Plugin contents are normalized; plugin-only runtime behavior is not converted.",
+            "MCP requires an explicit JSON config path.",
+        ],
+    },
+    {
+        agent: "codex",
+        displayName: "Codex",
+        components: {
+            ...unsupported,
+            skill: "native",
+            command: "adapted",
+            agent: "native",
+            plugin: "adapted",
+            mcp: "adapted",
+        },
+        notes: [
+            "Commands use the Codex prompts layout.",
+            "Codex MCP support only appends new TOML tables; existing tables are never rewritten.",
+        ],
+    },
+    {
+        agent: "cursor",
+        displayName: "Cursor",
+        components: {
+            ...unsupported,
+            skill: "native",
+            rule: "native",
+            command: "native",
+            agent: "native",
+            plugin: "adapted",
+            mcp: "adapted",
+        },
+        notes: ["MCP requires an explicit JSON config path."],
+    },
+    {
+        agent: "gemini-cli",
+        displayName: "Gemini CLI",
+        components: {
+            ...unsupported,
+            skill: "native",
+            command: "native",
+            plugin: "adapted",
+        },
+        notes: ["Only tested filesystem-native components are enabled."],
+    },
+    {
+        agent: "opencode",
+        displayName: "OpenCode",
+        components: {
+            ...unsupported,
+            skill: "native",
+            command: "native",
+            agent: "native",
+            plugin: "adapted",
+        },
+        notes: ["Plugin contents are normalized into supported components."],
+    },
+    {
+        agent: "hermes",
+        displayName: "Hermes",
+        components: { ...unsupported, skill: "native", plugin: "adapted" },
+        notes: ["Only skill installation is currently claimed."],
+    },
+    {
+        agent: "windsurf",
+        displayName: "Windsurf",
+        components: { ...unsupported, skill: "native" },
+        notes: ["Only the documented global Agent Skills directory is managed."],
+    },
+    {
+        agent: "cline",
+        displayName: "Cline",
+        components: { ...unsupported, skill: "native" },
+        notes: ["Only the documented global Agent Skills directory is managed."],
+    },
+    {
+        agent: "github-copilot",
+        displayName: "GitHub Copilot",
+        components: { ...unsupported, skill: "native" },
+        notes: ["Only the documented personal Agent Skills directory is managed."],
+    },
+    {
+        agent: "roo-code",
+        displayName: "Roo Code",
+        components: { ...unsupported, skill: "native" },
+        notes: ["Only the documented global generic skills directory is managed."],
+    },
+    {
+        agent: "kiro-cli",
+        displayName: "Kiro CLI",
+        components: { ...unsupported, skill: "native" },
+        notes: ["Only the documented global Agent Skills directory is managed."],
+    },
+    {
+        agent: "junie",
+        displayName: "Junie",
+        components: { ...unsupported, skill: "native" },
+        notes: [
+            "Only the documented user-level Agent Skills directory is managed.",
+        ],
+    },
+];
+export function adapterCapabilities(agent) {
+    const found = ADAPTER_CAPABILITIES.find((entry) => entry.agent === agent);
+    if (!found)
+        throw new Error(`No adapter capability declaration for '${agent}'`);
+    return found;
+}
+/**
+ * Produce a read-only native-skill plan for one agent.  This is deliberately
+ * narrower than package normalization: adapters may only target a directory
+ * declared by the capability matrix, and planning never creates that
+ * directory or writes agent configuration.
+ */
+export async function planAdapterSkillInstall(source, packageId, agent, options = {}) {
+    const capability = adapterCapabilities(agent.id).components.skill;
+    if (capability !== "native") {
+        throw new Error(`${agent.displayName} does not declare native skill installation support.`);
+    }
+    const plan = await planSkillInstall(source, [agent.skillsDirectory], packageId, options);
+    return {
+        ...plan,
+        files: plan.files.map((file) => ({
+            ...file,
+            targetAgent: agent.id,
+            componentType: "skill",
+            compatibility: capability,
+        })),
+        targetAgents: [agent.id],
+    };
+}
+/**
+ * Return only the filesystem directory that this adapter actually manages for
+ * a component. Undefined is intentional for unsupported components and for
+ * explicit/config-scoped features such as MCP; callers must not guess paths.
+ */
+export function agentComponentDirectory(agent, type) {
+    const compatibility = adapterCapabilities(agent.id).components[type];
+    if (compatibility === "unsupported")
+        return undefined;
+    if (type === "skill")
+        return agent.skillsDirectory;
+    const skillBase = dirname(agent.skillsDirectory);
+    if (agent.id === "claude-code" &&
+        (type === "rule" || type === "command" || type === "agent"))
+        return join(skillBase, `${type}s`);
+    if (agent.id === "codex") {
+        const home = dirname(dirname(agent.skillsDirectory));
+        if (type === "command")
+            return join(home, ".codex", "prompts");
+        if (type === "agent")
+            return join(home, ".codex", "agents");
+    }
+    if (agent.id === "cursor" &&
+        (type === "rule" || type === "command" || type === "agent"))
+        return join(skillBase, `${type}s`);
+    if (agent.id === "gemini-cli" && type === "command")
+        return join(skillBase, "commands");
+    if (agent.id === "opencode" && (type === "command" || type === "agent"))
+        return join(skillBase, `${type}s`);
+    return undefined;
+}
+export function formatCapabilityMatrix(width) {
+    const types = [
+        "skill",
+        "rule",
+        "command",
+        "agent",
+        "mcp",
+        "plugin",
+        "root",
+    ];
+    return formatTerminalTable(["Agent", ...types], ADAPTER_CAPABILITIES.map((entry) => [
+        entry.displayName,
+        ...types.map((type) => entry.components[type]),
+    ]), width);
+}
+export function compatibilityRule(compatibility) {
+    return COMPATIBILITY_RULES[compatibility];
+}
+/**
+ * Expose unsupported combinations as an engineering backlog. This report does
+ * not infer a filesystem path or imply that popularity is adapter evidence.
+ */
+export function buildAdapterCapabilityGaps() {
+    const demand = {
+        skill: 6,
+        mcp: 5,
+        command: 4,
+        agent: 3,
+        rule: 2,
+        plugin: 1,
+    };
+    return ADAPTER_CAPABILITIES.flatMap((entry) => Object.entries(entry.components)
+        .filter((item) => item[0] !== "root" && item[1] === "unsupported")
+        .map(([component]) => ({
+        agent: entry.agent,
+        displayName: entry.displayName,
+        component,
+        priority: demand[component],
+        requirement: "Official path/config documentation, a non-mutating planner, preservation fixtures, transaction tests, and a real disposable smoke test are required before support is claimed.",
+    }))).sort((left, right) => right.priority - left.priority ||
+        left.displayName.localeCompare(right.displayName) ||
+        left.component.localeCompare(right.component));
+}
+export function formatAdapterCapabilityGaps() {
+    const gaps = buildAdapterCapabilityGaps();
+    const counts = new Map();
+    for (const gap of gaps)
+        counts.set(gap.component, (counts.get(gap.component) ?? 0) + 1);
+    return [
+        `Unsupported adapter combinations: ${gaps.length}`,
+        `By component: ${[...counts.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([component, count]) => `${component} ${count}`)
+            .join(", ")}`,
+        "",
+        ...gaps.map((gap) => `${gap.displayName} / ${gap.component} — priority ${gap.priority} — documentation and conformance evidence required`),
+    ].join("\n");
+}

package/dist/src/core/adopt.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { enrichInventoryWithProvenance } from "./provenance.js";
+import { scanInstalledSkills } from "./skill-inventory.js";
+import { installStatePath, recordInstall } from "./state.js";
+import { runMutationTransaction } from "./transaction.js";
+function slug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60) || "skill");
+}
+export async function planSkillAdoption(skill, agent, index) {
+    const inventory = enrichInventoryWithProvenance(await scanInstalledSkills([agent]), index, index ? "cache" : "none");
+    const query = skill.trim().toLowerCase();
+    const matches = inventory.skills.filter((entry) => entry.name.toLowerCase() === query ||
+        basename(entry.path).toLowerCase() === query ||
+        entry.path === skill);
+    if (!matches.length)
+        throw new Error(`No installed skill named '${skill}' was found for ${agent.displayName}`);
+    if (matches.length > 1)
+        throw new Error(`Skill '${skill}' is ambiguous for ${agent.displayName}: ${matches.map((entry) => entry.path).join(", ")}`);
+    const match = matches[0];
+    if (match.managed)
+        throw new Error(`Skill '${skill}' is already managed as ${match.packageId}`);
+    const exact = match.provenance.kind === "catalog-exact"
+        ? match.provenance.candidates[0]
+        : undefined;
+    const packageId = `adopted-${agent.id}-${slug(match.name)}`;
+    return {
+        packageId,
+        agent,
+        name: match.name,
+        path: match.path,
+        fingerprint: match.fingerprint,
+        provenance: match.provenance,
+        reviewed: Boolean(exact),
+        ...(exact
+            ? { repository: exact.repository, resolvedCommit: exact.commit }
+            : {}),
+        installPlan: {
+            packageId,
+            targetAgents: [agent.id],
+            warnings: exact
+                ? []
+                : [
+                    "The installed bytes do not exactly match the reviewed catalog; adoption records ownership but does not mark them reviewed.",
+                ],
+            files: [
+                {
+                    source: match.path,
+                    target: match.path,
+                    targetAgent: agent.id,
+                    componentType: "skill",
+                    compatibility: "native",
+                    skillName: match.name,
+                },
+            ],
+        },
+    };
+}
+export async function applySkillAdoption(plan) {
+    const applied = await runMutationTransaction(async () => {
+        const current = createHash("sha256")
+            .update(await readFile(join(plan.path, "SKILL.md")))
+            .digest("hex");
+        if (current !== plan.fingerprint)
+            throw new Error("The skill changed after preview; scan again before adopting it.");
+        return { targets: [installStatePath()], value: plan };
+    }, async (freshPlan, snapshot) => {
+        await recordInstall(freshPlan.installPlan, snapshot.id, {
+            ...(freshPlan.repository ? { repository: freshPlan.repository } : {}),
+            ...(freshPlan.resolvedCommit
+                ? { resolvedCommit: freshPlan.resolvedCommit }
+                : {}),
+            reviewed: freshPlan.reviewed,
+        });
+    });
+    return applied.snapshotId;
+}
+export function formatAdoptionPlan(plan) {
+    return [
+        `Adopt: ${plan.name} for ${plan.agent.displayName}`,
+        `Path: ${plan.path}`,
+        `Managed id: ${plan.packageId}`,
+        `Provenance: ${plan.provenance.kind} (${plan.provenance.confidence})`,
+        `Review state: ${plan.reviewed ? "reviewed exact catalog match" : "unreviewed"}`,
+        ...plan.installPlan.warnings.map((warning) => `Warning: ${warning}`),
+    ].join("\n");
+}