loadout-ai 0.2.3 → 0.4.0

package/dist/src/core/uninstall.js

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { readdir, rm, rmdir } from "node:fs/promises";
+import { dirname, parse, resolve } from "node:path";
+import { promisify } from "node:util";
+import { loadoutHome } from "./paths.js";
+import { applyRemove, planRemove } from "./remove.js";
+import { applyRuntimeToolPlan, listInstalledRuntimeTools, planRuntimeTool, } from "./runtime-tools.js";
+import { applyNativeSchedulerBundle, planNativeScheduler, } from "./scheduler.js";
+import { readInstallState } from "./state.js";
+export async function buildUninstallPlan(dependencies = {}) {
+    const stateHome = loadoutHome();
+    const state = await readInstallState();
+    const packageIds = [
+        ...new Set([
+            ...state.installs.map((install) => install.packageId),
+            ...(state.mcpInstalls ?? []).map((install) => install.packageId),
+        ]),
+    ];
+    const packages = await Promise.all(packageIds.map(planRemove));
+    const runtimeTools = await (dependencies.runtimeTools ?? listInstalledRuntimeTools)(stateHome);
+    const schedulers = dependencies.schedulerPlans?.() ??
+        ["updates", "discovery"].map((job) => planNativeScheduler("unschedule", { job }));
+    const warnings = packages.flatMap((entry) => entry.warnings);
+    if (runtimeTools.length)
+        warnings.push(`${runtimeTools.length} Loadout-managed runtime tool(s) will be restored to their pre-install snapshots.`);
+    warnings.push("Loadout's cache, disabled library, history, and rollback snapshots will be deleted. This final state cleanup cannot itself be rolled back.");
+    return {
+        stateHome,
+        packages,
+        runtimeTools,
+        schedulers,
+        disabledLibraryRecords: (state.activations ?? []).filter((entry) => entry.activationState === "disabled").length,
+        blocked: packages.some((entry) => entry.blocked),
+        warnings,
+    };
+}
+async function removeEmptyManagedDirectories(plans) {
+    const candidates = [
+        ...new Set(plans.flatMap((plan) => plan.files.map((file) => dirname(file.path)))),
+    ].sort((left, right) => right.length - left.length);
+    for (const directory of candidates) {
+        try {
+            const queue = [directory];
+            const visited = [directory];
+            let entriesChecked = 0;
+            let empty = true;
+            while (queue.length && empty) {
+                const current = queue.pop();
+                for (const entry of await readdir(current, { withFileTypes: true })) {
+                    entriesChecked += 1;
+                    if (entriesChecked > 10_000) {
+                        empty = false;
+                        break;
+                    }
+                    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                        const child = resolve(current, entry.name);
+                        queue.push(child);
+                        visited.push(child);
+                    }
+                    else {
+                        empty = false;
+                        break;
+                    }
+                }
+            }
+            if (empty)
+                for (const current of visited.sort((left, right) => right.length - left.length))
+                    await rmdir(current);
+        }
+        catch {
+            // Missing and non-empty directories are both safe to leave alone.
+        }
+    }
+}
+function assertSafeStateHome(stateHome) {
+    const expected = resolve(loadoutHome());
+    const selected = resolve(stateHome);
+    const root = parse(selected).root;
+    if (selected !== expected || selected === root)
+        throw new Error(`Refusing unsafe Loadout state deletion target: ${selected}`);
+}
+export async function applyUninstall(plan, dependencies = {}, options = {}) {
+    assertSafeStateHome(plan.stateHome);
+    const fresh = await buildUninstallPlan(dependencies);
+    if (fresh.blocked && !options.force)
+        throw new Error(`Complete uninstall is blocked because managed files were modified. Review them, or re-run with --force. ${fresh.warnings.join(" ")}`);
+    for (const id of fresh.runtimeTools) {
+        const runtimePlan = await planRuntimeTool(id, {
+            action: "remove",
+            stateHome: fresh.stateHome,
+        });
+        await applyRuntimeToolPlan(runtimePlan, { approveRisk: true });
+    }
+    for (const packagePlan of fresh.packages)
+        await applyRemove(packagePlan, { force: options.force });
+    await removeEmptyManagedDirectories(fresh.packages);
+    if (fresh.schedulers.length)
+        await (dependencies.unschedule
+            ? dependencies.unschedule(fresh.schedulers)
+            : applyNativeSchedulerBundle(fresh.schedulers));
+    await rm(fresh.stateHome, { recursive: true, force: true });
+    return {
+        removedPackages: fresh.packages.length,
+        removedRuntimeTools: fresh.runtimeTools.length,
+    };
+}
+const execFileAsync = promisify(execFile);
+/** Remove the globally installed npm launcher after managed data is gone. */
+export async function uninstallGlobalCli() {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    await execFileAsync(npm, ["uninstall", "--global", "loadout-ai"], {
+        windowsHide: true,
+    });
+}
+export function formatUninstallPlan(plan) {
+    return [
+        "Complete Loadout uninstall preview",
+        "",
+        `Managed packages: ${plan.packages.length}`,
+        `Managed runtime tools: ${plan.runtimeTools.length ? plan.runtimeTools.join(", ") : "none"}`,
+        `Disabled library records: ${plan.disabledLibraryRecords}`,
+        `Daily jobs to remove: ${plan.schedulers.map((item) => item.job).join(", ") || "none"}`,
+        `State and cache: ${plan.stateHome}`,
+        ...(plan.blocked
+            ? ["", "BLOCKED: managed files were changed outside Loadout."]
+            : []),
+        "",
+        ...plan.warnings.map((warning) => `Warning: ${warning}`),
+        "",
+        "Dry run only. Re-run with `loadout uninstall --yes` to remove Loadout-managed data.",
+        "Add `--remove-cli` to also uninstall the global npm command.",
+    ].join("\n");
+}

