loadout-ai 0.2.2 → 0.3.1

package/dist/src/core/cli-guide.js

@@ -0,0 +1,101 @@
+/** Plain-language entry points for people using the CLI, not maintaining it. */
+export const BEGINNER_GUIDE = `
+START HERE
+
+1. See what Loadout currently manages
+   loadout library
+
+2. Preview the recommended everyday setup
+   loadout setup --mode stable
+
+3. Find additions that fit the project in this folder
+   loadout recommend --project .
+   loadout optimize --project .
+
+4. Check for safer updates and new discoveries
+   loadout health
+   loadout alerts
+   loadout candidate list --limit 10
+
+5. If you want a visual view, start the private local dashboard
+   loadout dashboard
+
+If you decide to install something, Loadout shows a preview first and creates a
+snapshot before changing managed files. Recover with: loadout rollback
+
+Nothing above changes your agents. For the full maintainer/tooling surface, run:
+loadout advanced
+`.trim();
+export const ADVANCED_GUIDE = [
+    "ADVANCED COMMANDS",
+    "",
+    "These remain available, but are hidden from the first screen so daily use stays simple.",
+    "",
+    "Discovery and evidence: candidate, discover, review-queue, intelligence, compatibility, benchmark.",
+    "Packages and sharing: init, add, sync, lock, export, import, audit, create, pack, publish, registry-serve.",
+    "Integrations and safety: mcp-recipe, mcp-config, codex-mcp-config, credentials, models, sandbox-run, canary.",
+    "Automation and release: watch, schedule, unschedule, catalog-sign, catalog-verify, catalog-update, claims.",
+    "",
+    "Use `loadout <command> --help` for exact options. Every mutation-capable command previews first or requires --yes.",
+].join("\n");
+/** Commands retained for specialist workflows but omitted from beginner help. */
+export const HIDDEN_FROM_FIRST_SCREEN = new Set([
+    "init",
+    "lock",
+    "export",
+    "import",
+    "audit",
+    "create",
+    "pack",
+    "publish",
+    "registry-serve",
+    "search",
+    "report",
+    "outcomes",
+    "outcome",
+    "share",
+    "card",
+    "compare-loadouts",
+    "badge",
+    "claims",
+    "alert-ignore",
+    "alert-pin",
+    "alert-unpin",
+    "alert-pins",
+    "improve",
+    "improve-feedback",
+    "adopt",
+    "intelligence",
+    "compatibility",
+    "skill-audit",
+    "interop",
+    "benchmark",
+    "capabilities",
+    "candidate",
+    "catalog-update",
+    "discover",
+    "review-queue",
+    "review",
+    "credentials",
+    "models",
+    "keygen",
+    "catalog-sign",
+    "catalog-verify",
+    "completion",
+    "mcp-recipe",
+    "mcp",
+    "inspect",
+    "evaluate",
+    "head-to-head",
+    "watch",
+    "schedule",
+    "unschedule",
+    "sandbox-run",
+    "mcp-config",
+    "codex-mcp-config",
+    "plan",
+    "install",
+    "convert",
+    "canary",
+    "serve",
+]);

package/dist/src/core/completion.js

