loadout-ai 0.1.0

package/dist/src/core/profiles.js

@@ -0,0 +1,255 @@
+import { compareCatalogPackages } from "./ranking.js";
+/**
+ * Stable is Loadout's recommended daily driver: broad enough to improve normal
+ * engineering work immediately, but bounded at skill granularity and restricted
+ * to catalog sources with an identified SPDX license. Maximum remains the
+ * explicit broad-library mode.
+ */
+export const STABLE_SKILL_ALLOWLIST = {
+    superpowers: [
+        "dispatching-parallel-agents",
+        "executing-plans",
+        "receiving-code-review",
+        "requesting-code-review",
+        "test-driven-development",
+        "using-superpowers",
+        "verification-before-completion",
+        "writing-plans",
+    ],
+    context7: ["context7-cli", "context7-mcp", "find-docs"],
+    "addyosmani-agent-skills": [
+        "api-and-interface-design",
+        "code-review-and-quality",
+        "context-engineering",
+        "debugging-and-error-recovery",
+        "deprecation-and-migration",
+        "documentation-and-adrs",
+        "frontend-ui-engineering",
+        "git-workflow-and-versioning",
+        "observability-and-instrumentation",
+        "performance-optimization",
+        "planning-and-task-breakdown",
+        "shipping-and-launch",
+        "spec-driven-development",
+    ],
+    "wshobson-agents": [
+        "architecture-patterns",
+        "code-review-excellence",
+        "error-handling-patterns",
+        "modern-javascript-patterns",
+        "postmortem-writing",
+        "python-type-safety",
+    ],
+};
+export const STABLE_BOOST_PACKAGE_IDS = Object.freeze(Object.keys(STABLE_SKILL_ALLOWLIST));
+/**
+ * Trust is deliberately separate from popularity and publisher tier. No
+ * bundled record is labelled human-reviewed or benchmarked until that evidence
+ * is actually stored; Stable is the policy-recommended subset.
+ */
+export function catalogTrustStage(pkg) {
+    if (STABLE_BOOST_PACKAGE_IDS.includes(pkg.id) &&
+        pkg.license &&
+        pkg.license !== "NOASSERTION" &&
+        pkg.source?.commit &&
+        !pkg.archived)
+        return "recommended";
+    if (pkg.source?.commit && pkg.source.evidencePaths.length)
+        return "inspected";
+    return "discovered";
+}
+export function isStableSkillSelected(packageId, skillName, targetName) {
+    const selected = STABLE_SKILL_ALLOWLIST[packageId];
+    if (!selected)
+        return true;
+    return (selected.includes(skillName ?? targetName) || selected.includes(targetName));
+}
+/**
+ * Broad daily-driver capabilities selected at skill granularity. Collection
+ * repositories stay available in full through Maximum Library, while Power
+ * activates only skills with a clear cross-project job.
+ */
+export const POWER_SKILL_ALLOWLIST = {
+    superpowers: [
+        "brainstorming",
+        "dispatching-parallel-agents",
+        "executing-plans",
+        "finishing-a-development-branch",
+        "receiving-code-review",
+        "requesting-code-review",
+        "subagent-driven-development",
+        "systematic-debugging",
+        "test-driven-development",
+        "using-git-worktrees",
+        "using-superpowers",
+        "verification-before-completion",
+        "writing-plans",
+        "writing-skills",
+    ],
+    context7: ["context7-cli", "context7-docs", "context7-mcp", "find-docs"],
+    "anthropic-skills": [
+        "docx",
+        "frontend-design",
+        "mcp-builder",
+        "pdf",
+        "web-artifacts-builder",
+        "webapp-testing",
+    ],
+    "openai-skills": [
+        "cli-creator",
+        "figma-implement-design",
+        "gh-fix-ci",
+        "imagegen",
+        "openai-docs",
+        "playwright",
+        "screenshot",
+        "security-best-practices",
+    ],
+    "vercel-agent-skills": [
+        "deploy-to-vercel",
+        "vercel-composition-patterns",
+        "vercel-optimize",
+        "vercel-react-best-practices",
+        "web-design-guidelines",
+    ],
+    "ui-ux-pro-max": ["design-system", "slides", "ui-styling", "ui-ux-pro-max"],
+    "wshobson-agents": [
+        "accessibility-compliance",
+        "api-design-principles",
+        "architecture-patterns",
+        "code-review-excellence",
+        "debugging-strategies",
+        "e2e-testing-patterns",
+        "modern-javascript-patterns",
+        "python-testing-patterns",
+        "python-type-safety",
+        "typescript-advanced-types",
+    ],
+    "awesome-copilot": [
+        "acquire-codebase-knowledge",
+        "chrome-devtools",
+        "create-implementation-plan",
+        "github-actions-hardening",
+        "security-review",
+    ],
+};
+export function isPowerSkillSelected(packageId, skillName, targetName) {
+    const selected = POWER_SKILL_ALLOWLIST[packageId];
+    if (!selected)
+        return false;
+    return (selected.includes(skillName ?? targetName) || selected.includes(targetName));
+}
+/**
+ * These are overlap warnings, not claims that the listed repositories are
+ * technically incompatible. The catalog currently has no evidenced hard
+ * family; hard-family support exists for a future verified incompatibility.
+ */
+export const CATALOG_CONFLICT_FAMILIES = [
+    {
+        id: "agent-skill-collections",
+        label: "agent skill collections",
+        severity: "soft",
+        packageIds: ["openai-skills", "anthropic-skills", "wshobson-agents"],
+        rationale: "Each is a broad skills collection, so installing several can duplicate discovery and workflow guidance.",
+    },
+    {
+        id: "web-research-mcp",
+        label: "web research MCP servers",
+        severity: "soft",
+        packageIds: ["exa-mcp-server", "firecrawl-mcp-server"],
+        rationale: "Both expose web search/crawling capabilities; they can coexist but may overlap in cost, permissions, and tool choice.",
+    },
+];
+function eligiblePackages(packages, selection) {
+    const ranked = [...packages]
+        .filter((pkg) => !pkg.archived)
+        .sort(compareCatalogPackages);
+    if (selection.mode === "stable") {
+        const reviewed = ranked.filter((pkg) => pkg.tier === "official" || pkg.tier === "stable");
+        const curated = reviewed.filter((pkg) => STABLE_BOOST_PACKAGE_IDS.includes(pkg.id));
+        // Fixtures and downstream catalogs may not contain Loadout's bundled ids;
+        // preserve reviewed-tier behavior in that case instead of returning empty.
+        return curated.length ? curated : reviewed;
+    }
+    if (selection.mode === "power") {
+        const packageIds = new Set(Object.keys(POWER_SKILL_ALLOWLIST));
+        const selected = ranked.filter((pkg) => packageIds.has(pkg.id));
+        return selected.length
+            ? selected
+            : ranked.filter((pkg) => pkg.components?.includes("skill"));
+    }
+    if (selection.mode === "maximum")
+        return ranked;
+    const ids = selection.packageIds ?? [];
+    if (ids.length === 0)
+        throw new Error("Custom mode requires at least one package id");
+    const byId = new Map(packages.map((pkg) => [pkg.id, pkg]));
+    const unknown = ids.filter((id) => !byId.has(id));
+    if (unknown.length)
+        throw new Error(`Unknown catalog package id(s): ${unknown.join(", ")}`);
+    const archived = ids.filter((id) => byId.get(id)?.archived);
+    if (archived.length)
+        throw new Error(`Archived catalog package(s) cannot be selected: ${archived.join(", ")}`);
+    return [...new Set(ids)]
+        .map((id) => byId.get(id))
+        .sort(compareCatalogPackages);
+}
+/**
+ * Resolve catalog overlap before any repository is fetched or files are
+ * written. Stable keeps one explainable default per soft family. Maximum and
+ * Custom retain soft-overlap candidates but report the chosen default; runtime
+ * activation is never claimed because skills do not have a universal enable
+ * switch. Hard families always stop the operation for human resolution.
+ */
+export function resolveCatalogProfile(packages, selection, families = CATALOG_CONFLICT_FAMILIES) {
+    if (!["stable", "power", "maximum", "custom"].includes(selection.mode))
+        throw new Error(`Unknown install mode '${selection.mode}'`);
+    const candidates = eligiblePackages(packages, selection);
+    const selected = new Map(candidates.map((pkg) => [pkg.id, pkg]));
+    const deferred = [];
+    const conflicts = [];
+    const warnings = [];
+    for (const family of families) {
+        const members = candidates
+            .filter((pkg) => family.packageIds.includes(pkg.id))
+            .sort(compareCatalogPackages);
+        if (members.length < 2)
+            continue;
+        const names = members.map((pkg) => pkg.displayName).join(", ");
+        if (family.severity === "hard") {
+            throw new Error(`Hard conflict in ${family.label}: ${names}. Remove all but one package before continuing. ${family.rationale}`);
+        }
+        const primary = members[0];
+        const message = `${family.label}: ${primary.displayName} is the default among ${names}. ${family.rationale}`;
+        conflicts.push({
+            familyId: family.id,
+            severity: family.severity,
+            packageIds: members.map((pkg) => pkg.id),
+            defaultPackageId: primary.id,
+            message,
+        });
+        if (selection.mode === "stable") {
+            for (const secondary of members.slice(1)) {
+                selected.delete(secondary.id);
+                deferred.push(secondary);
+            }
+            warnings.push(`Stable Boost selected ${primary.displayName}; deferred ${members
+                .slice(1)
+                .map((pkg) => pkg.displayName)
+                .join(", ")} because they overlap in ${family.label}.`);
+        }
+        else if (selection.mode === "custom") {
+            warnings.push(`Custom selection retains the soft overlap in ${family.label}. Review ${names} before installation.`);
+        }
+        else {
+            warnings.push(`${selection.mode === "power" ? "Power Boost" : "Maximum Library"} retains the soft overlap in ${family.label}. ${primary.displayName} is the recommended default; review each package before installation.`);
+        }
+    }
+    return {
+        mode: selection.mode,
+        packages: [...selected.values()].sort(compareCatalogPackages),
+        deferred: deferred.sort(compareCatalogPackages),
+        conflicts,
+        warnings,
+    };
+}