package/dist/src/core/update.js

@@ -85,66 +85,89 @@ async function analyzeManagedUpdate(oldRoot, newRoot, unitIds) {
     };
 }
 /** Builds a read-only update plan from persisted installs and live GitHub snapshots. */
-export async function buildUpdatePlan(resolver = async (repository) => fetchRepositorySnapshot(repository)) {
+export async function buildUpdatePlan(resolver = async (repository) => fetchRepositorySnapshot(repository, { timeoutMs: 30_000 }), options = {}) {
     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);
-                const analysis = await analyzeManagedUpdate(oldPath, current.path, managedUnitIds(state, record.packageId));
-                diff = analysis.diff;
-                safetyFindings = analysis.safetyFindings;
-                approvalRequired = analysis.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),
-            };
+    const records = options.packageId
+        ? state.installs.filter((record) => record.packageId === options.packageId)
+        : state.installs;
+    const results = new Array(records.length);
+    let cursor = 0;
+    let completed = 0;
+    const workers = Array.from({
+        length: Math.min(Math.max(1, options.concurrency ?? 4), Math.max(1, records.length)),
+    }, async () => {
+        while (cursor < records.length) {
+            const index = cursor++;
+            const record = records[index];
+            results[index] = await (async () => {
+                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);
+                        const analysis = await analyzeManagedUpdate(oldPath, current.path, managedUnitIds(state, record.packageId));
+                        diff = analysis.diff;
+                        safetyFindings = analysis.safetyFindings;
+                        approvalRequired = analysis.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} --yes 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),
+                    };
+                }
+            })();
+            completed += 1;
+            options.onProgress?.({
+                completed,
+                total: records.length,
+                packageId: record.packageId,
+            });
         }
-    }));
+    });
+    await Promise.all(workers);
+    return results;
 }
 export function formatUpdatePlan(plans) {
     if (plans.length === 0)
@@ -160,6 +183,12 @@ export function formatUpdatePlan(plans) {
     })
         .join("\n");
 }
