loadout-ai 0.1.0

package/dist/src/core/release-claims.js

@@ -0,0 +1,175 @@
+import { existsSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const RELEASE_CLAIMS = [
+    {
+        id: "catalog-immutable-attribution",
+        status: "supported",
+        statement: "The bundled catalog records immutable Git commits and upstream credit links.",
+        boundary: "A pin proves source identity; it does not prove safety, license permission, usefulness, or future compatibility.",
+        evidence: {
+            files: [
+                "catalog/packages.json",
+                "docs/CATALOG.md",
+                "scripts/check-catalog-attribution.mjs",
+            ],
+            commands: ["npm run check:evidence"],
+            sources: [],
+        },
+    },
+    {
+        id: "stable-bounded-profile",
+        status: "bounded",
+        statement: "Stable selects 30 skill directories from four pinned SPDX-identified sources.",
+        boundary: "Recommended means the bounded Loadout policy default, not universal task superiority.",
+        evidence: {
+            files: [
+                "src/core/profiles.ts",
+                "tests/profiles.test.ts",
+                "tests/catalog-install.test.ts",
+            ],
+            commands: ["npm test -- --run"],
+            sources: [],
+        },
+    },
+    {
+        id: "transactional-managed-mutations",
+        status: "bounded",
+        statement: "Managed installation batches use snapshot-backed filesystem transactions and rollback.",
+        boundary: "This is not database-grade power-loss durability and never authorizes mutation of unmanaged content.",
+        evidence: {
+            files: [
+                "src/core/transaction.ts",
+                "src/core/snapshot.ts",
+                "tests/transaction.test.ts",
+                "tests/snapshot.test.ts",
+                "tests/native-filesystem-smoke.test.ts",
+            ],
+            commands: ["npm run test:e2e:cli"],
+            sources: [],
+        },
+    },
+    {
+        id: "daily-read-only-autopilot",
+        status: "bounded",
+        statement: "Autopilot schedules read-only discovery and update checks on supported native schedulers.",
+        boundary: "Scheduled jobs do not install, promote, execute, or update candidate content.",
+        evidence: {
+            files: ["src/core/scheduler.ts", "tests/scheduler.test.ts"],
+            commands: ["npm test -- --run tests/scheduler.test.ts"],
+            sources: [],
+        },
+    },
+    {
+        id: "benchmark-performance-evidence",
+        status: "not-established",
+        statement: "Loadout has a deterministic evaluation protocol and model-free campaign planner.",
+        boundary: "No bundled source is benchmarked until isolated real trials, signed evidence, and human promotion approval exist.",
+        evidence: {
+            files: [
+                "docs/EVALUATION_PROTOCOL_V1.md",
+                "src/core/benchmark-campaign.ts",
+                "tests/benchmark-campaign.test.ts",
+                "tests/benchmark-cli.test.ts",
+            ],
+            commands: [
+                "npm test -- --run tests/benchmark-campaign.test.ts tests/benchmark-cli.test.ts",
+            ],
+            sources: [],
+        },
+    },
+    {
+        id: "privacy-safe-sharing",
+        status: "bounded",
+        statement: "Cards, reports, comparisons, and badges expose aggregate local evidence without project content or credentials.",
+        boundary: "Users must review generated artifacts before sharing; scores do not establish universal quality.",
+        evidence: {
+            files: [
+                "src/core/share-report.ts",
+                "src/core/loadout-card.ts",
+                "src/core/loadout-badge.ts",
+                "tests/share-report.test.ts",
+                "tests/loadout-card.test.ts",
+                "tests/loadout-badge.test.ts",
+            ],
+            commands: ["npm test -- --run"],
+            sources: [],
+        },
+    },
+];
+export function releaseEvidenceRoot() {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(moduleDirectory, "..", ".."),
+        join(moduleDirectory, "..", "..", ".."),
+        process.cwd(),
+    ];
+    return (candidates.find((candidate) => existsSync(join(candidate, "README.md"))) ??
+        candidates[0]);
+}
+const FORBIDDEN_PUBLIC_CLAIMS = [
+    /\buniversally best\b/i,
+    /\bguaranteed safe\b/i,
+    /\bzero[- ]risk\b/i,
+    /\bperfect(?:ly)? compatible\b/i,
+    /\bproves? task improvement\b/i,
+    /\bevery (?:skill|repository) is (?:safe|reviewed|benchmarked)\b/i,
+];
+function portableEvidencePath(path) {
+    return (path.length > 0 &&
+        !path.startsWith("/") &&
+        !path.includes("\\") &&
+        !path.split("/").includes(".."));
+}
+export async function auditReleaseClaims(options) {
+    const claims = [...(options.claims ?? RELEASE_CLAIMS)];
+    const blockers = [];
+    const ids = new Set();
+    for (const claim of claims) {
+        if (ids.has(claim.id))
+            blockers.push(`duplicate claim id: ${claim.id}`);
+        ids.add(claim.id);
+        if (!claim.statement.trim() || !claim.boundary.trim())
+            blockers.push(`claim ${claim.id} lacks statement or boundary`);
+        if (!claim.evidence.files.length)
+            blockers.push(`claim ${claim.id} has no evidence files`);
+        for (const path of claim.evidence.files) {
+            if (!portableEvidencePath(path)) {
+                blockers.push(`claim ${claim.id} has unsafe evidence path: ${path}`);
+                continue;
+            }
+            if (options.verifyEvidenceFiles !== false)
+                try {
+                    await access(resolve(options.root, path));
+                }
+                catch {
+                    blockers.push(`claim ${claim.id} evidence is missing: ${path}`);
+                }
+        }
+    }
+    for (const pattern of FORBIDDEN_PUBLIC_CLAIMS)
+        if (pattern.test(options.readme))
+            blockers.push(`README contains forbidden release claim: ${pattern}`);
+    const catalogPhrase = `${options.catalogCount} credited public repositories`;
+    if (!options.readme.includes(catalogPhrase))
+        blockers.push(`README catalog count is stale or missing; expected '${catalogPhrase}'`);
+    if (!/does not claim there is one universally [“"]best[”"] configuration/i.test(options.readme))
+        blockers.push("README lacks the universal-best claim boundary");
+    if (!/no bundled source is called benchmarked/i.test(options.readme))
+        blockers.push("README lacks the no-bundled-benchmark-evidence boundary");
+    return {
+        schemaVersion: 1,
+        policyVersion: "p16-17-v1",
+        claims,
+        releaseBlocked: blockers.length > 0,
+        blockers,
+    };
+}
+export function formatReleaseEvidenceIndex(index) {
+    return [
+        `Release claim gate: ${index.releaseBlocked ? "BLOCKED" : "PASS"} (${index.claims.length} claim(s))`,
+        ...index.claims.map((claim) => `${claim.status === "supported" ? "✓" : claim.status === "bounded" ? "△" : "○"} ${claim.id} — ${claim.statement}\n  Boundary: ${claim.boundary}`),
+        ...index.blockers.map((blocker) => `BLOCKER: ${blocker}`),
+    ].join("\n");
+}

