loadout-ai 0.1.0

package/dist/src/core/update.js

@@ -0,0 +1,216 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fetchRepositorySnapshot } from "./source.js";
+import { repositoryCachePath } from "./source.js";
+import { diffRepositorySnapshots } from "./diff.js";
+import { hashDirectory, readInstallState } from "./state.js";
+import { analyzeUpdateSafety } from "./safety.js";
+import { detectAgents, loadoutHome } from "./paths.js";
+import { applySkillInstall, buildSkillPlan, installedAgents, } from "./install.js";
+import { validateSkillDirectory } from "./skills.js";
+/** Builds a read-only update plan from persisted installs and live GitHub snapshots. */
+export async function buildUpdatePlan(resolver = async (repository) => fetchRepositorySnapshot(repository)) {
+    const state = await readInstallState();
+    return Promise.all(state.installs.map(async (record) => {
+        const disabledAgents = (state.activations ?? [])
+            .filter((activation) => activation.packageId === record.packageId &&
+            activation.installationState === "installed" &&
+            activation.activationState === "disabled")
+            .map((activation) => activation.agent);
+        const base = {
+            packageId: record.packageId,
+            repository: record.repository,
+            installedCommit: record.resolvedCommit,
+            targetAgents: record.targetAgents,
+            ...(disabledAgents.length ? { disabledAgents } : {}),
+        };
+        if (!record.repository || !record.resolvedCommit) {
+            return {
+                ...base,
+                status: "untracked",
+                action: "Reinstall from the original source to begin update tracking.",
+            };
+        }
+        try {
+            const current = await resolver(record.repository);
+            const same = current.commit.toLowerCase() === record.resolvedCommit.toLowerCase();
+            let diff;
+            let safetyFindings;
+            let approvalRequired = false;
+            if (!same && current.path) {
+                const oldPath = repositoryCachePath(record.repository, record.resolvedCommit);
+                diff = await diffRepositorySnapshots(oldPath, current.path);
+                const safety = await analyzeUpdateSafety(oldPath, current.path);
+                safetyFindings = safety.findings;
+                approvalRequired = safety.approvalRequired;
+            }
+            return {
+                ...base,
+                availableCommit: current.commit,
+                status: same ? "up-to-date" : "update-available",
+                action: same
+                    ? "No action required."
+                    : disabledAgents.length
+                        ? `Enable ${record.packageId} for ${disabledAgents.join(", ")} before applying an update; planning remains read-only.`
+                        : approvalRequired
+                            ? `Approval required: review safety warnings before updating ${record.packageId}.`
+                            : `Run loadout update --package ${record.packageId} after review.`,
+                ...(approvalRequired ? { approvalRequired: true } : {}),
+                ...(safetyFindings?.length ? { safetyFindings } : {}),
+                ...(diff ? { diff } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                ...base,
+                status: "error",
+                action: "Retry when GitHub is reachable; the installed version was not changed.",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }));
+}
+export function formatUpdatePlan(plans) {
+    if (plans.length === 0)
+        return "No tracked installations found.";
+    return plans
+        .map((plan) => {
+        const suffix = plan.error ? ` — ${plan.error}` : "";
+        const repo = plan.repository ? ` (${plan.repository})` : "";
+        const safety = plan.safetyFindings
+            ?.map((finding) => ` [${finding.severity}] ${finding.message}${finding.names?.length ? ` (${finding.names.join(", ")})` : ""}`)
+            .join("") ?? "";
+        return `${plan.status.toUpperCase()} ${plan.packageId}${repo}: ${plan.action}${safety}${suffix}`;
+    })
+        .join("\n");
+}
+function quarantineRoot() {
+    return join(loadoutHome(), "quarantine");
+}
+function safeName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 160) || "update";
+}
+/**
+ * Record a blocked update in an isolated review directory. This writes metadata
+ * only; it never installs files, imports configuration, or executes repository code.
+ */
+export async function quarantineUpdate(packageId, repository, commit, findings) {
+    const directory = join(quarantineRoot(), `${safeName(packageId)}-${safeName(commit)}`);
+    await mkdir(directory, { recursive: true });
+    const metadata = join(directory, "metadata.json");
+    await writeFile(metadata, JSON.stringify({
+        packageId,
+        repository,
+        commit,
+        quarantinedAt: new Date().toISOString(),
+        findings: findings.map(({ severity, category, message, paths, names }) => ({
+            severity,
+            category,
+            message,
+            paths,
+            ...(names?.length ? { names } : {}),
+        })),
+    }, null, 2) + "\n", { mode: 0o600 });
+    return directory;
+}
+/**
+ * Verify copied skill metadata only. This is deliberately static: Loadout does
+ * not run hooks, lifecycle scripts, MCP servers, or any repository code while
+ * applying an update.
+ */
+async function verifyInstalledSkills(context) {
+    for (const file of context.plan.files)
+        await validateSkillDirectory(file.target);
+}
+/**
+ * Apply an already reviewed package update. A failed post-copy verification
+ * restores the transaction snapshot, including the previous install state.
+ */
+export async function applyPackageUpdate(packageId, options = {}, runtime = {}) {
+    const state = await readInstallState();
+    const record = state.installs.find((item) => item.packageId === packageId);
+    if (!record)
+        throw new Error(`Package is not managed by Loadout: ${packageId}`);
+    const disabledAgents = (state.activations ?? [])
+        .filter((activation) => activation.packageId === packageId &&
+        activation.installationState === "installed" &&
+        activation.activationState === "disabled")
+        .map((activation) => activation.agent);
+    const expectedRecord = JSON.stringify(record);
+    const expectedActivations = JSON.stringify((state.activations ?? [])
+        .filter((activation) => activation.packageId === packageId)
+        .sort((left, right) => `${left.agent}\0${left.unitId ?? ""}`.localeCompare(`${right.agent}\0${right.unitId ?? ""}`)));
+    if (disabledAgents.length)
+        throw new Error(`Package '${packageId}' is disabled for ${disabledAgents.join(", ")}. Enable it before updating so an update cannot silently reactivate agent-visible files.`);
+    if (!record.repository || !record.resolvedCommit)
+        throw new Error(`Package '${packageId}' has no tracked GitHub source`);
+    const current = await (runtime.fetchSnapshot ?? fetchRepositorySnapshot)(record.repository);
+    if (current.commit.toLowerCase() === record.resolvedCommit.toLowerCase())
+        throw new Error(`Package '${packageId}' is already up to date`);
+    const oldPath = repositoryCachePath(record.repository, record.resolvedCommit);
+    const safety = await analyzeUpdateSafety(oldPath, current.path);
+    if (safety.approvalRequired && !options.approveRisk) {
+        const quarantinePath = options.quarantineOnBlock === false
+            ? undefined
+            : await quarantineUpdate(packageId, current.repository, current.commit, safety.findings);
+        throw new Error(`Update is blocked pending explicit risk approval${quarantinePath ? `; quarantined at ${quarantinePath}` : ""}: ${safety.findings
+            .filter((finding) => finding.severity === "blocking")
+            .map((finding) => finding.message)
+            .join(" ")}`);
+    }
+    const agents = installedAgents(await (runtime.detectAgents ?? detectAgents)(), record.targetAgents);
+    const plan = await (runtime.buildPlan ?? buildSkillPlan)(current.path, record.packageId, agents);
+    const verifier = runtime.verify ?? verifyInstalledSkills;
+    let verificationFailure;
+    let verificationSnapshotId;
+    try {
+        const snapshotId = await applySkillInstall(plan, {
+            repository: current.repository,
+            resolvedCommit: current.commit,
+        }, {
+            allowManagedReplacement: true,
+            replaceManagedTargets: true,
+            validateCurrentState: async () => {
+                const freshState = await readInstallState();
+                const freshRecord = freshState.installs.find((entry) => entry.packageId === packageId);
+                const freshActivations = (freshState.activations ?? [])
+                    .filter((activation) => activation.packageId === packageId)
+                    .sort((left, right) => `${left.agent}\0${left.unitId ?? ""}`.localeCompare(`${right.agent}\0${right.unitId ?? ""}`));
+                if (JSON.stringify(freshRecord) !== expectedRecord ||
+                    JSON.stringify(freshActivations) !== expectedActivations)
+                    throw new Error(`Package '${packageId}' changed while its update was prepared; build the update plan again`);
+                const liveFiles = (await Promise.all([...new Set(plan.files.map((file) => file.target))].map(hashDirectory)))
+                    .flat()
+                    .sort((left, right) => left.path.localeCompare(right.path));
+                const expectedFiles = [...record.files].sort((left, right) => left.path.localeCompare(right.path));
+                if (JSON.stringify(liveFiles) !== JSON.stringify(expectedFiles))
+                    throw new Error(`Package '${packageId}' files changed while its update was prepared; review local changes before updating`);
+            },
+            verifyBeforeCommit: async (pendingSnapshotId) => {
+                verificationSnapshotId = pendingSnapshotId;
+                try {
+                    await verifier({
+                        packageId,
+                        commit: current.commit,
+                        plan,
+                        snapshotId: pendingSnapshotId,
+                    });
+                }
+                catch (error) {
+                    verificationFailure = error;
+                    throw error;
+                }
+            },
+        });
+        return { snapshotId, commit: current.commit };
+    }
+    catch (error) {
+        if (verificationFailure !== undefined) {
+            const detail = verificationFailure instanceof Error
+                ? verificationFailure.message
+                : String(verificationFailure);
+            throw new Error(`Update verification failed; restored snapshot ${verificationSnapshotId}: ${detail}`, { cause: verificationFailure });
+        }
+        throw error;
+    }
+}

package/dist/src/core/upgrade.js

@@ -0,0 +1,207 @@
+import { buildAdapterCapabilityGaps, } from "./adapters.js";
+import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, RECOMMENDED_ACTIVE_SKILL_LIMIT, } from "./catalog-install.js";
+import { loadEffectiveCatalog } from "./catalog.js";
+import { buildHealthReport, formatHealthReport } from "./health.js";
+import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
+import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "./recommend.js";
+import { readLocalOutcomes } from "./outcomes.js";
+/**
+ * Builds the complete first-run preview without changing agent or Loadout state.
+ * Network access is limited to the same immutable catalog preparation performed by
+ * `setup`; the health and project scans remain local.
+ */
+export async function planUpgrade(selection, options = {}) {
+    const projectPath = options.projectPath ?? process.cwd();
+    const catalog = options.catalog ?? (await loadEffectiveCatalog());
+    const health = options.health ?? (() => buildHealthReport());
+    const healthScores = options.healthScores ?? (() => buildLocalAgentHealthScores());
+    const projectScan = options.projectScan ?? scanProject;
+    const outcomes = options.outcomes ?? readLocalOutcomes;
+    const [healthBefore, healthScoresBefore, project, prepared, localOutcomes] = await Promise.all([
+        health(),
+        healthScores(),
+        projectScan(projectPath),
+        prepareCatalogInstall(selection, {
+            catalog,
+            ...(options.requestedAgents
+                ? { requestedAgents: options.requestedAgents }
+                : {}),
+            ...(options.detectedAgents
+                ? { detectedAgents: options.detectedAgents }
+                : {}),
+            ...(options.fetchSnapshot
+                ? { fetchSnapshot: options.fetchSnapshot }
+                : {}),
+            ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+        }),
+        outcomes(),
+    ]);
+    const recommendations = recommendPackages(project, catalog);
+    const personalizedRecommendations = prepared.agents.map((agent) => ({
+        agent: agent.id,
+        recommendations: personalizeRecommendations(recommendations, project, localOutcomes, agent.id),
+    }));
+    const selectedAgents = new Set(prepared.agents.map((agent) => agent.id));
+    const capabilityGaps = buildAdapterCapabilityGaps().filter((gap) => selectedAgents.has(gap.agent));
+    const alternatives = [
+        ...prepared.resolution.conflicts.map((conflict) => ({
+            kind: "profile-conflict",
+            selected: conflict.defaultPackageId ?? conflict.packageIds[0] ?? "unresolved",
+            deferred: conflict.packageIds.filter((id) => id !== conflict.defaultPackageId),
+            reason: conflict.message,
+        })),
+        ...prepared.collisions.map((collision) => ({
+            kind: "target-overlap",
+            selected: collision.keptPackageId,
+            deferred: [collision.deferredPackageId],
+            reason: `Both packages target the same agent skill directory; ${collision.keptPackageId} wins by deterministic profile evidence order.`,
+        })),
+    ];
+    const deferredActions = prepared.skipped
+        .filter((item) => item.kind === "explicit-setup")
+        .map((item) => {
+        const pkg = prepared.resolution.packages.find((candidate) => candidate.id === item.packageId);
+        const components = pkg?.components ?? [];
+        return {
+            packageId: item.packageId,
+            components,
+            reason: item.reason,
+            nextCommand: components.includes("mcp")
+                ? `loadout mcp --repository ${pkg?.repository ?? item.packageId}`
+                : `loadout inspect ${item.packageId}`,
+            automatic: false,
+        };
+    });
+    const targetDirectories = prepared.entries.reduce((total, entry) => total + entry.plan.files.length, 0);
+    const plannedDirectoriesPerAgent = prepared.agents.length
+        ? Math.ceil(targetDirectories / prepared.agents.length)
+        : 0;
+    const activeSet = selection.mode === "maximum"
+        ? {
+            policy: "disabled-library",
+            recommendedLimit: RECOMMENDED_ACTIVE_SKILL_LIMIT,
+            plannedDirectoriesPerAgent,
+            exceedsRecommendedLimit: plannedDirectoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT,
+            explanation: "Maximum stores reviewed skills in the disabled library; it does not expose the full library to agent context.",
+            nextCommand: `loadout optimize --project ${project.root} --limit ${RECOMMENDED_ACTIVE_SKILL_LIMIT}`,
+        }
+        : {
+            policy: "bounded-active",
+            recommendedLimit: RECOMMENDED_ACTIVE_SKILL_LIMIT,
+            plannedDirectoriesPerAgent,
+            exceedsRecommendedLimit: plannedDirectoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT,
+            explanation: plannedDirectoriesPerAgent <= RECOMMENDED_ACTIVE_SKILL_LIMIT
+                ? "The prepared profile stays within the recommended active-set ceiling."
+                : "The prepared profile exceeds the recommended active-set ceiling; use Stable or project optimization before treating it as a daily active set.",
+            ...(plannedDirectoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT
+                ? {
+                    nextCommand: `loadout optimize --project ${project.root} --limit ${RECOMMENDED_ACTIVE_SKILL_LIMIT}`,
+                }
+                : {}),
+        };
+    const riskApprovalRequired = prepared.entries.some((entry) => entry.safety.approvalRequired);
+    return {
+        schemaVersion: 1,
+        generatedAt: (options.now?.() ?? new Date()).toISOString(),
+        project,
+        recommendations,
+        personalizedRecommendations,
+        localOutcomeEventsConsidered: localOutcomes.events.length,
+        healthBefore,
+        healthScoresBefore,
+        prepared,
+        alternatives,
+        capabilityGaps,
+        deferredActions,
+        activeSet,
+        riskApprovalRequired,
+        guarantees: [
+            "preview is read-only until --yes",
+            "reviewed GitHub inputs resolve to exact catalog commits",
+            "all selected agent targets are changed through one snapshot-backed transaction",
+            "unmanaged agent content is not adopted, overwritten, or removed",
+            "daily discovery and update checks remain read-only and opt-in",
+        ],
+    };
+}
+export async function applyUpgrade(plan, options = {}) {
+    if (plan.riskApprovalRequired && !options.approveRisk)
+        throw new Error("The upgrade preview contains reviewed safety findings; inspect it and add --approve-risk");
+    const snapshotId = await applyPreparedCatalogInstall(plan.prepared, {
+        approveRisk: options.approveRisk,
+    });
+    const healthAfter = await (options.health ?? (() => buildHealthReport()))();
+    const healthScoresAfter = await (options.healthScores ?? (() => buildLocalAgentHealthScores()))();
+    return {
+        snapshotId,
+        healthBefore: plan.healthBefore,
+        healthAfter,
+        healthScoresBefore: plan.healthScoresBefore,
+        healthScoresAfter,
+    };
+}
+export function summarizeUpgradePlan(plan) {
+    return {
+        schemaVersion: plan.schemaVersion,
+        generatedAt: plan.generatedAt,
+        mode: plan.prepared.selection.mode,
+        project: plan.project,
+        healthBefore: plan.healthBefore,
+        healthScoresBefore: plan.healthScoresBefore,
+        recommendations: plan.recommendations,
+        personalizedRecommendations: plan.personalizedRecommendations,
+        localOutcomeEventsConsidered: plan.localOutcomeEventsConsidered,
+        agents: plan.prepared.agents,
+        repositories: plan.prepared.resolution.packages.map((pkg) => ({
+            id: pkg.id,
+            repository: pkg.repository,
+            commit: pkg.source?.commit,
+            license: pkg.license,
+        })),
+        install: {
+            repositoryCount: plan.prepared.entries.length,
+            targetDirectoryCount: plan.prepared.entries.reduce((total, entry) => total + entry.plan.files.length, 0),
+            skipped: plan.prepared.skipped,
+            collisions: plan.prepared.collisions,
+            riskApprovalRequired: plan.riskApprovalRequired,
+            safetyFindings: plan.prepared.entries.flatMap((entry) => entry.safety.findings.map((finding) => ({
+                packageId: entry.package.id,
+                ...finding,
+            }))),
+        },
+        alternatives: plan.alternatives,
+        capabilityGaps: plan.capabilityGaps,
+        deferredActions: plan.deferredActions,
+        activeSet: plan.activeSet,
+        guarantees: plan.guarantees,
+    };
+}
+export function formatUpgradePlan(plan) {
+    return [
+        "Loadout upgrade preview",
+        "",
+        formatHealthReport(plan.healthBefore),
+        ...plan.healthScoresBefore.map((score) => `Agent Health Score (${score.agent}): ${score.score}/100 (${score.rating}; evidence coverage ${score.evidenceCoverage}%)`),
+        "",
+        formatRecommendations(plan.project, plan.recommendations),
+        ...plan.personalizedRecommendations.flatMap((item) => item.recommendations.some((recommendation) => recommendation.localOutcomeAdjustment !== undefined)
+            ? [
+                "",
+                `Local outcome personalization (${item.agent}; ${plan.localOutcomeEventsConsidered} local event(s), never uploaded):`,
+                formatRecommendations(plan.project, item.recommendations),
+            ]
+            : []),
+        "",
+        formatPreparedCatalogInstall(plan.prepared),
+        "",
+        `Active-set policy: ${plan.activeSet.policy}; about ${plan.activeSet.plannedDirectoriesPerAgent}/${plan.activeSet.recommendedLimit} directories per agent. ${plan.activeSet.explanation}`,
+        ...(plan.activeSet.nextCommand
+            ? [`Next bounded activation: ${plan.activeSet.nextCommand}`]
+            : []),
+        ...plan.alternatives.map((item) => `Alternative (${item.kind}): selected ${item.selected}; deferred ${item.deferred.join(", ")} — ${item.reason}`),
+        ...plan.deferredActions.map((item) => `Deferred explicit action: ${item.packageId} [${item.components.join(", ") || "unknown"}] — ${item.nextCommand}`),
+        `Unsupported selected-agent capability combinations: ${plan.capabilityGaps.length}; no undocumented path will be guessed.`,
+        "",
+        ...plan.guarantees.map((guarantee) => `Safety: ${guarantee}`),
+    ].join("\n");
+}