package/dist/src/core/provenance.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { loadEffectiveCatalog } from "./catalog.js";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+import { discoverSkillDirectories } from "./skills.js";
+import { fetchRepositorySnapshot, } from "./source.js";
+import { writeFileAtomically } from "./atomic-file.js";
+const catalogSkillIndexPath = () => join(loadoutHome(), "provenance", "catalog-skills.json");
+function immutableCatalogDigest(catalog) {
+    const evidence = catalog
+        .filter((pkg) => pkg.source?.commit && pkg.components?.includes("skill"))
+        .map((pkg) => `${pkg.id}\0${pkg.source.commit}`)
+        .sort()
+        .join("\n");
+    return createHash("sha256").update(evidence).digest("hex");
+}
+function cleanFrontmatterValue(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'")))
+        return trimmed.slice(1, -1);
+    return trimmed;
+}
+function portablePath(root, path) {
+    return relative(resolve(root), resolve(path)).split(sep).join("/") || ".";
+}
+async function parallelMap(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    async function run() {
+        while (cursor < values.length) {
+            const index = cursor++;
+            results[index] = await worker(values[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(Math.max(1, concurrency), values.length) }, run));
+    return results;
+}
+function isCatalogSkillIndex(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    const recordsValid = Array.isArray(item.records) &&
+        item.records.every((record) => {
+            if (!record || typeof record !== "object" || Array.isArray(record))
+                return false;
+            const candidate = record;
+            return (typeof candidate.packageId === "string" &&
+                typeof candidate.packageDisplayName === "string" &&
+                typeof candidate.repository === "string" &&
+                typeof candidate.commit === "string" &&
+                ["official", "stable", "trending", "community"].includes(String(candidate.tier)) &&
+                typeof candidate.category === "string" &&
+                (candidate.license === undefined ||
+                    typeof candidate.license === "string") &&
+                typeof candidate.skillName === "string" &&
+                (candidate.description === undefined ||
+                    typeof candidate.description === "string") &&
+                typeof candidate.skillPath === "string" &&
+                typeof candidate.fingerprint === "string");
+        });
+    const failuresValid = Array.isArray(item.failures) &&
+        item.failures.every((failure) => {
+            if (!failure || typeof failure !== "object" || Array.isArray(failure))
+                return false;
+            const candidate = failure;
+            return (typeof candidate.packageId === "string" &&
+                typeof candidate.repository === "string" &&
+                typeof candidate.error === "string");
+        });
+    return (item.schemaVersion === 1 &&
+        typeof item.catalogDigest === "string" &&
+        typeof item.generatedAt === "string" &&
+        recordsValid &&
+        failuresValid);
+}
+export async function readCatalogSkillIndex() {
+    try {
+        const value = JSON.parse(await readFile(catalogSkillIndexPath(), "utf8"));
+        return isCatalogSkillIndex(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function buildCatalogSkillIndex(options = {}) {
+    const catalog = options.catalog ?? (await loadEffectiveCatalog());
+    const packages = catalog.filter((pkg) => pkg.source?.commit && pkg.components?.includes("skill"));
+    const fetchSnapshot = options.fetchSnapshot ?? fetchRepositorySnapshot;
+    let completed = 0;
+    const results = await parallelMap(packages, options.concurrency ?? 4, async (pkg) => {
+        options.onProgress?.({
+            packageId: pkg.id,
+            completed,
+            total: packages.length,
+            status: "fetching",
+            message: `Indexing reviewed ${pkg.displayName} skills`,
+        });
+        try {
+            const snapshot = await fetchSnapshot(pkg.repository, {
+                ref: pkg.source.commit,
+            });
+            if (snapshot.commit.toLowerCase() !== pkg.source.commit.toLowerCase())
+                throw new Error(`resolved ${snapshot.commit}, expected ${pkg.source.commit}`);
+            const directories = await discoverSkillDirectories(snapshot.path);
+            const records = await Promise.all(directories.map(async (directory) => {
+                const content = await readFile(join(directory, "SKILL.md"), "utf8");
+                const description = cleanFrontmatterValue(content.match(/^description:\s*(.+)$/m)?.[1]);
+                return {
+                    packageId: pkg.id,
+                    packageDisplayName: pkg.displayName,
+                    repository: pkg.repository,
+                    commit: pkg.source.commit,
+                    tier: pkg.tier,
+                    category: pkg.category,
+                    ...(pkg.license ? { license: pkg.license } : {}),
+                    skillName: cleanFrontmatterValue(content.match(/^name:\s*(.+)$/m)?.[1]) ??
+                        directory.split(sep).at(-1) ??
+                        "unnamed",
+                    ...(description ? { description } : {}),
+                    skillPath: portablePath(snapshot.path, directory),
+                    fingerprint: createHash("sha256").update(content).digest("hex"),
+                };
+            }));
+            completed += 1;
+            options.onProgress?.({
+                packageId: pkg.id,
+                completed,
+                total: packages.length,
+                status: "ready",
+                message: `${pkg.displayName}: ${records.length} reviewed skill(s) indexed`,
+            });
+            return { records };
+        }
+        catch (error) {
+            completed += 1;
+            const failure = {
+                packageId: pkg.id,
+                repository: pkg.repository,
+                error: error instanceof Error ? error.message : String(error),
+            };
+            options.onProgress?.({
+                packageId: pkg.id,
+                completed,
+                total: packages.length,
+                status: "failed",
+                message: `${pkg.displayName}: ${failure.error}`,
+            });
+            return { records: [], failure };
+        }
+    });
+    const index = {
+        schemaVersion: 1,
+        catalogDigest: immutableCatalogDigest(catalog),
+        generatedAt: (options.now ?? new Date()).toISOString(),
+        records: results
+            .flatMap((result) => result.records)
+            .sort((left, right) => left.packageId.localeCompare(right.packageId) ||
+            left.skillPath.localeCompare(right.skillPath)),
+        failures: results
+            .flatMap((result) => (result.failure ? [result.failure] : []))
+            .sort((left, right) => left.packageId.localeCompare(right.packageId)),
+    };
+    await ensureDirectory(dirname(catalogSkillIndexPath()));
+    await writeFileAtomically(catalogSkillIndexPath(), `${JSON.stringify(index, null, 2)}\n`);
+    return index;
+}
+export async function resolveCatalogSkillIndex(options = {}) {
+    const catalog = options.build?.catalog ?? (await loadEffectiveCatalog());
+    const digest = immutableCatalogDigest(catalog);
+    const cached = await readCatalogSkillIndex();
+    const stale = Boolean(cached && cached.catalogDigest !== digest);
+    if (!options.refresh && cached && !stale)
+        return { index: cached, source: "cache" };
+    if (options.offline)
+        return cached
+            ? { index: cached, source: stale ? "stale-cache" : "cache" }
+            : { source: "none" };
+    return {
+        index: await buildCatalogSkillIndex({
+            ...options.build,
+            catalog,
+        }),
+        source: "refreshed",
+    };
+}
+function candidatesFor(skill, index) {
+    const records = index?.records ?? [];
+    if (skill.managed) {
+        const candidates = records.filter((record) => record.packageId === skill.packageId);
+        return {
+            kind: "loadout-managed",
+            confidence: "high",
+            evidence: [
+                `Loadout state owns this path as package '${skill.packageId}'.`,
+                ...(candidates.length
+                    ? ["The managed package also exists in the reviewed catalog index."]
+                    : []),
+            ],
+            candidates,
+        };
+    }
+    const exact = records.filter((record) => record.fingerprint === skill.fingerprint);
+    if (exact.length)
+        return {
+            kind: "catalog-exact",
+            confidence: "exact",
+            evidence: [
+                `SKILL.md SHA-256 exactly matches ${exact.length} reviewed catalog record(s).`,
+            ],
+            candidates: exact,
+        };
+    const hints = new Set((skill.sourceHints ?? []).map((item) => item.toLowerCase()));
+    const embedded = records.filter((record) => hints.has(record.repository.toLowerCase()));
+    if (embedded.length)
+        return {
+            kind: "embedded-source",
+            confidence: "medium",
+            evidence: [
+                "The skill text names a reviewed repository, but its instruction fingerprint differs from the reviewed commit.",
+            ],
+            candidates: embedded,
+        };
+    const name = skill.name.trim().toLowerCase();
+    const named = records.filter((record) => record.skillName.trim().toLowerCase() === name);
+    if (named.length)
+        return {
+            kind: "catalog-name-candidate",
+            confidence: "low",
+            evidence: [
+                "Only the normalized skill name matches; names alone do not establish provenance or equivalence.",
+            ],
+            candidates: named,
+        };
+    return {
+        kind: "unknown",
+        confidence: "unknown",
+        evidence: [
+            index
+                ? "No managed record, exact fingerprint, embedded reviewed source, or reviewed name match was found."
+                : "No catalog skill index is available; run with provenance refresh for reviewed matching.",
+        ],
+        candidates: [],
+    };
+}
+export function enrichInventoryWithProvenance(report, index, source = "none") {
+    const skills = report.skills.map((skill) => ({
+        ...skill,
+        provenance: candidatesFor(skill, index),
+    }));
+    const count = (kind) => skills.filter((skill) => skill.provenance.kind === kind).length;
+    return {
+        ...report,
+        skills,
+        provenance: {
+            indexSource: source,
+            ...(index ? { catalogDigest: index.catalogDigest } : {}),
+            ...(index ? { indexGeneratedAt: index.generatedAt } : {}),
+            indexedSkills: index?.records.length ?? 0,
+            exact: count("catalog-exact"),
+            managed: count("loadout-managed"),
+            embedded: count("embedded-source"),
+            nameCandidates: count("catalog-name-candidate"),
+            unknown: count("unknown"),
+            failures: index?.failures ?? [],
+        },
+    };
+}
+export function formatProvenanceSummary(report) {
+    const value = report.provenance;
+    return [
+        `Provenance: ${value.exact} exact catalog match(es), ${value.managed} Loadout-managed, ${value.embedded} embedded-source candidate(s), ${value.nameCandidates} name-only candidate(s), ${value.unknown} unknown`,
+        `Catalog skill index: ${value.indexSource}; ${value.indexedSkills} reviewed skill(s)${value.failures.length ? `; ${value.failures.length} repository failure(s)` : ""}`,
+    ].join("\n");
+}

package/dist/src/core/ranking.js

@@ -0,0 +1,104 @@
+const TIER_ORDER = {
+    official: 4,
+    stable: 3,
+    trending: 2,
+    community: 1,
+};
+function bounded(value, maximum) {
+    return Math.max(0, Math.min(maximum, value));
+}
+function daysSince(value, now) {
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp) || timestamp > now.getTime())
+        return undefined;
+    return (now.getTime() - timestamp) / 86_400_000;
+}
+/**
+ * Explain the score from evidence that is actually present in the catalog.
+ * A single star count cannot establish momentum, so momentum is intentionally
+ * assigned zero points until the discovery service stores a second observation.
+ */
+export function explainCatalogScore(pkg, now = new Date()) {
+    const adoption = pkg.stars === undefined
+        ? {
+            factor: "adoption",
+            points: 0,
+            maximum: 30,
+            evidence: "No independently fetched adoption count is available.",
+        }
+        : {
+            factor: "adoption",
+            points: Number(bounded((Math.log10(pkg.stars + 1) / 6) * 30, 30).toFixed(2)),
+            maximum: 30,
+            evidence: `${pkg.stars.toLocaleString()} GitHub stars, logarithmically scaled and capped.`,
+        };
+    const momentum = {
+        factor: "momentum",
+        points: 0,
+        maximum: 20,
+        evidence: "No two-point star or download history is stored yet; a single snapshot is not treated as momentum.",
+    };
+    const age = pkg.pushedAt ? daysSince(pkg.pushedAt, now) : undefined;
+    const maintenance = age === undefined
+        ? {
+            factor: "maintenance",
+            points: 0,
+            maximum: 20,
+            evidence: "No valid code-push timestamp is available; metadata edits and catalog verification are not counted as maintenance.",
+        }
+        : {
+            factor: "maintenance",
+            points: Number((age <= 30
+                ? 20
+                : age <= 90
+                    ? 16
+                    : age <= 180
+                        ? 10
+                        : age <= 365
+                            ? 5
+                            : 0).toFixed(2)),
+            maximum: 20,
+            evidence: `Repository code was last pushed ${Math.floor(age)} day(s) ago.`,
+        };
+    const platforms = pkg.operatingSystems?.length ?? 0;
+    // Catalog operatingSystems describe where Loadout can inspect the Git
+    // source, not where every component has been proven installable. Until a
+    // record carries agent-specific compatibility evidence, do not award those
+    // ten points.
+    const compatibilityPoints = pkg.components?.length ? 5 : 0;
+    const compatibility = {
+        factor: "compatibility",
+        points: Number(compatibilityPoints.toFixed(2)),
+        maximum: 15,
+        evidence: `${pkg.components?.length ?? 0} evidenced component kind(s) and ${platforms} source-inspection platform(s); no package or adapter compatibility is inferred.`,
+    };
+    const assertedLicense = Boolean(pkg.license && pkg.license.toUpperCase() !== "NOASSERTION");
+    const trustPoints = (pkg.source ? 6 : 0) +
+        (assertedLicense ? 4 : 0) +
+        (pkg.tier === "official" ? 5 : 0);
+    const trust = {
+        factor: "trust",
+        points: trustPoints,
+        maximum: 15,
+        evidence: `${pkg.source ? "Immutable source evidence" : "No immutable source evidence"}, ${assertedLicense ? `asserted ${pkg.license} license metadata` : pkg.license === "NOASSERTION" ? "license is unknown (NOASSERTION)" : "no license metadata"}${pkg.tier === "official" ? ", and a declared official publisher tier" : ""}.`,
+    };
+    const contributions = [adoption, momentum, maintenance, compatibility, trust];
+    return {
+        score: Number(contributions
+            .reduce((sum, contribution) => sum + contribution.points, 0)
+            .toFixed(2)),
+        contributions,
+        guardrails: [
+            "Scores order candidates inside a capability category; they do not compare unrelated tools or prove universal quality.",
+            "Stars are logarithmic and capped, so popularity cannot overwhelm tier, provenance, license, archive, or compatibility policy.",
+            "Missing evidence earns no points. Self-reported README claims, topics, and a single timestamp are not treated as adoption, momentum, or safety proof.",
+            "Official is a publisher-identity tier, not a security guarantee. Archived packages remain ineligible for automatic profiles.",
+        ],
+    };
+}
+/** A deterministic ordering: review tier first, then explainable evidence, then id. */
+export function compareCatalogPackages(a, b) {
+    return (TIER_ORDER[b.tier] - TIER_ORDER[a.tier] ||
+        explainCatalogScore(b).score - explainCatalogScore(a).score ||
+        a.id.localeCompare(b.id));
+}