loadout-ai 0.1.0

package/dist/src/core/skill-compare.js

@@ -0,0 +1,239 @@
+import { basename } from "node:path";
+import { explainCatalogScore } from "./ranking.js";
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "as",
+    "at",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "is",
+    "it",
+    "of",
+    "on",
+    "or",
+    "the",
+    "this",
+    "to",
+    "tool",
+    "use",
+    "using",
+    "with",
+    "workflow",
+]);
+function normalized(value) {
+    return value.trim().toLowerCase();
+}
+function terms(name, description) {
+    return new Set(`${name} ${description ?? ""}`
+        .toLowerCase()
+        .replace(/[^a-z0-9+#.-]+/g, " ")
+        .split(/\s+/)
+        .map((value) => value.replace(/^[.-]+|[.-]+$/g, ""))
+        .filter((value) => value.length > 1 && !STOP_WORDS.has(value)));
+}
+function jaccard(left, right) {
+    const union = new Set([...left, ...right]);
+    if (!union.size)
+        return 0;
+    const intersection = [...left].filter((value) => right.has(value)).length;
+    return intersection / union.size;
+}
+function relationship(subject, candidate) {
+    if (subject.fingerprint === candidate.fingerprint)
+        return { relationship: "exact-copy", similarity: 1 };
+    if (normalized(subject.name) === normalized(candidate.skillName))
+        return { relationship: "divergent-same-name", similarity: 1 };
+    const similarity = jaccard(terms(subject.name, subject.description), terms(candidate.skillName, candidate.description));
+    if (similarity >= 0.3)
+        return { relationship: "overlapping-capability", similarity };
+    const subjectCategory = subject.catalog?.category;
+    if (subjectCategory && subjectCategory === candidate.category)
+        return { relationship: "same-category-candidate", similarity };
+    return { similarity };
+}
+function installedMatches(query, report, agent) {
+    const value = normalized(query);
+    const scoped = agent
+        ? report.skills.filter((skill) => skill.agent === agent)
+        : report.skills;
+    const exact = scoped.filter((skill) => normalized(skill.name) === value ||
+        normalized(basename(skill.path)) === value ||
+        skill.provenance.candidates.some((candidate) => candidate.packageId === value));
+    if (exact.length)
+        return exact;
+    return scoped.filter((skill) => normalized(skill.name).includes(value) ||
+        normalized(basename(skill.path)).includes(value));
+}
+function selectInstalledSubject(query, matches) {
+    if (!matches.length)
+        return { mirrors: [] };
+    const fingerprints = new Set(matches.map((skill) => skill.fingerprint));
+    if (fingerprints.size > 1)
+        throw new Error(`Several divergent installed skills match '${query}'. Re-run with --agent <id> or use an exact skill directory name: ${matches.map((skill) => `${skill.agent}:${basename(skill.path)}`).join(", ")}`);
+    const selected = matches[0];
+    return {
+        subject: {
+            source: "installed",
+            name: selected.name,
+            ...(selected.description ? { description: selected.description } : {}),
+            fingerprint: selected.fingerprint,
+            agent: selected.agent,
+            path: selected.path,
+            provenance: selected.provenance,
+            ...(selected.provenance.candidates[0]
+                ? { catalog: selected.provenance.candidates[0] }
+                : {}),
+        },
+        mirrors: matches
+            .filter((skill) => skill !== selected)
+            .map((skill) => ({ agent: skill.agent, path: skill.path })),
+    };
+}
+function selectCatalogSubject(query, records) {
+    const value = normalized(query);
+    const matches = records.filter((record) => record.packageId === value || normalized(record.skillName) === value);
+    if (!matches.length)
+        return undefined;
+    if (matches.length > 1 && matches.every((item) => item.packageId === value))
+        throw new Error(`Catalog package '${query}' contains ${matches.length} skills. Compare one by skill name: ${matches
+            .slice(0, 20)
+            .map((item) => item.skillName)
+            .join(", ")}`);
+    if (matches.length > 1)
+        throw new Error(`Several reviewed catalog skills are named '${query}'. Use a package id or inspect JSON output to disambiguate: ${[...new Set(matches.map((item) => item.packageId))].join(", ")}`);
+    const selected = matches[0];
+    return {
+        source: "catalog",
+        name: selected.skillName,
+        ...(selected.description ? { description: selected.description } : {}),
+        fingerprint: selected.fingerprint,
+        catalog: selected,
+    };
+}
+function evidenceFor(relationshipValue, similarity, candidate, pkg) {
+    const relationshipEvidence = {
+        "exact-copy": "The SKILL.md instruction fingerprint is identical.",
+        "divergent-same-name": "The normalized name matches but the instructions differ; this is not proof of equivalence or improvement.",
+        "overlapping-capability": `Name/description token overlap is ${(similarity * 100).toFixed(0)}%; task evaluation is still required.`,
+        "same-category-candidate": "The catalog category matches, but textual overlap is weak; treat this as exploration rather than a replacement.",
+    };
+    return [
+        relationshipEvidence[relationshipValue],
+        `${candidate.tier} catalog tier; reviewed commit ${candidate.commit.slice(0, 12)}; license ${candidate.license ?? "unverified"}.`,
+        pkg
+            ? `Evidence score ${explainCatalogScore(pkg).score}/100 orders catalog evidence only; it is not a universal quality score.`
+            : "No current catalog metadata was available for an evidence score.",
+    ];
+}
+function evidenceDimensionsFor(pkg) {
+    const explanation = pkg ? explainCatalogScore(pkg) : undefined;
+    const contribution = (factor) => explanation?.contributions.find((item) => item.factor === factor)
+        ?.evidence ?? "No current catalog evidence is available.";
+    return {
+        adoption: contribution("adoption"),
+        momentum: contribution("momentum"),
+        maintenance: contribution("maintenance"),
+        compatibility: contribution("compatibility"),
+        permissions: "No declarative permission manifest exists for this skill; preview and safety inspection are required before install.",
+        evaluation: "No skill-specific model-output benchmark is stored yet; relationship evidence is not an outcome evaluation.",
+    };
+}
+function recommendationFor(subject, alternatives) {
+    if (subject.source === "catalog")
+        return alternatives.length
+            ? "This is a reviewed catalog skill, not an installed replacement decision. Compare the related candidates on your task before choosing what to install."
+            : "This is a reviewed catalog skill with no related candidate strong enough to show. Inspect its evidence and preview its files before deciding whether to install it.";
+    if (subject.provenance?.kind === "catalog-exact" ||
+        subject.provenance?.kind === "loadout-managed")
+        return "Keep the installed skill for now: its source is strongly attributable. Review alternatives only if a task-specific evaluation or maintenance signal demonstrates an advantage.";
+    const sameName = alternatives.find((item) => item.relationship === "divergent-same-name");
+    if (sameName)
+        return `Review ${sameName.packageDisplayName}/${sameName.skillName} head-to-head before replacing anything. It has the same name but different instructions, so Loadout cannot honestly call it better yet.`;
+    const overlapping = alternatives.find((item) => item.relationship === "overlapping-capability");
+    if (overlapping)
+        return `Explore ${overlapping.packageDisplayName}/${overlapping.skillName} as a possible alternative. Keep the current skill until category-specific evaluation or your explicit outcome supports a change.`;
+    return "No reviewed replacement has enough relationship evidence. Keep the current skill, record its source if known, and leave it marked unknown rather than guessing.";
+}
+export function compareSkill(query, inventory, records, catalog, options = {}) {
+    if (!query.trim())
+        throw new Error("Comparison query cannot be empty");
+    const installed = selectInstalledSubject(query, installedMatches(query, inventory, options.agent));
+    const subject = installed.subject ?? selectCatalogSubject(query, records);
+    if (!subject)
+        throw new Error(`No installed or reviewed catalog skill matches '${query}'. Run loadout scan --refresh-provenance or loadout search first.`);
+    const packages = new Map(catalog.map((pkg) => [pkg.id, pkg]));
+    const priority = {
+        "exact-copy": 4,
+        "divergent-same-name": 3,
+        "overlapping-capability": 2,
+        "same-category-candidate": 1,
+    };
+    const alternatives = records
+        .filter((candidate) => !(subject.catalog &&
+        candidate.packageId === subject.catalog.packageId &&
+        candidate.skillPath === subject.catalog.skillPath))
+        .map((candidate) => {
+        const relation = relationship(subject, candidate);
+        if (!relation.relationship)
+            return undefined;
+        const pkg = packages.get(candidate.packageId);
+        const explanation = pkg ? explainCatalogScore(pkg) : undefined;
+        return {
+            relationship: relation.relationship,
+            similarity: Number(relation.similarity.toFixed(4)),
+            ...candidate,
+            evidenceScore: explanation?.score ?? 0,
+            evidence: evidenceFor(relation.relationship, relation.similarity, candidate, pkg),
+            evidenceDimensions: evidenceDimensionsFor(pkg),
+        };
+    })
+        .filter((candidate) => candidate !== undefined)
+        .sort((left, right) => priority[right.relationship] - priority[left.relationship] ||
+        right.similarity - left.similarity ||
+        right.evidenceScore - left.evidenceScore ||
+        left.packageId.localeCompare(right.packageId))
+        .slice(0, Math.max(1, Math.min(options.limit ?? 10, 50)));
+    return {
+        query,
+        subject,
+        mirroredInstallations: installed.mirrors,
+        alternatives,
+        recommendation: recommendationFor(subject, alternatives),
+        uncertainty: "This comparison uses provenance, reviewed static evidence, maintenance/adoption metadata, and deterministic text relationships. It does not prove that one skill produces better model output on every task.",
+        ...(options.indexGeneratedAt
+            ? { catalogIndexGeneratedAt: options.indexGeneratedAt }
+            : {}),
+        catalogIndexFailures: options.failures ?? [],
+    };
+}
+export function formatSkillComparison(report) {
+    const subject = report.subject;
+    const lines = [
+        `Compare: ${subject.name}`,
+        `Subject: ${subject.source}${subject.agent ? ` on ${subject.agent}` : ""}${subject.path ? ` — ${subject.path}` : ""}`,
+    ];
+    if (subject.catalog)
+        lines.push(`Reviewed source: ${subject.catalog.packageDisplayName} · ${subject.catalog.repository}@${subject.catalog.commit.slice(0, 12)} · ${subject.catalog.tier} · license ${subject.catalog.license ?? "unverified"}`);
+    if (subject.provenance)
+        lines.push(`Provenance: ${subject.provenance.kind} (${subject.provenance.confidence})`, ...subject.provenance.evidence.map((item) => `  ${item}`));
+    if (report.mirroredInstallations.length)
+        lines.push(`Mirrors: ${report.mirroredInstallations.map((item) => `${item.agent}:${item.path}`).join(", ")}`);
+    lines.push("", "Reviewed alternatives:");
+    if (!report.alternatives.length)
+        lines.push("  No related reviewed candidate found.");
+    for (const alternative of report.alternatives) {
+        lines.push(`  ${alternative.packageDisplayName}/${alternative.skillName} [${alternative.relationship}]`, `    ${alternative.repository}@${alternative.commit.slice(0, 12)} · ${alternative.tier} · evidence ${alternative.evidenceScore}/100`);
+        for (const evidence of alternative.evidence)
+            lines.push(`    - ${evidence}`);
+        lines.push(`    Adoption: ${alternative.evidenceDimensions.adoption}`, `    Momentum: ${alternative.evidenceDimensions.momentum}`, `    Maintenance: ${alternative.evidenceDimensions.maintenance}`, `    Compatibility: ${alternative.evidenceDimensions.compatibility}`, `    Permissions: ${alternative.evidenceDimensions.permissions}`, `    Evaluation: ${alternative.evidenceDimensions.evaluation}`);
+    }
+    lines.push("", `Recommendation: ${report.recommendation}`, `Uncertainty: ${report.uncertainty}`);
+    if (report.catalogIndexFailures.length)
+        lines.push(`Index warning: ${report.catalogIndexFailures.length} reviewed repository/repositories could not be indexed.`);
+    return lines.join("\n");
+}

package/dist/src/core/skill-inventory.js

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { readInstallState } from "./state.js";
+const MAX_SCAN_DEPTH = 6;
+export const RECOMMENDED_ACTIVE_SKILLS = 30;
+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 isInside(root, candidate) {
+    const path = relative(resolve(root), resolve(candidate));
+    return path === "" || (!path.startsWith("..") && !path.startsWith(sep));
+}
+function owningPackage(skillRoot, agent, records, activations) {
+    const active = activations.find((record) => record.agent === agent &&
+        record.activationState === "active" &&
+        record.installationState === "installed" &&
+        record.targets.some((target) => isInside(target.activePath, skillRoot)));
+    if (active)
+        return active.packageId;
+    return records.find((record) => record.targetAgents.includes(agent) &&
+        !activations.some((activation) => activation.packageId === record.packageId &&
+            activation.agent === agent) &&
+        record.files.some((file) => isInside(skillRoot, file.path)))?.packageId;
+}
+async function scanAgentSkills(agent, records, activations) {
+    const root = resolve(agent.skillsDirectory);
+    const skills = [];
+    const warnings = [];
+    async function visit(directory, depth) {
+        let info;
+        try {
+            info = await lstat(directory);
+        }
+        catch {
+            return;
+        }
+        if (info.isSymbolicLink()) {
+            warnings.push(`${agent.displayName}: symlinked skill path was reported but not followed: ${directory}`);
+            return;
+        }
+        if (!info.isDirectory())
+            return;
+        let children;
+        try {
+            children = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            warnings.push(`${agent.displayName}: could not read ${directory}`);
+            return;
+        }
+        const skillFile = children.find((entry) => entry.isFile() && entry.name === "SKILL.md");
+        if (skillFile) {
+            try {
+                const path = join(directory, "SKILL.md");
+                const content = await readFile(path, "utf8");
+                const packageId = owningPackage(directory, agent.id, records, activations);
+                const sourceHints = [
+                    ...new Set([
+                        ...content.matchAll(/https?:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
+                    ].map((match) => match[1].replace(/\.git$/, ""))),
+                ].sort();
+                skills.push({
+                    agent: agent.id,
+                    agentDisplayName: agent.displayName,
+                    name: cleanFrontmatterValue(content.match(/^name:\s*(.+)$/m)?.[1]) ??
+                        directory.split(sep).at(-1) ??
+                        "unnamed",
+                    ...(cleanFrontmatterValue(content.match(/^description:\s*(.+)$/m)?.[1])
+                        ? {
+                            description: cleanFrontmatterValue(content.match(/^description:\s*(.+)$/m)?.[1]),
+                        }
+                        : {}),
+                    path: directory,
+                    fingerprint: createHash("sha256").update(content).digest("hex"),
+                    managed: Boolean(packageId),
+                    ...(packageId ? { packageId } : {}),
+                    ...(sourceHints.length ? { sourceHints } : {}),
+                });
+            }
+            catch (error) {
+                warnings.push(`${agent.displayName}: could not inspect ${join(directory, "SKILL.md")}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return;
+        }
+        if (depth >= MAX_SCAN_DEPTH) {
+            warnings.push(`${agent.displayName}: stopped scanning below depth ${MAX_SCAN_DEPTH}: ${directory}`);
+            return;
+        }
+        for (const child of children) {
+            if (child.name === ".git" ||
+                child.name === "node_modules" ||
+                child.name === ".cache")
+                continue;
+            if (child.isDirectory() || child.isSymbolicLink())
+                await visit(join(directory, child.name), depth + 1);
+        }
+    }
+    await visit(root, 0);
+    return {
+        skills: skills.sort((left, right) => left.path.localeCompare(right.path)),
+        warnings,
+    };
+}
+function duplicateGroups(skills) {
+    const byName = new Map();
+    for (const skill of skills) {
+        const key = skill.name.trim().toLowerCase();
+        const items = byName.get(key) ?? [];
+        items.push(skill);
+        byName.set(key, items);
+    }
+    return [...byName.entries()]
+        .filter(([, entries]) => entries.length > 1)
+        .map(([name, entries]) => {
+        const agents = entries.map((entry) => entry.agent);
+        const withinAgent = new Set(agents).size < agents.length;
+        return {
+            name,
+            kind: withinAgent ? "within-agent" : "cross-agent-mirror",
+            entries: entries.map((entry) => ({
+                agent: entry.agent,
+                path: entry.path,
+                fingerprint: entry.fingerprint,
+                managed: entry.managed,
+                ...(entry.packageId ? { packageId: entry.packageId } : {}),
+            })),
+        };
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Read existing agent skill directories without executing their instructions.
+ * Unmanaged means only "not installed by Loadout"; it is not a quality or
+ * safety verdict and no files are changed by this scan.
+ */
+export async function scanInstalledSkills(agents) {
+    const state = await readInstallState();
+    const scans = await Promise.all(agents.map((agent) => scanAgentSkills(agent, state.installs, state.activations ?? [])));
+    const skills = scans.flatMap((scan) => scan.skills);
+    const warnings = scans.flatMap((scan) => scan.warnings);
+    const summaries = agents.map((agent, index) => {
+        const entries = scans[index].skills;
+        const managed = entries.filter((entry) => entry.managed).length;
+        return {
+            agent: agent.id,
+            displayName: agent.displayName,
+            directory: agent.skillsDirectory,
+            detected: agent.installed,
+            total: entries.length,
+            managed,
+            unmanaged: entries.length - managed,
+            overRecommendedLimit: entries.length > RECOMMENDED_ACTIVE_SKILLS,
+        };
+    });
+    for (const summary of summaries.filter((item) => item.overRecommendedLimit))
+        warnings.push(`${summary.displayName} exposes ${summary.total} skills; the recommended active set is at most ${RECOMMENDED_ACTIVE_SKILLS}.`);
+    const managed = skills.filter((entry) => entry.managed).length;
+    return {
+        generatedAt: new Date().toISOString(),
+        total: skills.length,
+        managed,
+        unmanaged: skills.length - managed,
+        uniqueNames: new Set(skills.map((entry) => entry.name.trim().toLowerCase()))
+            .size,
+        agents: summaries,
+        skills,
+        duplicates: duplicateGroups(skills),
+        warnings,
+    };
+}
+export function formatInstalledSkillInventory(report) {
+    const within = report.duplicates.filter((group) => group.kind === "within-agent").length;
+    const mirrors = report.duplicates.length - within;
+    const lines = [
+        `Skill inventory: ${report.total} skill(s), ${report.uniqueNames} unique name(s)`,
+        `Loadout-managed: ${report.managed}; unmanaged: ${report.unmanaged}`,
+        `Duplicate groups: ${within} within an agent; ${mirrors} cross-agent mirror(s)`,
+        "",
+    ];
+    for (const agent of report.agents)
+        lines.push(`${agent.detected ? "✓" : "○"} ${agent.displayName}: ${agent.total} skill(s) (${agent.managed} managed, ${agent.unmanaged} unmanaged) — ${agent.directory}`);
+    for (const warning of report.warnings)
+        lines.push(`! ${warning}`);
+    lines.push("", "Read-only scan complete. Unmanaged content was not changed or judged automatically.");
+    return lines.join("\n");
+}