+/** Updates safe enough for an explicit whole-profile `update --yes` apply. */
+export function selectSafeAutomaticUpdates(plans) {
+    return plans.filter((plan) => plan.status === "update-available" &&
+        !plan.approvalRequired &&
+        !plan.disabledAgents?.length);
+}
 function quarantineRoot() {
     return join(loadoutHome(), "quarantine");
 }

package/dist/src/dashboard.js

@@ -8,7 +8,7 @@ import { inspectAgents } from "./core/agent-inspection.js";
 import { loadEffectiveCatalog, rankCatalog } from "./core/catalog.js";
 import { buildUpdatePlan } from "./core/update.js";
 import { buildHealthReport } from "./core/health.js";
-import { recommendPackages, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
+import { recommendPackages, RECOMMENDATION_BOUNDARY, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
 import { searchLocalRegistry } from "./core/registry.js";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { applySyncPlan, buildSyncPlan } from "./core/sync.js";
@@ -318,6 +318,7 @@ async function route(request, response, context) {
             const signals = await scanProject(process.cwd());
             await sendJson(response, 200, {
                 signals,
+                recommendationBoundary: RECOMMENDATION_BOUNDARY,
                 recommendations: recommendPackages(signals, await loadEffectiveCatalog()),
             });
             return;
@@ -368,7 +369,9 @@ export function createDashboardServer(options = {}) {
         buildSync: options.buildSync ?? buildSyncPlan,
         applySync: options.applySync ?? applySyncPlan,
         rollback: options.rollback ??
-            (async (snapshotId) => withMutationLock(async () => restoreSnapshot(await readSnapshot(snapshotId)))),
+            (async (snapshotId) => withMutationLock(async () => restoreSnapshot(await readSnapshot(snapshotId), {
+                requireUnchangedPostMutationState: true,
+            }))),
         token: randomBytes(32).toString("hex"),
     };
     return createServer((request, response) => {

package/dist/src/shared/schemas.js

@@ -41,8 +41,26 @@ export const componentCompatibilitySchema = z.enum([
     "unsupported",
 ]);
 export const safetyRiskLevelSchema = z.enum(["safe", "review", "blocked"]);
+export const readmeClaimEvidenceClassSchema = z.enum([
+    "structural",
+    "unit-verified",
+    "integration-verified",
+    "live-verified",
+    "platform-verified",
+    "human-reviewed",
+    "benchmarked",
+    "policy-selected",
+]);
+export const readmeClaimStatusSchema = z.enum([
+    "proven",
+    "bounded",
+    "unfulfilled",
+]);
 const text = z.string().trim().min(1, "must not be empty");
 const optionalText = text.optional();
+const readmeClaimIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/, "must be a safe dotted identifier");
 const sha256 = z.string().regex(/^[a-f0-9]{64}$/i, "must be a SHA-256 hash");
 const gitSha = z.string().regex(/^[a-f0-9]{40}$/i, "must be a full Git SHA");
 const repository = z
@@ -304,6 +322,18 @@ export const installStateSchema = z
     installs: z.array(installRecordSchema),
     mcpInstalls: z.array(mcpInstallRecordSchema).default([]),
     activations: z.array(managedActivationRecordSchema).default([]),
+    profile: z
+        .object({
+        mode: z.enum(["stable", "power", "maximum", "custom"]),
+        packageIds: z.array(text).optional(),
+        agents: z.array(agentIdSchema),
+        catalogPackages: z.array(z.object({
+            packageId: text,
+            reviewedCommit: optionalText,
+        })),
+        appliedAt: text,
+    })
+        .optional(),
 })
     .passthrough();
 const lockedPackageSchema = z
@@ -336,6 +366,45 @@ export const loadoutLockfileSchema = z
         .optional(),
 })
     .passthrough();