@@ -1,4 +1,6 @@
 const commands = [
+    "guide",
+    "advanced",
     "setup",
     "upgrade",
     "init",
@@ -83,6 +85,7 @@ const commands = [
     "outcome",
     "outcomes",
     "remove",
+    "uninstall",
     "dashboard",
     "serve",
     "completion",

package/dist/src/core/mcp-recipes.js

@@ -16,6 +16,7 @@ export const REVIEWED_MCP_RECIPES = [
         command: "npx",
         args: ["-y", "@playwright/mcp@0.0.78"],
         environment: [],
+        modelApiProviders: [],
         fixedEnvironment: {},
         permissions: [
             "browser automation",
@@ -26,6 +27,25 @@ export const REVIEWED_MCP_RECIPES = [
         reviewedAt: "2026-07-16T00:00:00Z",
         artifact: "npm:@playwright/mcp@0.0.78#sha512-XLTUeA6mEN9sQ+hJ4dfG8EIkDbxS0K3Trc2RBkUJuf02TgE2FQRNTMtq/aJfhyRMINsRl/Ybc4sxcWLtFn4/TQ==",
     },
+    {
+        id: "chrome-devtools",
+        displayName: "Chrome DevTools MCP",
+        source: "https://github.com/ChromeDevTools/chrome-devtools-mcp/tree/f621d0052fd241dca76e7f615b20e9d320ba965f",
+        serverName: "chrome-devtools",
+        command: "npx",
+        args: ["-y", "chrome-devtools-mcp@1.6.0"],
+        environment: [],
+        modelApiProviders: [],
+        fixedEnvironment: {},
+        permissions: [
+            "control a local Chrome browser",
+            "inspect pages, network activity, performance, and console output",
+        ],
+        connection: "stdio",
+        reviewedCommit: "f621d0052fd241dca76e7f615b20e9d320ba965f",
+        reviewedAt: "2026-07-18T00:00:00Z",
+        artifact: "npm:chrome-devtools-mcp@1.6.0#sha512-VZX6f/OjQSYhy2BGGRs+y3LsrsAQAz/HwZCWKBLVyST/4r/3zjVEjjVW7gMCVbRDuspnVdcp5hQDPrQ5UFrdZw==",
+    },
     {
         id: "github-readonly",
         displayName: "GitHub MCP Server (read-only)",
@@ -43,6 +63,7 @@ export const REVIEWED_MCP_RECIPES = [
             "ghcr.io/github/github-mcp-server@sha256:7b1384cdd6d025c09256af2fb6cb79bc5e87aedc957c8826b5e50d8cb82f0be3",
         ],
         environment: ["GITHUB_PERSONAL_ACCESS_TOKEN"],
+        modelApiProviders: [],
         fixedEnvironment: { GITHUB_READ_ONLY: "1" },
         permissions: ["read GitHub repositories, issues, pull requests, and users"],
         connection: "stdio",

package/dist/src/core/profile-state.js

@@ -0,0 +1,101 @@
+import { resolveCatalogProfile } from "./profiles.js";
+import { readInstallState, writeInstallState } from "./state.js";
+export async function recordInstalledProfile(prepared) {
+    const profile = {
+        mode: prepared.selection.mode,
+        ...(prepared.selection.packageIds
+            ? { packageIds: [...prepared.selection.packageIds] }
+            : {}),
+        agents: prepared.agents.map((agent) => agent.id),
+        catalogPackages: prepared.resolution.packages
+            .filter((pkg) => pkg.components?.includes("skill"))
+            .map((pkg) => ({
+            packageId: pkg.id,
+            ...(pkg.source?.commit ? { reviewedCommit: pkg.source.commit } : {}),
+        })),
+        appliedAt: new Date().toISOString(),
+    };
+    const state = await readInstallState();
+    await writeInstallState({ ...state, profile });
+    return profile;
+}
+export function evaluateInstalledProfileState(state, catalog) {
+    const evaluatedAt = new Date().toISOString();
+    const boundary = "Checks the current signed/reviewed catalog. Newly discovered candidates stay recommendations until review evidence promotes them.";
+    if (!state.profile)
+        return {
+            installed: false,
+            expectedPackages: [],
+            missingPackages: [],
+            reviewedRevisionChanges: [],
+            needsRefresh: false,
+            evaluatedAt,
+            boundary,
+        };
+    const resolution = resolveCatalogProfile(catalog, {
+        mode: state.profile.mode,
+        ...(state.profile.packageIds
+            ? { packageIds: state.profile.packageIds }
+            : {}),
+    });
+    const expected = resolution.packages.filter((pkg) => pkg.components?.includes("skill"));
+    const installed = new Map(state.installs.map((record) => [record.packageId, record]));
+    const previousCatalog = new Map(state.profile.catalogPackages.map((record) => [record.packageId, record]));
+    const missingPackages = expected
+        .filter((pkg) => !installed.has(pkg.id))
+        .map((pkg) => pkg.id);
+    const reviewedRevisionChanges = expected.flatMap((pkg) => {
+        const previous = previousCatalog.get(pkg.id);
+        if (!previous ||
+            !pkg.source?.commit ||
+            previous.reviewedCommit?.toLowerCase() === pkg.source.commit.toLowerCase())
+            return [];
+        return [
+            {
+                packageId: pkg.id,
+                previousReviewedCommit: previous.reviewedCommit,
+                reviewedCommit: pkg.source.commit,
+            },
+        ];
+    });
+    const oldIds = state.profile.catalogPackages
+        .map((item) => item.packageId)
+        .sort();
+    const expectedPackages = expected.map((pkg) => pkg.id).sort();
+    const selectionChanged = oldIds.join("\0") !== expectedPackages.join("\0");
+    return {
+        installed: true,
+        mode: state.profile.mode,
+        appliedAt: state.profile.appliedAt,
+        expectedPackages,
+        missingPackages,
+        reviewedRevisionChanges,
+        needsRefresh: selectionChanged ||
+            missingPackages.length > 0 ||
+            reviewedRevisionChanges.length > 0,
+        evaluatedAt,
+        boundary,
+    };
+}
+export async function evaluateInstalledProfile(catalog) {
+    return evaluateInstalledProfileState(await readInstallState(), catalog);
+}
+export function formatInstalledProfileStatus(status) {
+    if (!status.installed)
+        return "PROFILE No saved Stable, Power, Maximum, or Custom profile yet.";
+    return [
+        `PROFILE ${status.mode?.toUpperCase()}: ${status.needsRefresh ? "reviewed changes available" : "current against reviewed catalog"}`,
+        `Expected repositories: ${status.expectedPackages.length}`,
+        ...(status.missingPackages.length
+            ? [`Missing: ${status.missingPackages.join(", ")}`]
+            : []),
+        ...(status.reviewedRevisionChanges.length
+            ? [
+                `Reviewed revisions changed: ${status.reviewedRevisionChanges
+                    .map((item) => item.packageId)
+                    .join(", ")}`,
+            ]
+            : []),
+        `Trust boundary: ${status.boundary}`,
+    ].join("\n");
+}

package/dist/src/core/remove.js

@@ -4,10 +4,12 @@ import { forgetInstall, installStatePath, readInstallState } from "./state.js";
 import { writeMcpConfigPlan } from "./mcp.js";
 import { runMutationTransaction } from "./transaction.js";
 export async function planRemove(packageId) {
-    const record = (await readInstallState()).installs.find((entry) => entry.packageId === packageId);
-    if (!record)
+    const state = await readInstallState();
+    const record = state.installs.find((entry) => entry.packageId === packageId);
+    const trackedMcp = (state.mcpInstalls ?? []).filter((entry) => entry.packageId === packageId);
+    if (!record && !trackedMcp.length)
         throw new Error(`Package is not managed by Loadout: ${packageId}`);
-    const files = await Promise.all(record.files.map(async (file) => {
+    const files = await Promise.all((record?.files ?? []).map(async (file) => {
         try {
             const digest = createHash("sha256")
                 .update(await readFile(file.path))
@@ -24,10 +26,7 @@ export async function planRemove(packageId) {
         }
     }));
     const modified = files.filter((file) => file.status === "modified");
-    const state = await readInstallState();
-    const mcpServers = await Promise.all((state.mcpInstalls ?? [])
-        .filter((entry) => entry.packageId === packageId)
-        .map(async (entry) => {
+    const mcpServers = await Promise.all(trackedMcp.map(async (entry) => {
         try {
             const config = JSON.parse(await readFile(entry.configPath, "utf8"));
             if (!config.mcpServers || !(entry.serverName in config.mcpServers))

package/dist/src/core/runtime-tool-recipe.js

@@ -118,7 +118,14 @@ const generatedFilesSchema = z
         .object({
         fileExtension: z.string().regex(/^\.[A-Za-z0-9]+$/),
         from: nonControlTextSchema,
-        to: nonControlTextSchema.refine((value) => !/[{}]/u.test(value.replaceAll("{artifactRequirement}", "")), "unknown rewrite template variable"),
+        to: nonControlTextSchema.refine((value) => {
+            const rendered = [
+                "{artifactRequirement}",
+                "{artifactUrl}",
+                "{artifactSha256}",
+            ].reduce((current, placeholder) => current.replaceAll(placeholder, ""), value);
+            return !/[{}]/u.test(rendered);
+        }, "unknown rewrite template variable"),
         mustEliminate: z.boolean(),
     })
         .strict()),
@@ -306,6 +313,8 @@ export function runtimeArtifactRequirement(recipe) {
 export function renderRuntimeRecipeValue(value, recipe) {
     return value
         .replaceAll("{artifactRequirement}", runtimeArtifactRequirement(recipe))
+        .replaceAll("{artifactUrl}", recipe.artifactUrl)
+        .replaceAll("{artifactSha256}", recipe.artifactSha256)
         .replaceAll("{version}", recipe.version);
 }
 /** Resolve reviewed path segments without ever accepting a recipe-owned root. */

package/dist/src/core/runtime-tools.js

@@ -162,6 +162,24 @@ export const GRAPHIFY_RECIPE = deepFreeze(parseRuntimeToolRecipe({
                 to: "--from '{artifactRequirement}'",
                 mustEliminate: true,
             },
+            {
+                fileExtension: ".md",
+                from: "install --upgrade graphifyy",
+                to: "install '{artifactRequirement}' --exclude-newer 2026-07-17T00:00:00Z",
+                mustEliminate: true,
+            },
+            {
+                fileExtension: ".md",
+                from: "pip install graphifyy",
+                to: "pip install '{artifactRequirement}'",
+                mustEliminate: true,
+            },
+            {
+                fileExtension: ".md",
+                from: "pip install 'graphifyy[gemini]'",
+                to: "pip install 'graphifyy[gemini] @ {artifactUrl}#sha256={artifactSha256}'",
+                mustEliminate: true,
+            },
         ],
     },
     guarantees: [
@@ -169,7 +187,7 @@ export const GRAPHIFY_RECIPE = deepFreeze(parseRuntimeToolRecipe({
         "exact top-level wheel URL and SHA-256; dependency uploads bounded by the reviewed cutoff",
         "no API keys or provider credentials inherited by installer subprocesses",
         "agent skill targets and isolated runtime are snapshotted for rollback/removal",
-        "generated runtime lookup is rewritten to the same pinned Graphify artifact",
+        "generated top-level Graphify lookups and repair commands are rewritten to the same pinned artifact",
     ],
 }));
 export const REVIEWED_RUNTIME_TOOLS = [GRAPHIFY_RECIPE];
@@ -199,6 +217,11 @@ async function readState(stateHome) {
         throw error;
     }
 }
+/** Return runtime tools currently installed and owned by Loadout. */
+export async function listInstalledRuntimeTools(stateHome = loadoutHome()) {
+    const state = await readState(stateHome);
+    return Object.keys(state.tools).sort();
+}
 async function writeState(state, stateHome) {
     await writeFileAtomically(statePath(stateHome), `${JSON.stringify(state, null, 2)}\n`);
 }

package/dist/src/core/scheduler.js

@@ -41,7 +41,7 @@ export function planNativeScheduler(action, options = {}) {
     const job = options.job ?? "updates";
     const nativeId = `loadout-daily-${job}`;
     const command = job === "updates"
-        ? [...launcher, "watch", "--once", "--json"]
+        ? [...launcher, "update", "--json"]
         : [...launcher, "discover", "--source", "all", "--queue", "--json"];
     if (selectedPlatform === "darwin") {
         const label = `com.loadout.daily.${job}`;
@@ -259,6 +259,6 @@ export function formatNativeScheduler(plan) {
         `Command: ${plan.command.join(" ")}`,
         ...plan.files.map((file) => `File: ${file.path}`),
         ...plan.applyCommands.map((item) => `Native action: ${item.command} ${item.args.join(" ")}`),
-        `Guarantee: the scheduled command is ${plan.command.slice(2).join(" ")}; it can only report updates or queue candidates and cannot apply changes.`,
+        `Guarantee: no --yes flag is scheduled; this job can only report updates or queue candidates and cannot apply changes.`,
     ].join("\n");
 }

package/dist/src/core/snapshot.js

@@ -205,6 +205,19 @@ export function validateSnapshot(value) {
     return value;
 }
 function isCanonicalBase64(value) {
-    return (value.length % 4 === 0 &&
-        /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value));
+    if (value.length % 4 !== 0)
+        return false;
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    const contentLength = value.length - padding;
+    for (let index = 0; index < contentLength; index += 1) {
+        const code = value.charCodeAt(index);
+        const valid = (code >= 65 && code <= 90) ||
+            (code >= 97 && code <= 122) ||
+            (code >= 48 && code <= 57) ||
+            code === 43 ||
+            code === 47;
+        if (!valid)
+            return false;
+    }
+    return value.slice(contentLength) === "=".repeat(padding);
 }

package/dist/src/core/state.js

@@ -298,12 +298,15 @@ export async function recordInstallTransaction(entries, mcpEntries, snapshotId)
 export async function forgetInstall(packageId) {
     const state = await readInstallState();
     const installs = state.installs.filter((entry) => entry.packageId !== packageId);
-    if (installs.length === state.installs.length)
+    const mcpInstalls = (state.mcpInstalls ?? []).filter((entry) => entry.packageId !== packageId);
+    if (installs.length === state.installs.length &&
+        mcpInstalls.length === (state.mcpInstalls ?? []).length)
         throw new Error(`Package is not managed by Loadout: ${packageId}`);
     await writeInstallState({
         version: 1,
         installs,
-        mcpInstalls: (state.mcpInstalls ?? []).filter((entry) => entry.packageId !== packageId),
+        ...(state.profile ? { profile: state.profile } : {}),
+        mcpInstalls,
         activations: (state.activations ?? []).map((entry) => entry.packageId === packageId
             ? {
                 ...entry,

package/dist/src/core/uninstall.js

@@ -0,0 +1,109 @@
+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 {
+            if ((await readdir(directory)).length === 0)
+                await rmdir(directory);
+        }
+        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");
+}