loadout-ai 0.1.0

package/dist/src/core/package.js

@@ -0,0 +1,225 @@
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { discoverSkillDirectories } from "./skills.js";
+import { discoverMcpManifests } from "./mcp.js";
+import { discoverResources } from "./components.js";
+const portableRelative = (root, path) => relative(root, path).split(/[\\/]/).join("/") || ".";
+function frontmatter(path) {
+    return readFile(join(path, "SKILL.md"), "utf8").then((content) => {
+        const name = content.match(/^name:\s*(\S.*)$/m)?.[1];
+        const description = content.match(/^description:\s*(\S.*)$/m)?.[1];
+        return {
+            name: name ?? path.split(/[\\/]/).at(-1) ?? "unnamed",
+            ...(description ? { description } : {}),
+        };
+    });
+}
+async function discoverPlugins(root) {
+    const plugins = [];
+    async function visit(directory, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".git" || entry.name === "node_modules")
+                continue;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(path, depth + 1);
+                continue;
+            }
+            // Claude and Codex use the same plugin.json convention but different
+            // manifest directories. We parse declarations only; lifecycle code and
+            // hooks are deliberately never loaded or executed.
+            const pathParts = directory.split(/[\\/]/);
+            if (!entry.isFile() ||
+                entry.name !== "plugin.json" ||
+                (!pathParts.includes(".claude-plugin") &&
+                    !pathParts.includes(".codex-plugin")))
+                continue;
+            try {
+                const value = JSON.parse(await readFile(path, "utf8"));
+                const name = typeof value.name === "string" && value.name
+                    ? value.name
+                    : (relative(root, dirname(path)).split(/[\\/]/).at(-2) ??
+                        "unnamed");
+                const components = new Set();
+                const warnings = [];
+                const names = (field) => {
+                    const item = value[field];
+                    if (typeof item === "string" && item)
+                        return [item];
+                    if (Array.isArray(item))
+                        return item.filter((entry) => typeof entry === "string" && entry.length > 0);
+                    if (item !== undefined)
+                        warnings.push(`plugin field '${field}' has an unsupported shape`);
+                    return [];
+                };
+                const commandPaths = names("commands");
+                if (commandPaths.length)
+                    components.add("command");
+                const agentPaths = names("agents");
+                if (agentPaths.length)
+                    components.add("agent");
+                const skillPaths = names("skills");
+                if (skillPaths.length)
+                    components.add("skill");
+                const hookEvents = value.hooks &&
+                    typeof value.hooks === "object" &&
+                    !Array.isArray(value.hooks)
+                    ? Object.keys(value.hooks).sort()
+                    : value.hooks === undefined
+                        ? []
+                        : (warnings.push("plugin field 'hooks' has an unsupported shape"),
+                            []);
+                if (hookEvents.length)
+                    warnings.push("hooks are inspected but never executed by Loadout");
+                const mcpServers = value.mcpServers &&
+                    typeof value.mcpServers === "object" &&
+                    !Array.isArray(value.mcpServers)
+                    ? Object.keys(value.mcpServers).sort()
+                    : value.mcpServers === undefined
+                        ? []
+                        : (warnings.push("plugin field 'mcpServers' has an unsupported shape"),
+                            []);
+                if (mcpServers.length)
+                    components.add("mcp");
+                plugins.push({
+                    type: "plugin",
+                    name,
+                    path: portableRelative(root, path),
+                    ...(typeof value.description === "string"
+                        ? { description: value.description }
+                        : {}),
+                    ...(typeof value.version === "string"
+                        ? { version: value.version }
+                        : {}),
+                    ...(typeof value.author === "string" ? { author: value.author } : {}),
+                    components: [...components].sort(),
+                    hookEvents,
+                    mcpServers,
+                    warnings,
+                });
+            }
+            catch (error) {
+                plugins.push({
+                    type: "plugin",
+                    name: "invalid",
+                    path: portableRelative(root, path),
+                    components: [],
+                    hookEvents: [],
+                    mcpServers: [],
+                    warnings: [
+                        `invalid plugin manifest: ${error instanceof Error ? error.message : String(error)}`,
+                    ],
+                });
+            }
+        }
+    }
+    await visit(root, 0);
+    return plugins;
+}
+/** Inspect a real package without running scripts or exposing environment values. */
+export async function inspectPackage(root) {
+    const resolvedRoot = resolve(root);
+    const warnings = [];
+    let skillPaths = [];
+    try {
+        skillPaths = await discoverSkillDirectories(resolvedRoot);
+    }
+    catch (error) {
+        warnings.push(error instanceof Error ? error.message : String(error));
+    }
+    const skills = [];
+    for (const path of skillPaths) {
+        try {
+            const meta = await frontmatter(path);
+            skills.push({
+                type: "skill",
+                ...meta,
+                path: portableRelative(resolvedRoot, path),
+            });
+        }
+        catch (error) {
+            warnings.push(`Could not read skill metadata at ${portableRelative(resolvedRoot, path)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const manifests = await discoverMcpManifests(resolvedRoot);
+    const resources = await discoverResources(resolvedRoot);
+    const plugins = await discoverPlugins(resolvedRoot);
+    plugins.sort((a, b) => a.path.localeCompare(b.path));
+    const mcpServers = manifests.flatMap((manifest) => manifest.servers.map((server) => ({
+        type: "mcp",
+        name: server.name,
+        transport: server.command
+            ? "command"
+            : server.url
+                ? "url"
+                : "unknown",
+        ...(server.command ? { command: server.command } : {}),
+        ...(server.url ? { url: server.url } : {}),
+        argumentCount: server.args.length,
+        environmentVariableCount: Object.keys(server.env).length,
+        path: portableRelative(resolvedRoot, manifest.path),
+        warnings: server.warnings,
+    })));
+    for (const manifest of manifests)
+        for (const warning of manifest.warnings)
+            warnings.push(`${portableRelative(resolvedRoot, manifest.path)}: ${warning}`);
+    return {
+        root: resolvedRoot,
+        skills,
+        resources,
+        plugins,
+        mcpServers,
+        counts: {
+            skills: skills.length,
+            rules: resources.filter((item) => item.type === "rule").length,
+            commands: resources.filter((item) => item.type === "command").length,
+            agents: resources.filter((item) => item.type === "agent").length,
+            plugins: plugins.length,
+            mcpServers: mcpServers.length,
+            manifests: manifests.length,
+        },
+        warnings,
+    };
+}
+export function formatPackageInspection(result) {
+    const lines = [
+        `Package: ${result.root}`,
+        `Skills: ${result.counts.skills}`,
+        `Rules: ${result.counts.rules}`,
+        `Commands: ${result.counts.commands}`,
+        `Agents: ${result.counts.agents}`,
+        `Plugins: ${result.counts.plugins}`,
+        `MCP servers: ${result.counts.mcpServers}`,
+        `Manifests: ${result.counts.manifests}`,
+    ];
+    for (const skill of result.skills)
+        lines.push(`  skill: ${skill.name}${skill.description ? ` — ${skill.description}` : ""} (${skill.path})`);
+    for (const resource of result.resources)
+        lines.push(`  ${resource.type}: ${resource.name} (${resource.path})`);
+    for (const plugin of result.plugins) {
+        const declared = plugin.components.length
+            ? `; declares ${plugin.components.join(", ")}`
+            : "";
+        lines.push(`  plugin: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ""}${plugin.description ? ` — ${plugin.description}` : ""} (${plugin.path}${declared})`);
+        if (plugin.hookEvents.length)
+            lines.push(`    hooks: ${plugin.hookEvents.join(", ")} (not executed)`);
+        if (plugin.mcpServers.length)
+            lines.push(`    mcp servers: ${plugin.mcpServers.join(", ")}`);
+        for (const warning of plugin.warnings)
+            lines.push(`    warning: ${warning}`);
+    }
+    for (const server of result.mcpServers)
+        lines.push(`  mcp: ${server.name} (${server.transport}${server.command ? ` ${server.command}` : server.url ? ` ${server.url}` : ""}; ${server.environmentVariableCount} env var(s))`);
+    for (const warning of result.warnings)
+        lines.push(`warning: ${warning}`);
+    return lines.join("\n");
+}

package/dist/src/core/paths.js

@@ -0,0 +1,214 @@
+import { access, mkdir, readdir } from "node:fs/promises";
+import { join, posix, win32 } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const AGENT_DEFINITIONS = [
+    {
+        id: "claude-code",
+        displayName: "Claude Code",
+        binary: "claude",
+        directory: [".claude", "skills"],
+    },
+    {
+        id: "codex",
+        displayName: "Codex",
+        binary: "codex",
+        directory: [".agents", "skills"],
+    },
+    {
+        id: "cursor",
+        displayName: "Cursor",
+        binary: "cursor",
+        directory: [".cursor", "skills"],
+    },
+    {
+        id: "gemini-cli",
+        displayName: "Gemini CLI",
+        binary: "gemini",
+        directory: [".gemini", "skills"],
+    },
+    {
+        id: "opencode",
+        displayName: "OpenCode",
+        binary: "opencode",
+        directory: [".config", "opencode", "skills"],
+    },
+    {
+        id: "hermes",
+        displayName: "Hermes",
+        binary: "hermes",
+        directory: [".hermes", "skills"],
+    },
+    {
+        id: "windsurf",
+        displayName: "Windsurf",
+        directory: [".codeium", "windsurf", "skills"],
+        detectionDirectories: [[".codeium", "windsurf"]],
+    },
+    {
+        id: "cline",
+        displayName: "Cline",
+        binary: "cline",
+        directory: [".cline", "skills"],
+        detectionDirectories: [[".cline"]],
+    },
+    {
+        id: "github-copilot",
+        displayName: "GitHub Copilot",
+        binary: "copilot",
+        directory: [".copilot", "skills"],
+        detectionDirectories: [[".copilot"]],
+    },
+    {
+        id: "roo-code",
+        displayName: "Roo Code",
+        directory: [".roo", "skills"],
+        detectionDirectories: [[".roo"]],
+    },
+    {
+        id: "kiro-cli",
+        displayName: "Kiro CLI",
+        directory: [".kiro", "skills"],
+        detectionDirectories: [[".kiro"]],
+    },
+    {
+        id: "junie",
+        displayName: "Junie",
+        directory: [".junie", "skills"],
+        detectionDirectories: [[".junie"]],
+    },
+];
+/** Parse one CLI agent selection consistently across every command. */
+export function parseAgentSelection(input) {
+    if (input === undefined)
+        return undefined;
+    const values = input
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (!values.length)
+        throw new Error("--agents requires at least one supported agent id");
+    const known = new Set(AGENT_DEFINITIONS.map((definition) => definition.id));
+    const unknown = [
+        ...new Set(values.filter((id) => !known.has(id))),
+    ];
+    if (unknown.length)
+        throw new Error(`Unknown agent id(s): ${unknown.join(", ")}. Supported ids: ${[...known].join(", ")}`);
+    return [...new Set(values)];
+}
+/**
+ * WSL intentionally uses its Linux/POSIX home and paths. We never translate a
+ * Windows USERPROFILE into /mnt/c because that would install into a different
+ * agent profile than the Linux executable uses.
+ */
+export function runtimeBoundary(env = process.env, platform = process.platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "linux" &&
+        (Boolean(env.WSL_DISTRO_NAME) || Boolean(env.WSL_INTEROP)))
+        return "wsl";
+    return "posix";
+}
+export function userHome(env = process.env, platform = process.platform) {
+    if (env.LOADOUT_USER_HOME)
+        return env.LOADOUT_USER_HOME;
+    // USERPROFILE is the canonical home variable on native Windows. HOME is
+    // still accepted as a fallback for Git Bash/WSL and test environments.
+    if (platform === "win32")
+        return env.USERPROFILE ?? env.HOME ?? process.cwd();
+    return env.HOME ?? env.USERPROFILE ?? process.cwd();
+}
+export function loadoutHome(env = process.env, platform = process.platform) {
+    if (env.LOADOUT_HOME)
+        return env.LOADOUT_HOME;
+    if (platform === "win32") {
+        // Application state belongs in roaming app data on Windows rather than a
+        // dot-directory in the profile. APPDATA may be absent in stripped-down
+        // shells, so fall back to a conventional profile path.
+        const appData = env.APPDATA ?? win32.join(userHome(env, platform), "AppData", "Roaming");
+        return win32.join(appData, "loadout");
+    }
+    return join(userHome(env, platform), ".loadout");
+}
+/** The lookup order accepts npm's Windows .cmd shims as first-class executables. */
+export function executableCandidates(binary, platform = process.platform) {
+    if (platform !== "win32")
+        return [binary];
+    return [binary, `${binary}.cmd`, `${binary}.exe`, `${binary}.bat`];
+}
+export function executableLookup(binary, platform = process.platform) {
+    return {
+        command: platform === "win32" ? "where" : "which",
+        candidates: executableCandidates(binary, platform),
+    };
+}
+async function hasBinary(binary, platform = process.platform) {
+    const lookup = executableLookup(binary, platform);
+    try {
+        for (const candidate of lookup.candidates) {
+            try {
+                await execFileAsync(lookup.command, [candidate]);
+                return true;
+            }
+            catch {
+                // Continue so an npm-installed command such as codex.cmd is found
+                // even when the bare command is not resolved by a stripped-down PATH.
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function agentSkillsDirectory(agent, home = userHome(), platform = process.platform) {
+    const definition = AGENT_DEFINITIONS.find((entry) => entry.id === agent);
+    if (!definition)
+        throw new Error(`Unknown agent '${agent}'`);
+    const path = platform === "win32" ? win32 : posix;
+    return path.join(home, ...definition.directory);
+}
+export async function detectAgents(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const home = userHome(env, platform);
+    return Promise.all(AGENT_DEFINITIONS.map(async (definition) => {
+        const path = platform === "win32" ? win32 : posix;
+        const skillsDirectory = agentSkillsDirectory(definition.id, home, platform);
+        const detectionDirectories = definition.detectionDirectories?.map((parts) => path.join(home, ...parts)) ?? [dirnameForDetection(skillsDirectory)];
+        return {
+            id: definition.id,
+            displayName: definition.displayName,
+            ...(definition.binary ? { binary: definition.binary } : {}),
+            installed: (definition.binary
+                ? await hasBinary(definition.binary, platform)
+                : false) ||
+                (await Promise.all(detectionDirectories.map((directory) => directoryExists(directory)))).some(Boolean),
+            skillsDirectory,
+        };
+    }));
+}
+function dirnameForDetection(skillsDirectory) {
+    return skillsDirectory.replace(/[\\/]skills$/, "");
+}
+export async function ensureDirectory(path) {
+    await mkdir(path, { recursive: true });
+}
+export async function directoryExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listDirectory(path) {
+    try {
+        return await readdir(path);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/core/portable.js

@@ -0,0 +1,130 @@
+import { lstat, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { parseLockfile, readLockfile } from "./audit.js";
+import { parseManifest, readManifest } from "./manifest.js";
+import { runMutationTransaction } from "./transaction.js";
+import { detectSecretKinds } from "./safety.js";
+export function parsePortableLoadout(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Portable Loadout must be an object");
+    const item = value;
+    if (item.schemaVersion !== 1 ||
+        item.kind !== "loadout-portable" ||
+        typeof item.exportedAt !== "string")
+        throw new Error("Portable Loadout schema is invalid");
+    const manifest = parseManifest(item.manifest);
+    const lockfile = item.lockfile === undefined ? undefined : parseLockfile(item.lockfile);
+    if (lockfile && lockfile.manifestName !== manifest.name)
+        throw new Error("Portable lockfile does not belong to its manifest");
+    const serialized = JSON.stringify({ manifest, lockfile });
+    const secrets = detectSecretKinds(serialized);
+    if (secrets.length)
+        throw new Error(`Portable Loadout appears to contain secret material: ${secrets.join(", ")}`);
+    return {
+        schemaVersion: 1,
+        kind: "loadout-portable",
+        exportedAt: item.exportedAt,
+        manifest,
+        ...(lockfile ? { lockfile } : {}),
+    };
+}
+export async function exportPortableLoadout(manifestPath, output, lockPath) {
+    const manifest = await readManifest(manifestPath);
+    const absoluteLocal = manifest.packages.find((pkg) => pkg.source.type === "local" && isAbsolute(pkg.source.path));
+    if (absoluteLocal)
+        throw new Error(`Package '${absoluteLocal.id}' uses an absolute local path and cannot be exported portably. Move it below the manifest and add it with a relative --path, or publish it to a Loadout registry first.`);
+    const lockfile = lockPath ? await readLockfile(lockPath) : undefined;
+    const bundle = parsePortableLoadout({
+        schemaVersion: 1,
+        kind: "loadout-portable",
+        exportedAt: new Date().toISOString(),
+        manifest,
+        lockfile,
+    });
+    const target = resolve(output);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(bundle, null, 2)}\n`, {
+        flag: "wx",
+        mode: 0o600,
+    });
+    return bundle;
+}
+async function readPortableFile(path) {
+    const source = resolve(path);
+    const info = await lstat(source);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error("Portable Loadout source must be a real file");
+    if (info.size > 5_000_000)
+        throw new Error("Portable Loadout exceeds the 5 MB limit");
+    return parsePortableLoadout(JSON.parse(await readFile(source, "utf8")));
+}
+export async function planPortableImport(source, manifestPath = "loadout.json", lockPath = "loadout.lock") {
+    const bundle = await readPortableFile(source);
+    const warnings = bundle.manifest.packages
+        .filter((pkg) => pkg.source.type === "local")
+        .map((pkg) => `Local package '${pkg.id}' is resolved relative to the importing machine.`);
+    return {
+        plan: {
+            source: resolve(source),
+            manifestPath: resolve(manifestPath),
+            ...(bundle.lockfile ? { lockPath: resolve(lockPath) } : {}),
+            packageCount: bundle.manifest.packages.length,
+            includesLockfile: Boolean(bundle.lockfile),
+            warnings,
+        },
+        bundle,
+    };
+}
+export async function applyPortableImport(source, manifestPath = "loadout.json", lockPath = "loadout.lock", options = {}) {
+    const applied = await runMutationTransaction(async () => {
+        const prepared = await planPortableImport(source, manifestPath, lockPath);
+        const targets = [
+            prepared.plan.manifestPath,
+            ...(prepared.plan.lockPath ? [prepared.plan.lockPath] : []),
+        ];
+        if (!options.overwrite) {
+            for (const target of targets) {
+                try {
+                    await lstat(target);
+                    throw new Error(`Refusing to overwrite existing file without --overwrite: ${target}`);
+                }
+                catch (error) {
+                    if (!(error &&
+                        typeof error === "object" &&
+                        "code" in error &&
+                        error.code === "ENOENT"))
+                        throw error;
+                }
+            }
+        }
+        return { targets, value: prepared };
+    }, async ({ plan, bundle }) => {
+        const writes = [
+            { path: plan.manifestPath, value: bundle.manifest },
+            ...(plan.lockPath && bundle.lockfile
+                ? [{ path: plan.lockPath, value: bundle.lockfile }]
+                : []),
+        ];
+        const temporary = [];
+        try {
+            for (const entry of writes) {
+                await mkdir(dirname(entry.path), { recursive: true });
+                const temp = `${entry.path}.loadout-import-${process.pid}-${Date.now()}`;
+                temporary.push(temp);
+                await writeFile(temp, `${JSON.stringify(entry.value, null, 2)}\n`, {
+                    flag: "wx",
+                });
+            }
+            for (let index = 0; index < writes.length; index += 1) {
+                if (options.overwrite)
+                    await rm(writes[index].path, { force: true });
+                await rename(temporary[index], writes[index].path);
+            }
+        }
+        finally {
+            await Promise.all(temporary.map((path) => rm(path, { force: true })));
+        }
+        return plan;
+    });
+    return { plan: applied.result, snapshotId: applied.snapshotId };
+}

package/dist/src/core/private-discovery.js

@@ -0,0 +1,45 @@
+/**
+ * Opt-in private discovery using a caller-provided GitHub token. OAuth/App
+ * brokering remains a deployment concern; this function proves the safe data
+ * boundary and never places the token in a URL, result, cache, or log.
+ */
+export async function discoverPrivateRepositories(options = {}) {
+    const token = options.token ?? process.env.GITHUB_TOKEN;
+    if (!token)
+        throw new Error("Private discovery requires an explicit GITHUB_TOKEN or token option; public discovery needs no credentials");
+    const response = await (options.fetcher ?? fetch)("https://api.github.com/user/repos?visibility=private&affiliation=owner,collaborator,organization_member&per_page=100", {
+        headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            "user-agent": "loadout-discovery",
+        },
+    });
+    if (!response.ok)
+        throw new Error(`Private GitHub discovery failed (${response.status})`);
+    const value = await response.json();
+    if (!Array.isArray(value))
+        throw new Error("Private GitHub discovery response is invalid");
+    return value.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const record = item;
+        if (record.private !== true ||
+            typeof record.id !== "number" ||
+            typeof record.full_name !== "string")
+            return [];
+        return [
+            {
+                id: record.id,
+                repository: record.full_name,
+                description: typeof record.description === "string" ? record.description : "",
+                defaultBranch: typeof record.default_branch === "string"
+                    ? record.default_branch
+                    : "main",
+                updatedAt: typeof record.updated_at === "string" ? record.updated_at : "",
+                topics: Array.isArray(record.topics)
+                    ? record.topics.filter((topic) => typeof topic === "string")
+                    : [],
+            },
+        ];
+    });
+}