+export const readmeClaimSchema = z
+    .object({
+    id: readmeClaimIdSchema,
+    section: text,
+    summary: text,
+    evidenceClass: readmeClaimEvidenceClassSchema,
+    status: readmeClaimStatusSchema,
+    evidence: z.array(text),
+    externalPrerequisites: z.array(text).optional(),
+})
+    .strict()
+    .superRefine((claim, context) => {
+    if (claim.status === "proven" && claim.evidence.length === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["evidence"],
+            message: "proven claims require at least one authoritative evidence reference",
+        });
+    }
+});
+export const readmeClaimManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    claims: z.array(readmeClaimSchema).min(1),
+})
+    .strict()
+    .superRefine((manifest, context) => {
+    const seen = new Set();
+    for (const [index, claim] of manifest.claims.entries()) {
+        if (seen.has(claim.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "id"],
+                message: "must be unique",
+            });
+        }
+        seen.add(claim.id);
+    }
+});
 /** Compact, path-aware errors suitable for CLI and persisted-data diagnostics. */
 export function formatSchemaError(error) {
     return error.issues

package/docs/FEATURE_TEST_MATRIX.md

@@ -121,8 +121,10 @@ reruns and diagnosis.
 | `npm run format:check`       | Repository formatting                                                   | Exit 0; no files changed.                          |
 | `npm run lint`               | TypeScript lint rules                                                   | Exit 0.                                            |
 | `npm run typecheck`          | TypeScript contract                                                     | Exit 0.                                            |
+| `npm run check:evidence`     | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
 | `npm test`                   | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
 | `npm run test:e2e:cli`       | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
+| `npm run test:e2e:readme`    | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
 | `npm run test:package`       | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
 | `npm run test:performance`   | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
 | `npm run test:e2e:dashboard` | Loopback dashboard first-run browser test                               | Playwright passes; no real profile is used.        |
@@ -131,6 +133,20 @@ The dashboard test needs a Playwright browser. If the browser executable is abse
 run `npx playwright install chromium` once; that download is not a Loadout product
 side effect.
 
+The focused regression contract for the v0.3.x profile lifecycle is:
+
+```bash
+npx vitest run tests/upgrade.test.ts tests/profile-state.test.ts \
+  tests/update.test.ts tests/uninstall.test.ts tests/install.test.ts \
+  tests/mcp-recipes.test.ts tests/cli-help.test.ts
+```
+
+It verifies preview/apply upgrade behavior, saved-profile refresh detection, safe
+profile reconciliation, complete-uninstall drift protection, recursively empty target
+recovery, and the separation between model-provider access declarations and service
+credentials. These are disposable automated filesystem tests; they do not prove that
+a native agent consumes the resulting files or that a host scheduler/keychain works.
+
 ## 2. Read-only inventory, ranking, and recommendation track (R; some N)
 
 ```bash

package/docs/README_RESEARCH.md

@@ -0,0 +1,36 @@
+# README redesign research
+
+Research was performed against the current default-branch READMEs on 2026-07-19 and
+recorded at immutable commits so the references remain reproducible.
+
+| Repository | README studied                                                                                                  | Principle adopted                                                            |
+| ---------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Ponytail   | [`16f2980`](https://github.com/DietrichGebert/ponytail/blob/16f29800fd2681bdf24f3eb4ccffe38be3baec6b/README.md) | Give the tool an unmistakable identity and memorable line.                   |
+| uv         | [`1535a67`](https://github.com/astral-sh/uv/blob/1535a6767e5ebd77eac2ace0f6cf1a3edc5f681c/README.md)            | Define the product immediately, then show installation and observable proof. |
+| bat        | [`7895139`](https://github.com/sharkdp/bat/blob/78951393e29bfd2f2a45f4326b9d2bb5e737dd2a/README.md)             | Demonstrate the terminal experience before exhaustive platform detail.       |
+| fzf        | [`b163463`](https://github.com/junegunn/fzf/blob/b163463079e6254b8582b05acefcf187ec160d9b/README.md)            | Use recognizable branding and compact capability statements.                 |
+| ripgrep    | [`227381d`](https://github.com/BurntSushi/ripgrep/blob/227381db0ee83dfa4341f1e27ff9617c0f5ad992/README.md)      | Prefer technical precision, scoped proof, and explicit limitations.          |
+| mise       | [`126e775`](https://github.com/jdx/mise/blob/126e7755cc22e36c3d206b650de613951146b5e3/README.md)                | Pair a concise purpose with a real demo and copyable quickstart.             |
+| Gum        | [`716d8b5`](https://github.com/charmbracelet/gum/blob/716d8b5d0221558f944b5a078dbbcca8572534fb/README.md)       | Teach one complete use case before listing the command surface.              |
+| Starship   | [`8f28dfc`](https://github.com/starship/starship/blob/8f28dfcb1ca3242fba00a3cf98c10ee24605c3ed/README.md)       | Separate prerequisites, installation, and configuration.                     |
+
+## Adopted
+
+- A small original mark and one memorable product line.
+- A proof-first opening with only CI, Node requirement, and license badges.
+- A real terminal transcript that distinguishes preview from mutation.
+- Installation and a disposable first success near the top.
+- Short summaries with direct links to detailed technical evidence.
+- Explicit boundaries beside the claims they qualify.
+
+## Rejected
+
+- Copying another project's mascot, artwork, prose, or layout.
+- Comparative performance charts or speed claims; Loadout has no valid competitor
+  benchmark.
+- Screenshot-led presentation without a real product screenshot.
+- `npm install --global loadout-ai@0.3.2`; that version is not currently published.
+- Claims of universal safety, production readiness, human review, benchmarked sources,
+  or native execution across every configured agent.
+- Badge arrays, star counters, community/sponsor promotion, animations, and exhaustive
+  command or platform tables on the front page.

package/docs/RELEASE_REVIEW.md

@@ -1,8 +1,34 @@
-# Release review — 2026-07-15
-
-This review covers the current Loadout implementation, not an aspirational
-roadmap. It was performed after the transaction, source-fetch, dashboard, and
-adapter test suites passed locally.
+# Release review — historical 2026-07-15 review, updated 2026-07-19
+
+## Current status and evidence boundary
+
+The sections below preserve the evidence recorded for the earlier 0.1.0 review; their
+old package version, catalog count, and test totals are historical and must not be read
+as current 0.3.2 results. The checked-in package is now 0.3.2 with a 50-record catalog.
+
+On 2026-07-19, the focused v0.3.x regression run passed 58 tests covering the unified
+upgrade, saved-profile updates, complete uninstall, separation of model API access from
+service credentials, and recursively empty skill-directory recovery. The later
+`npm run verify:full` result is bound to exact tested commit
+`8f8eccdd20272ebb88d0339087fc9cd3828e65c9`: its deterministic evidence gate, 552 tests
+with one explicit skip, both CLI product journeys, package smoke, the 1,000-skill
+performance gate, and two Playwright dashboard projects passed. The evidence-only
+follow-up commit that records this statement was not represented as part of that tested
+commit. These local results establish the tested repository behaviors only; they do not
+retroactively establish native-agent recognition, current npm publication, branch
+protection, or an independent security review.
+
+The separate [sanitized live-check report](./evidence/live-checks-2026-07-19.json) was
+generated at `2026-07-19T13:45:14.945Z` and records the same repository commit
+`8f8eccdd20272ebb88d0339087fc9cd3828e65c9` as the deterministic run above. At that
+historical observation time, the pinned Stable install and rollback were verified; npm
+returned 404 for `loadout-ai@0.3.2`; and authenticated GitHub access reached the
+repository but branch protection for `main` returned 404. These results can change
+after the timestamp and are not part of the deterministic offline gate.
+
+At the time it was written, this review covered the then-current Loadout
+implementation, not an aspirational roadmap. It was performed after the transaction,
+source-fetch, dashboard, and adapter test suites passed locally.
 
 ## P4-08: atomic-commit review — accepted with explicit durability boundary