package/dist/src/core/remove.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { forgetInstall, installStatePath, readInstallState } from "./state.js";
+import { writeMcpConfigPlan } from "./mcp.js";
+import { runMutationTransaction } from "./transaction.js";
+export async function planRemove(packageId) {
+    const record = (await readInstallState()).installs.find((entry) => entry.packageId === packageId);
+    if (!record)
+        throw new Error(`Package is not managed by Loadout: ${packageId}`);
+    const files = await Promise.all(record.files.map(async (file) => {
+        try {
+            const digest = createHash("sha256")
+                .update(await readFile(file.path))
+                .digest("hex");
+            return {
+                path: file.path,
+                status: digest === file.sha256
+                    ? "unchanged"
+                    : "modified",
+            };
+        }
+        catch {
+            return { path: file.path, status: "missing" };
+        }
+    }));
+    const modified = files.filter((file) => file.status === "modified");
+    const state = await readInstallState();
+    const mcpServers = await Promise.all((state.mcpInstalls ?? [])
+        .filter((entry) => entry.packageId === packageId)
+        .map(async (entry) => {
+        try {
+            const config = JSON.parse(await readFile(entry.configPath, "utf8"));
+            if (!config.mcpServers || !(entry.serverName in config.mcpServers))
+                return {
+                    configPath: entry.configPath,
+                    serverName: entry.serverName,
+                    status: "missing",
+                };
+            const fingerprint = createHash("sha256")
+                .update(JSON.stringify(config.mcpServers[entry.serverName]))
+                .digest("hex");
+            return {
+                configPath: entry.configPath,
+                serverName: entry.serverName,
+                status: fingerprint === entry.fingerprint
+                    ? "unchanged"
+                    : "modified",
+            };
+        }
+        catch {
+            return {
+                configPath: entry.configPath,
+                serverName: entry.serverName,
+                status: "missing",
+            };
+        }
+    }));
+    const modifiedMcp = mcpServers.filter((entry) => entry.status === "modified");
+    const warnings = [
+        ...(modified.length
+            ? [`${modified.length} managed file(s) were modified outside Loadout.`]
+            : []),
+        ...(modifiedMcp.length
+            ? [
+                `${modifiedMcp.length} managed MCP server entry or entries were modified outside Loadout.`,
+            ]
+            : []),
+    ];
+    if (warnings.length)
+        warnings.push("Removal is blocked unless --force is used.");
+    return {
+        packageId,
+        files,
+        mcpServers,
+        blocked: modified.length > 0 || modifiedMcp.length > 0,
+        warnings,
+    };
+}
+export async function applyRemove(plan, options = {}) {
+    const applied = await runMutationTransaction(async () => {
+        const fresh = await planRemove(plan.packageId);
+        if (fresh.blocked && !options.force)
+            throw new Error(fresh.warnings.join(" "));
+        const existing = fresh.files
+            .filter((file) => file.status !== "missing")
+            .map((file) => file.path);
+        const configPaths = [
+            ...new Set(fresh.mcpServers
+                .filter((entry) => entry.status !== "missing")
+                .map((entry) => entry.configPath)),
+        ];
+        return {
+            targets: [...existing, ...configPaths, installStatePath()],
+            value: { fresh, existing, configPaths },
+        };
+    }, async ({ fresh, existing, configPaths }) => {
+        for (const file of existing)
+            await rm(file, { force: true });
+        for (const configPath of configPaths) {
+            const current = JSON.parse(await readFile(configPath, "utf8"));
+            const servers = {
+                ...(current.mcpServers ?? {}),
+            };
+            const removals = fresh.mcpServers.filter((entry) => entry.configPath === configPath && entry.status !== "missing");
+            for (const entry of removals)
+                delete servers[entry.serverName];
+            await writeMcpConfigPlan({
+                path: configPath,
+                serverName: removals[0]?.serverName ?? "removed",
+                changes: removals.map((entry) => ({
+                    serverName: entry.serverName,
+                    action: "replace",
+                    summary: `Remove MCP server '${entry.serverName}'`,
+                })),
+                warnings: [],
+                proposed: { ...current, mcpServers: servers },
+            });
+        }
+        await forgetInstall(plan.packageId);
+    });
+    return applied.snapshotId;
+}

