loadout-ai 0.1.0

package/dist/src/core/catalog.js

@@ -0,0 +1,327 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { catalogSchema, formatSchemaError } from "../shared/schemas.js";
+import { fetchGitHubMetadata } from "./github.js";
+import { loadoutHome } from "./paths.js";
+import { compareCatalogPackages, explainCatalogScore } from "./ranking.js";
+import { resolveCatalogProfile } from "./profiles.js";
+import { recordCatalogObservations } from "./observations.js";
+import { publicKeyFingerprint, verifyEnvelope, } from "./signing.js";
+const cachedCatalogPath = () => join(loadoutHome(), "catalog.json");
+export const trustedCatalogPath = () => join(loadoutHome(), "catalog-releases", "trusted.json");
+export const catalogTrustPath = () => join(loadoutHome(), "catalog-releases", "trust.json");
+export async function readCatalogTrustState() {
+    let value;
+    try {
+        value = JSON.parse(await readFile(catalogTrustPath(), "utf8"));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Catalog trust anchor is unreadable at ${catalogTrustPath()}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Catalog trust anchor is invalid");
+    const state = value;
+    if (state.schemaVersion !== 1 ||
+        typeof state.fingerprint !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/.test(state.fingerprint) ||
+        typeof state.publicKeyPem !== "string" ||
+        publicKeyFingerprint(state.publicKeyPem) !== state.fingerprint ||
+        !validDateString(state.highWaterCreatedAt) ||
+        !validDateString(state.pinnedAt) ||
+        (state.pendingCreatedAt !== undefined &&
+            !validDateString(state.pendingCreatedAt)) ||
+        (state.pendingEnvelopeSha256 !== undefined &&
+            !/^[a-f0-9]{64}$/.test(state.pendingEnvelopeSha256)) ||
+        (state.pendingCreatedAt !== undefined) !==
+            (state.pendingEnvelopeSha256 !== undefined) ||
+        (state.pendingFirstPin !== undefined &&
+            (state.pendingFirstPin !== true || state.pendingCreatedAt === undefined)))
+        throw new Error("Catalog trust anchor is invalid");
+    return state;
+}
+function validDateString(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+function bundledCatalogPath() {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(moduleDirectory, "..", "..", "catalog", "packages.json"),
+        join(moduleDirectory, "..", "..", "..", "catalog", "packages.json"),
+        join(process.cwd(), "catalog", "packages.json"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+const TIERS = new Set([
+    "official",
+    "stable",
+    "trending",
+    "community",
+]);
+const COMPONENTS = new Set([
+    "skill",
+    "rule",
+    "command",
+    "agent",
+    "mcp",
+    "plugin",
+    "root",
+]);
+const OPERATING_SYSTEMS = new Set(["windows", "macos", "linux"]);
+function invalid(record, message) {
+    throw new Error(`Catalog record ${record + 1}: ${message}`);
+}
+/**
+ * Validate catalog data before it is shown or selected. This intentionally
+ * checks provenance only when it is present, so older cached catalogs remain
+ * readable; the bundled catalog is required to carry complete provenance.
+ */
+export function validateCatalog(value, options = {}) {
+    if (!Array.isArray(value))
+        throw new Error("Catalog must be an array");
+    const schema = catalogSchema.safeParse(value);
+    if (!schema.success)
+        throw new Error(`Catalog schema is invalid: ${formatSchemaError(schema.error)}`);
+    const ids = new Set();
+    const repositories = new Set();
+    for (const [index, item] of value.entries()) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            invalid(index, "must be an object");
+        const record = item;
+        const text = (field) => {
+            const candidate = record[field];
+            if (typeof candidate !== "string" || !candidate.trim())
+                invalid(index, `'${field}' must be a non-empty string`);
+            return candidate;
+        };
+        const id = text("id");
+        if (!/^[a-z0-9]+(?:[a-z0-9-]*[a-z0-9])?$/.test(id))
+            invalid(index, "'id' must be lowercase kebab-case");
+        if (ids.has(id))
+            invalid(index, `duplicates id '${id}'`);
+        ids.add(id);
+        text("displayName");
+        text("description");
+        text("category");
+        const repository = text("repository");
+        if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository))
+            invalid(index, "'repository' must be owner/repository");
+        if (repositories.has(repository.toLowerCase()))
+            invalid(index, `duplicates repository '${repository}'`);
+        repositories.add(repository.toLowerCase());
+        if (typeof record.tier !== "string" ||
+            !TIERS.has(record.tier))
+            invalid(index, "'tier' is invalid");
+        if (record.stars !== undefined &&
+            (typeof record.stars !== "number" ||
+                !Number.isFinite(record.stars) ||
+                record.stars < 0))
+            invalid(index, "'stars' must be a non-negative number");
+        if (record.license !== undefined &&
+            (typeof record.license !== "string" || !record.license.trim()))
+            invalid(index, "'license' must be a non-empty string");
+        const components = record.components;
+        if (components !== undefined) {
+            if (!Array.isArray(components) ||
+                !components.length ||
+                components.some((component) => typeof component !== "string" || !COMPONENTS.has(component)))
+                invalid(index, "'components' must contain supported component kinds");
+            if (new Set(components).size !== components.length)
+                invalid(index, "'components' must not contain duplicates");
+        }
+        const operatingSystems = record.operatingSystems;
+        if (operatingSystems !== undefined) {
+            if (!Array.isArray(operatingSystems) ||
+                !operatingSystems.length ||
+                operatingSystems.some((system) => typeof system !== "string" || !OPERATING_SYSTEMS.has(system)))
+                invalid(index, "'operatingSystems' must contain supported operating systems");
+            if (new Set(operatingSystems).size !== operatingSystems.length)
+                invalid(index, "'operatingSystems' must not contain duplicates");
+        }
+        const source = record.source;
+        if (options.requireEvidence && source === undefined)
+            invalid(index, "is missing immutable source evidence");
+        if (source !== undefined) {
+            if (!source || typeof source !== "object" || Array.isArray(source))
+                invalid(index, "'source' must be an object");
+            const evidence = source;
+            if (evidence.type !== "github")
+                invalid(index, "'source.type' must be github");
+            if (evidence.url !== `https://github.com/${repository}`)
+                invalid(index, "'source.url' must match repository");
+            if (typeof evidence.defaultBranch !== "string" ||
+                !/^[A-Za-z0-9._/-]+$/.test(evidence.defaultBranch))
+                invalid(index, "'source.defaultBranch' is invalid");
+            if (typeof evidence.commit !== "string" ||
+                !/^[a-f0-9]{40}$/i.test(evidence.commit))
+                invalid(index, "'source.commit' must be a full Git SHA");
+            if (!Array.isArray(evidence.evidencePaths) ||
+                !evidence.evidencePaths.length ||
+                evidence.evidencePaths.some((path) => typeof path !== "string" ||
+                    !path ||
+                    path.startsWith("/") ||
+                    path.split("/").includes("..")))
+                invalid(index, "'source.evidencePaths' must be safe repository-relative paths");
+            if (typeof evidence.verifiedAt !== "string" ||
+                Number.isNaN(Date.parse(evidence.verifiedAt)))
+                invalid(index, "'source.verifiedAt' must be an ISO date");
+            if (options.requireEvidence &&
+                (components === undefined ||
+                    operatingSystems === undefined ||
+                    record.license === undefined))
+                invalid(index, "is missing component, platform, or license evidence");
+        }
+    }
+}
+export async function loadCatalog(path = bundledCatalogPath()) {
+    const raw = await readFile(path, "utf8");
+    const value = JSON.parse(raw);
+    validateCatalog(value, { requireEvidence: true });
+    return value;
+}
+/** Re-verify persisted signed catalog state on every use; public keys are not secrets. */
+export async function readTrustedCatalogState() {
+    let value;
+    try {
+        value = JSON.parse(await readFile(trustedCatalogPath(), "utf8"));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Trusted catalog state is unreadable at ${trustedCatalogPath()}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Trusted catalog state is invalid");
+    const state = value;
+    if (state.schemaVersion !== 1 ||
+        typeof state.appliedAt !== "string" ||
+        Number.isNaN(Date.parse(state.appliedAt)) ||
+        typeof state.source !== "string" ||
+        typeof state.publicKeyPem !== "string" ||
+        (state.snapshotId !== undefined &&
+            !/^\d+-[a-f0-9]{12}$/.test(state.snapshotId)) ||
+        !state.envelope ||
+        typeof state.envelope !== "object" ||
+        typeof state.envelope.createdAt !== "string" ||
+        Number.isNaN(Date.parse(state.envelope.createdAt)))
+        throw new Error("Trusted catalog state is invalid");
+    const verification = verifyEnvelope(state.envelope, state.publicKeyPem);
+    if (!verification.valid)
+        throw new Error("Trusted catalog state has an invalid Ed25519 signature");
+    const trust = await readCatalogTrustState();
+    if (!trust)
+        throw new Error("Trusted catalog state has no pinned trust anchor");
+    const anchored = verifyEnvelope(state.envelope, trust.publicKeyPem);
+    if (!anchored.valid || anchored.fingerprint !== trust.fingerprint)
+        throw new Error("Trusted catalog state does not match the pinned signing key");
+    if (Date.parse(state.envelope.createdAt) > Date.parse(trust.highWaterCreatedAt)) {
+        const coordinatedPending = state.envelope.createdAt === trust.pendingCreatedAt &&
+            createHash("sha256").update(state.envelope.signature).digest("hex") ===
+                trust.pendingEnvelopeSha256;
+        const transactionStillPending = Boolean(state.snapshotId &&
+            existsSync(join(loadoutHome(), "staging", state.snapshotId)));
+        if (!coordinatedPending || transactionStillPending)
+            throw new Error(transactionStillPending
+                ? "Trusted catalog release is still pending transaction recovery"
+                : "Trusted catalog state is not coordinated with its trust anchor");
+    }
+    validateCatalog(state.envelope.payload, { requireEvidence: true });
+    return state;
+}
+/** Load the most recently refreshed catalog, falling back to the bundled catalog offline. */
+export async function loadEffectiveCatalog(path = bundledCatalogPath()) {
+    const trusted = await readTrustedCatalogState();
+    const base = trusted?.envelope.payload ?? (await loadCatalog(path));
+    try {
+        const raw = await readFile(cachedCatalogPath(), "utf8");
+        const value = JSON.parse(raw);
+        validateCatalog(value);
+        const cachedById = new Map(value.map((pkg) => [pkg.id, pkg]));
+        // A refresh cache contains mutable GitHub fields. Never allow an older
+        // cache format to erase immutable provenance, add stale records, or hide
+        // packages introduced by a newer bundled catalog.
+        return base.map((record) => {
+            const cached = cachedById.get(record.id);
+            if (!cached)
+                return record;
+            return {
+                ...record,
+                ...(cached.stars !== undefined ? { stars: cached.stars } : {}),
+                ...(cached.description ? { description: cached.description } : {}),
+                ...(cached.lastUpdatedAt
+                    ? { lastUpdatedAt: cached.lastUpdatedAt }
+                    : {}),
+                ...(cached.pushedAt ? { pushedAt: cached.pushedAt } : {}),
+                ...(cached.topics ? { topics: cached.topics } : {}),
+                ...(cached.openIssues !== undefined
+                    ? { openIssues: cached.openIssues }
+                    : {}),
+                ...(record.archived !== undefined || cached.archived !== undefined
+                    ? { archived: Boolean(record.archived || cached.archived) }
+                    : {}),
+            };
+        });
+    }
+    catch {
+        /* no refresh has been performed yet */
+    }
+    return base;
+}
+/** Refreshes package metadata from GitHub and persists only data returned by the API. */
+export async function refreshCatalog(packages, options = {}) {
+    const refreshed = [];
+    const failures = [];
+    for (const pkg of packages) {
+        try {
+            const metadata = await fetchGitHubMetadata(pkg.repository, options);
+            refreshed.push({
+                ...pkg,
+                stars: metadata.stars,
+                description: metadata.description || pkg.description,
+                lastUpdatedAt: metadata.lastUpdatedAt,
+                pushedAt: metadata.pushedAt ?? undefined,
+                topics: metadata.topics,
+                openIssues: metadata.openIssues,
+                archived: metadata.archived,
+            });
+        }
+        catch (error) {
+            failures.push({
+                repository: pkg.repository,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            refreshed.push(pkg);
+        }
+    }
+    await mkdir(loadoutHome(), { recursive: true });
+    await writeFile(cachedCatalogPath(), `${JSON.stringify(refreshed, null, 2)}\n`, { mode: 0o600 });
+    const observations = await recordCatalogObservations(refreshed, options);
+    return {
+        catalog: refreshed,
+        failures,
+        observationFailures: observations.failures,
+    };
+}
+export function rankCatalog(packages) {
+    return [...packages].sort(compareCatalogPackages);
+}
+/** Return the evidence behind a package's ordering without pretending it is objective quality. */
+export { explainCatalogScore };
+/**
+ * Select packages for an installation loadout. This is deliberately based on
+ * catalog metadata, not star count alone: archived repositories are never
+ * selected automatically and stable mode only includes reviewed tiers.
+ */
+export function selectCatalogPackages(packages, selection) {
+    return resolveCatalogProfile(packages, selection).packages;
+}

package/dist/src/core/codex-mcp.js

@@ -0,0 +1,122 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { loadoutHome, userHome } from "./paths.js";
+import { runMutationTransaction } from "./transaction.js";
+function safeName(name) {
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(name))
+        throw new Error("MCP server name may contain only letters, numbers, ., _, and -");
+}
+function tomlString(value) {
+    // TOML basic-string escaping is compatible with JSON escaping for the values
+    // Loadout writes here, and preserves literal environment values without
+    // rendering them in a plan summary.
+    return JSON.stringify(value);
+}
+function tableHeader(name) {
+    return `[mcp_servers.${tomlString(name)}]`;
+}
+export function defaultCodexMcpConfigPath() {
+    return join(userHome(), ".codex", "config.toml");
+}
+/**
+ * Appends a new official Codex TOML MCP table without parsing or rewriting any
+ * existing TOML. Replacing an existing server is intentionally rejected until
+ * Loadout has a comment-preserving TOML editor.
+ */
+export async function planCodexMcpConfig(path, server, name = server.name) {
+    safeName(name);
+    if ((server.command ? 1 : 0) + (server.url ? 1 : 0) !== 1)
+        throw new Error("Codex MCP server requires exactly one command or URL");
+    const target = resolve(path);
+    let current = "";
+    let existed = true;
+    try {
+        current = await readFile(target, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            existed = false;
+        else
+            throw error;
+    }
+    const header = tableHeader(name);
+    if (new RegExp(`^\\s*${header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m").test(current)) {
+        throw new Error(`Codex MCP server '${name}' already exists; Loadout refuses to rewrite existing TOML tables`);
+    }
+    const lines = [header];
+    if (server.command)
+        lines.push(`command = ${tomlString(server.command)}`);
+    if (server.url)
+        lines.push(`url = ${tomlString(server.url)}`);
+    if (server.args.length)
+        lines.push(`args = [${server.args.map(tomlString).join(", ")}]`);
+    if (Object.keys(server.env).length) {
+        lines.push("", `[mcp_servers.${tomlString(name)}.env]`);
+        for (const key of Object.keys(server.env).sort()) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+                throw new Error(`Invalid environment variable name '${key}'`);
+            lines.push(`${key} = ${tomlString(server.env[key])}`);
+        }
+    }
+    const separator = current.length === 0 ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+    return {
+        path: target,
+        serverName: name,
+        summary: `Add Codex MCP server '${name}' (${server.url ? "URL" : "command"}; ${Object.keys(server.env).length} environment variable(s))`,
+        baseSha256: createHash("sha256")
+            .update(existed ? current : "loadout:codex-mcp:missing")
+            .digest("hex"),
+        proposed: `${current}${separator}${lines.join("\n")}\n`,
+    };
+}
+async function snapshotPath(id) {
+    return join(loadoutHome(), "mcp-snapshots", `${id}.json`);
+}
+export async function applyCodexMcpConfigPlan(plan) {
+    const applied = await runMutationTransaction(async () => {
+        let content = "";
+        let existed = true;
+        try {
+            content = await readFile(plan.path, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                existed = false;
+            else
+                throw error;
+        }
+        const current = createHash("sha256")
+            .update(existed ? content : "loadout:codex-mcp:missing")
+            .digest("hex");
+        if (current !== plan.baseSha256)
+            throw new Error("Codex MCP configuration changed after preview; prepare the plan again.");
+        const snapshot = {
+            id: randomUUID(),
+            path: plan.path,
+            existed,
+            ...(existed ? { content } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        const stored = await snapshotPath(snapshot.id);
+        return {
+            targets: [plan.path, stored],
+            value: { plan, snapshot, stored },
+        };
+    }, async ({ plan: freshPlan, snapshot, stored }) => {
+        await mkdir(dirname(freshPlan.path), { recursive: true });
+        const temporary = join(dirname(freshPlan.path), `.${basename(freshPlan.path)}.loadout-${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, freshPlan.proposed, { mode: 0o600 });
+            await rename(temporary, freshPlan.path);
+            await mkdir(dirname(stored), { recursive: true });
+            await writeFile(stored, JSON.stringify(snapshot), { mode: 0o600 });
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+        return snapshot;
+    });
+    return applied.result;
+}

package/dist/src/core/community.js

@@ -0,0 +1,86 @@
+const API_BASE = "https://hacker-news.firebaseio.com/v0";
+const GITHUB_REPOSITORY = /(?:https?:\/\/)?(?:www\.)?github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)/gi;
+function repositoryFromText(value) {
+    const match = GITHUB_REPOSITORY.exec(value);
+    GITHUB_REPOSITORY.lastIndex = 0;
+    if (!match)
+        return undefined;
+    const owner = match[1];
+    const repository = match[2].replace(/(?:\.git|[?#].*)$/i, "");
+    if (!owner || !repository)
+        return undefined;
+    return `${owner}/${repository}`;
+}
+function storyCandidate(story, minScore, keywords) {
+    if (story.type !== "story" ||
+        story.dead ||
+        story.deleted ||
+        !Number.isInteger(story.id) ||
+        !story.title ||
+        (story.score ?? 0) < minScore)
+        return undefined;
+    const searchable = `${story.title}\n${story.url ?? ""}\n${story.text ?? ""}`;
+    if (keywords.length &&
+        !keywords.some((keyword) => searchable.toLowerCase().includes(keyword)))
+        return undefined;
+    const repository = repositoryFromText(searchable);
+    if (!repository)
+        return undefined;
+    return {
+        source: "hacker-news",
+        repository,
+        title: story.title,
+        storyId: story.id,
+        storyUrl: story.url ?? `https://news.ycombinator.com/item?id=${story.id}`,
+        discussionUrl: `https://news.ycombinator.com/item?id=${story.id}`,
+        score: story.score ?? 0,
+        comments: story.descendants ?? 0,
+        createdAt: new Date((story.time ?? 0) * 1000).toISOString(),
+    };
+}
+/**
+ * Finds public GitHub repositories mentioned by current Hacker News stories.
+ * It calls only HN's documented Firebase API—no HTML scraping, authentication,
+ * or background polling. Results are discovery leads, never install candidates.
+ */
+export async function discoverHackerNewsRepositories(options = {}) {
+    const fetcher = options.fetcher ?? fetch;
+    const limit = Math.max(1, Math.min(options.limit ?? 50, 100));
+    const minScore = Math.max(0, options.minScore ?? 20);
+    const keywords = (options.keywords ?? [])
+        .map((keyword) => keyword.trim().toLowerCase())
+        .filter(Boolean);
+    const idsResponse = await fetcher(`${API_BASE}/topstories.json`);
+    if (!idsResponse.ok)
+        throw new Error(`Hacker News top stories request failed (${idsResponse.status})`);
+    const ids = (await idsResponse.json());
+    if (!Array.isArray(ids))
+        throw new Error("Hacker News top stories response is invalid");
+    const selectedIds = ids
+        .filter((id) => typeof id === "number" && Number.isInteger(id))
+        .slice(0, limit);
+    const stories = await Promise.all(selectedIds.map(async (id) => {
+        const response = await fetcher(`${API_BASE}/item/${id}.json`);
+        if (!response.ok)
+            return undefined;
+        return (await response.json());
+    }));
+    const deduplicated = new Map();
+    for (const story of stories) {
+        if (!story)
+            continue;
+        const candidate = storyCandidate(story, minScore, keywords);
+        if (!candidate)
+            continue;
+        const current = deduplicated.get(candidate.repository.toLowerCase());
+        if (!current || candidate.score > current.score) {
+            deduplicated.set(candidate.repository.toLowerCase(), candidate);
+        }
+    }
+    return {
+        source: "hacker-news",
+        fetchedAt: new Date().toISOString(),
+        storiesScanned: selectedIds.length,
+        candidates: [...deduplicated.values()].sort((left, right) => right.score - left.score || right.comments - left.comments),
+    };
+}