package/dist/src/core/review-queue.js

@@ -0,0 +1,200 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+const queuePath = () => join(loadoutHome(), "review-queue.json");
+function isQueue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record.schemaVersion === 1 &&
+        typeof record.updatedAt === "string" &&
+        Array.isArray(record.items) &&
+        record.items.every((item) => item &&
+            typeof item === "object" &&
+            typeof item.repository === "string" &&
+            ["pending", "shortlisted", "ignored"].includes(item.decision)));
+}
+export async function readReviewQueue() {
+    try {
+        const value = JSON.parse(await readFile(queuePath(), "utf8"));
+        if (!isQueue(value))
+            throw new Error("review queue schema is invalid");
+        return value;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return {
+                schemaVersion: 1,
+                updatedAt: new Date(0).toISOString(),
+                items: [],
+            };
+        throw new Error(`Loadout review queue is invalid at ${queuePath()}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function fromLead(lead, now, cataloged) {
+    if (lead.source === "github-search")
+        return {
+            repository: lead.repository,
+            url: lead.url,
+            title: lead.title,
+            description: lead.description,
+            sources: [lead.source],
+            firstSeenAt: now,
+            lastSeenAt: now,
+            decision: "pending",
+            alreadyCataloged: cataloged.has(lead.repository.toLowerCase()),
+            stars: lead.stars,
+            starVelocityBaselineStars: lead.stars,
+            starVelocityBaselineAt: now,
+            forks: lead.forks,
+            repositoryCreatedAt: lead.createdAt,
+            repositoryUpdatedAt: lead.updatedAt,
+        };
+    if (lead.source === "hacker-news")
+        return {
+            repository: lead.repository,
+            url: lead.storyUrl,
+            title: lead.title,
+            description: "",
+            sources: [lead.source],
+            firstSeenAt: now,
+            lastSeenAt: now,
+            decision: "pending",
+            alreadyCataloged: cataloged.has(lead.repository.toLowerCase()),
+            communityScore: lead.score,
+            discussionUrl: lead.discussionUrl,
+        };
+    if (lead.source === "skills-sh" && lead.repository)
+        return {
+            repository: lead.repository.repository,
+            url: lead.repository.url,
+            title: lead.name,
+            description: lead.ranking.meaning,
+            sources: [lead.source],
+            firstSeenAt: now,
+            lastSeenAt: now,
+            decision: "pending",
+            alreadyCataloged: cataloged.has(lead.repository.repository.toLowerCase()),
+            installs: lead.installs,
+        };
+    if (lead.source === "official-mcp-registry" && lead.repository?.repository)
+        return {
+            repository: lead.repository.repository,
+            url: lead.repository.url,
+            title: lead.title ?? lead.name,
+            description: lead.description,
+            sources: [lead.source],
+            firstSeenAt: now,
+            lastSeenAt: now,
+            decision: "pending",
+            alreadyCataloged: cataloged.has(lead.repository.repository.toLowerCase()),
+            registryVersion: lead.version,
+            lifecycleStatus: lead.verification.lifecycleStatus,
+        };
+    return undefined;
+}
+function decisionPriority(decision) {
+    if (decision === "shortlisted")
+        return 0;
+    if (decision === "pending")
+        return 1;
+    return 2;
+}
+function compareQueueItems(left, right) {
+    return (Number(left.alreadyCataloged) - Number(right.alreadyCataloged) ||
+        decisionPriority(left.decision) - decisionPriority(right.decision) ||
+        (right.starVelocity ?? Number.NEGATIVE_INFINITY) -
+            (left.starVelocity ?? Number.NEGATIVE_INFINITY) ||
+        (right.stars ?? right.communityScore ?? 0) -
+            (left.stars ?? left.communityScore ?? 0) ||
+        left.repository.localeCompare(right.repository));
+}
+/** Merge read-only discovery leads; this never promotes or installs a candidate. */
+export async function mergeReviewQueue(leads, catalog, now = new Date()) {
+    const current = await readReviewQueue();
+    const timestamp = now.toISOString();
+    const cataloged = new Set(catalog.map((item) => item.repository.toLowerCase()));
+    const items = new Map(current.items.map((item) => [item.repository.toLowerCase(), item]));
+    for (const lead of leads) {
+        const incoming = fromLead(lead, timestamp, cataloged);
+        if (!incoming)
+            continue;
+        const key = incoming.repository.toLowerCase();
+        const existing = items.get(key);
+        let velocityEvidence = {};
+        if (existing &&
+            incoming.stars !== undefined &&
+            existing.stars !== undefined) {
+            const baselineStars = existing.starVelocityBaselineStars ?? existing.stars;
+            const baselineAt = existing.starVelocityBaselineAt ?? existing.lastSeenAt;
+            const elapsedDays = (now.getTime() - Date.parse(baselineAt)) / 86_400_000;
+            if (Number.isFinite(elapsedDays) && elapsedDays >= 1) {
+                velocityEvidence = {
+                    starVelocity: (incoming.stars - baselineStars) / elapsedDays,
+                    starVelocityWindowDays: elapsedDays,
+                    starVelocityMeasuredAt: timestamp,
+                    starVelocityBaselineStars: incoming.stars,
+                    starVelocityBaselineAt: timestamp,
+                };
+            }
+            else if (Number.isFinite(elapsedDays) && elapsedDays > 0) {
+                velocityEvidence = {
+                    starVelocity: existing.starVelocity,
+                    starVelocityWindowDays: existing.starVelocityWindowDays,
+                    starVelocityMeasuredAt: existing.starVelocityMeasuredAt,
+                    starVelocityBaselineStars: baselineStars,
+                    starVelocityBaselineAt: baselineAt,
+                };
+            }
+            else {
+                velocityEvidence = {
+                    starVelocity: existing.starVelocity,
+                    starVelocityWindowDays: existing.starVelocityWindowDays,
+                    starVelocityMeasuredAt: existing.starVelocityMeasuredAt,
+                    starVelocityBaselineStars: incoming.stars,
+                    starVelocityBaselineAt: timestamp,
+                };
+            }
+        }
+        items.set(key, existing
+            ? {
+                ...existing,
+                ...incoming,
+                sources: [...new Set([...existing.sources, ...incoming.sources])],
+                firstSeenAt: existing.firstSeenAt,
+                decision: existing.decision,
+                ...velocityEvidence,
+            }
+            : incoming);
+    }
+    const queue = {
+        schemaVersion: 1,
+        updatedAt: timestamp,
+        items: [...items.values()].sort(compareQueueItems),
+    };
+    await ensureDirectory(dirname(queuePath()));
+    await writeFileAtomically(queuePath(), `${JSON.stringify(queue, null, 2)}\n`);
+    return queue;
+}
+export async function setReviewDecision(repository, decision) {
+    const queue = await readReviewQueue();
+    const item = queue.items.find((candidate) => candidate.repository.toLowerCase() === repository.toLowerCase());
+    if (!item)
+        throw new Error(`Repository is not in the review queue: ${repository}. Run loadout discover --queue first.`);
+    item.decision = decision;
+    queue.items.sort(compareQueueItems);
+    queue.updatedAt = new Date().toISOString();
+    await writeFileAtomically(queuePath(), `${JSON.stringify(queue, null, 2)}\n`);
+    return item;
+}
+export function formatReviewQueue(queue) {
+    const visible = queue.items.filter((item) => !item.alreadyCataloged);
+    return [
+        `Review queue: ${visible.length} uncataloged candidate(s), ${queue.items.length - visible.length} already cataloged`,
+        ...visible.map((item) => `${item.decision === "shortlisted" ? "★" : item.decision === "ignored" ? "×" : "○"} ${item.repository} — ${item.stars !== undefined ? `${item.stars} stars${item.starVelocity !== undefined ? ` (${item.starVelocity >= 0 ? "+" : ""}${item.starVelocity.toFixed(1)}/day over ${item.starVelocityWindowDays?.toFixed(2) ?? "unknown"} days)` : ""}` : item.installs !== undefined ? `${item.installs} skills.sh installs` : item.registryVersion ? `MCP ${item.registryVersion} (${item.lifecycleStatus ?? "unknown"})` : `community score ${item.communityScore ?? 0}`} — ${item.sources.join("+")}`),
+    ].join("\n");
+}