loadout-ai 0.2.2 → 0.3.1

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/shared/schemas.js

@@ -304,6 +304,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

package/docs/TESTING.md

@@ -199,8 +199,20 @@ write to the detected real agent profiles. After npm publication, replace `npx .
 
 ## 8. Test credential-gated MCP configuration without exposing a key
 
-The Playwright recipe has no service credential. The GitHub read-only recipe does and
-must refuse `--yes` until its declared environment reference resolves:
+List the reviewed recipes that need no separately billed AI/model API key:
+
+```bash
+npx . mcp-recipe --no-key
+```
+
+This includes Playwright, Chrome DevTools, and GitHub read-only. The first two have no
+service credential. GitHub read-only needs a GitHub token and must refuse `--yes`
+until its declared environment reference resolves. Use `--credential-free` for the
+stricter zero-credential list:
+
+```bash
+npx . mcp-recipe --credential-free
+```
 
 ```bash
 npx . mcp-recipe github-readonly --config "$TEST_HOME/mcp.json" --yes
@@ -230,3 +242,14 @@ npx . dashboard
 Open the printed loopback URL. CLI setup, updates, removal, discovery, and rollback all
 work without it. Browser automation is also optional and runs only when manually
 dispatched in CI; locally, use `npm run test:e2e:dashboard`.
+
+## Final cleanup test
+
+```bash
+npx . uninstall
+npx . uninstall --yes
+```
+
+The first command is a dry run. The second removes only Loadout-managed agent files,
+runtime tools, native jobs, state, snapshots, and cache; it leaves the locally invoked
+package itself alone. Use `--remove-cli` only when testing a global npm install.

package/docs/USER_TEST_GUIDE.md

@@ -0,0 +1,176 @@
+# Test Loadout on your own machine
+
+This is the short, safe route through the product. Start in a normal terminal.
+The first group only reads local state or prepares a preview; it does not replace
+agent files. A preview can download reviewed source into Loadout's cache, but it
+does not activate skills or change an agent configuration.
+
+## 1. Get oriented
+
+```bash
+loadout guide
+loadout library
+loadout scan
+loadout health
+```
+
+`library` is the concise provenance view: it shows active skills and disabled
+reviewed-library copies per agent. For the full source-package and upstream-repository
+record for every skill, use `loadout library --all`. `scan` distinguishes
+Loadout-managed skills from your own pre-existing skills. `health` checks local drift only; add
+`--updates` only when you want it to contact the tracked public repositories.
+
+## 2. Explore without installing
+
+```bash
+loadout catalog --json
+loadout candidate list --limit 10
+loadout recommend --project .
+loadout optimize --project .
+loadout tool
+loadout tool graphify
+```
+
+Run the project commands from the project you care about, or replace `.` with its
+absolute path. `optimize` is still a preview until `--yes` is supplied. `tool
+graphify` is also a preview; Graphify is a reviewed runtime tool and does not
+need an OpenAI or Anthropic API key for its code-only install.
+
+## 3. Open the optional dashboard
+
+```bash
+loadout dashboard
+```
+
+Open the `http://127.0.0.1:PORT` address it prints. It never listens on the
+network. The dashboard shows status, health, installed packages, updates, local
+project recommendations, profiles, and the catalog. Its Apply and Undo buttons
+require an in-page preview, acknowledgement, and a private local session token.
+Stop the server with `Control-C`.
+
+## 4. Preview and install a profile
+
+Use this order. Each setup command previews first; interactive setup asks for
+confirmation before changing files. A mutation creates a snapshot first.
+
+```bash
+# Recommended everyday skills
+loadout setup --mode stable --agents codex,claude-code
+
+# Broader daily-use selection (50 curated skill directories)
+loadout setup --mode power --agents codex,claude-code
+
+# Download the broad reviewed library while keeping the active set controlled
+loadout setup --mode maximum --agents codex,claude-code
+```
+
+At the API-access question, choose `None` unless you separately pay for a
+provider API. A ChatGPT Plus or Claude Pro subscription is not an API key. Core
+skill profiles do not require one; credentialed MCP and runtime operations stay
+explicit.
+
+For unattended use only after reviewing a preview, the equivalent is:
+
+```bash
+loadout setup --mode stable --agents codex,claude-code --yes
+```
+
+Do not add `--approve-risk` unless the displayed preview identifies a specific
+reviewed finding and you understand it.
+
+## 5. Test a change and recover
+
+```bash
+# Preview Graphify, then install only if the preview looks right
+loadout tool graphify --agents codex,claude-code
+loadout tool graphify --agents codex,claude-code --yes --approve-risk
+
+# Check the exact current state
+loadout library
+loadout health
+
+# Restore a prior snapshot if you do not like the result
+loadout rollback --list
+loadout rollback
+
+# Or remove only Graphify and restore its pre-install agent state
+loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
+```
+
+`rollback` restores a whole Loadout snapshot. The tool-specific remove command
+is narrower and is preferable when you only want to undo that one runtime tool.
+
+## 6. Test daily discovery and updates
+
+```bash
+loadout alerts
+loadout update
+loadout update --package superpowers
+loadout autopilot
+```
+
+`update --package` checks only the named tracked package. The default is a
+read-only diff and safety plan. Apply only after review:
+
+```bash
+loadout update --package superpowers --apply
+loadout update --yes
+```
+
+`autopilot` previews two native daily read-only jobs (updates and discovery).
+Enable or remove both explicitly:
+
+```bash
+loadout autopilot --time 09:00 --yes
+loadout autopilot --remove --yes
+```
+
+The daily update job re-evaluates your saved Stable, Power, or Maximum profile and
+checks every managed package, but never supplies `--yes`. Daily discovery can add
+interesting repositories to the review queue; it cannot silently promote or install
+them.
+
+## 7. Test MCP choices without a model API key
+
+```bash
+loadout mcp-recipe --no-key
+```
+
+Expect Playwright MCP, Chrome DevTools MCP, and GitHub read-only. None requires a
+separately billed AI/model API key. GitHub read-only still discloses that it needs a
+GitHub token; use `loadout mcp-recipe --credential-free` to exclude every service
+credential too. Browser configuration and real connection testing remain explicit.
+Graphify is a separate runtime tool, not an MCP server.
+
+## 8. Preview complete cleanup
+
+```bash
+loadout uninstall
+```
+
+Read the package, runtime, scheduler, and state summary. The preview changes nothing.
+At the very end of testing, remove all Loadout-managed data while keeping the CLI:
+
+```bash
+loadout uninstall --yes
+```
+
+To remove the npm command too, use `loadout uninstall --yes --remove-cli`. Complete
+cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle test.
+
+## 9. Advanced surface
+
+The first help screen deliberately focuses on daily use. Existing advanced
+commands have not been removed:
+
+```bash
+loadout advanced
+loadout candidate --help
+loadout mcp-recipe --help
+loadout <command> --help
+```
+
+Avoid running registry publishing, signing, sandbox, credential, or arbitrary
+MCP configuration commands on your main profile as part of routine user testing.
+They are package-author or integration workflows, not required to use Loadout's
+core product.

package/docs/plans/2026-07-18-release-0.3.md

@@ -0,0 +1,42 @@
+# Loadout 0.3 Product-Hardening Plan
+
+## Goal
+
+Ship a user-testable CLI release with one-command cleanup, honest whole-profile update
+checks, explicit no-key MCP discovery, and a verified local dashboard.
+
+## Public contracts
+
+1. `loadout uninstall` is a preview. `loadout uninstall --yes` removes scheduled
+   Loadout jobs, runtime tools, managed agent files, disabled library copies, cache,
+   snapshots, and state while preserving unmanaged or modified files. `--remove-cli`
+   additionally runs the global npm uninstall.
+2. `loadout update` checks every tracked package and compares the last installed
+   Stable/Power/Maximum profile with the current trusted catalog. It never mutates by
+   default.
+3. `loadout update --yes` reapplies trusted profile changes and applies all
+   statically-safe active package updates; blocked, disabled, or failed updates are
+   reported and skipped. `--package <id> --yes` remains the precise path.
+4. Stable, Power, and Maximum are re-evaluated against the trusted catalog whenever
+   `update` runs. Discovery can nominate new candidates daily, but candidates cannot
+   enter a profile until immutable source, license, compatibility, and safety review
+   are recorded.
+5. `loadout mcp-recipe --no-key` lists reviewed recipes requiring no separately
+   billed AI/model API key. It includes GitHub read-only while separately disclosing
+   the GitHub token. `--credential-free` is the stricter zero-credential filter.
+6. `loadout dashboard` remains loopback-only and is verified by the browser E2E test.
+
+## Implementation sequence
+
+- [x] Add failing tests for uninstall preview/application and CLI help.
+- [x] Implement uninstall orchestration with dependency injection and path guards.
+- [x] Add failing tests for persisted profile state and profile drift reporting.
+- [x] Record setup mode in snapshot-restorable install state and include it in update.
+- [x] Add failing tests for bulk safe update selection and clear skipped results.
+- [x] Implement `update --yes`, retaining `--apply` as a compatible alias.
+- [x] Add and test Chrome DevTools as a pinned no-key MCP recipe.
+- [x] Add `mcp-recipe --no-key` and beginner-readable recipe output.
+- [x] Update README, test guide, master plan, changelog, completion, and version.
+- [ ] Run unit, lint, type, evidence, package, CLI E2E, performance, dashboard E2E,
+      and npm dry-run gates.
+- [ ] Review, commit, merge to main, push, tag, and publish to npm.

package/docs/superpowers/plans/2026-07-18-cli-ux-polish.md

@@ -0,0 +1,86 @@
+# CLI UX Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Loadout's everyday CLI path understandable for a first-time user while preserving its existing safe, advanced capabilities.
+
+**Architecture:** Keep the CLI as the primary interface. Add one concise, read-only `guide` command and a focused help footer; retain advanced commands but remove them from the first-screen help. Fix JSON output and package-scoped update previews as explicit public CLI contracts. Document a safe test journey and keep the dashboard as an optional local companion.
+
+**Tech Stack:** Node.js 20+, TypeScript, Commander, Vitest, framework-free local dashboard.
+
+## Global Constraints
+
+- Never mutate a user's agent configuration from a default or preview command.
+- Existing command names remain valid even if hidden from first-screen help.
+- Machine-readable commands must emit valid JSON when `--json` is accepted.
+- Do not require an API key or GitHub account for the core test journey.
+- Every behavior change gets a test before its production code.
+
+---
+
+### Task 1: Define the beginner CLI contract
+
+**Files:**
+
+- Modify: `tests/cli-help.test.ts`
+- Modify: `src/cli.ts`
+
+**Interfaces:**
+
+- Produces: `loadout guide`, a read-only command that explains setup, discovery, project recommendations, recovery, dashboard, and help.
+
+- [x] **Step 1: Write failing CLI contract tests** for `loadout guide`, a focused top-level help footer, and retained access to an advanced command.
+- [x] **Step 2: Run** `npm test -- tests/cli-help.test.ts` **and confirm the new assertions fail.**
+- [x] **Step 3: Implement** `guide`, hide maintainer-only commands from first-screen help, and add a short help footer that points to the guide.
+- [x] **Step 4: Run** `npm test -- tests/cli-help.test.ts` **and confirm it passes.**
+- [ ] **Step 5: Commit** the focused CLI discoverability change.
+
+### Task 2: Repair machine-readable and scoped preview contracts
+
+**Files:**
+
+- Modify: `tests/cli-help.test.ts`
+- Modify: `tests/update.test.ts`
+- Modify: `src/cli.ts`
+- Modify: `src/core/update.ts`
+
+**Interfaces:**
+
+- `loadout catalog --json` returns a JSON array.
+- `loadout update --package <id>` plans only that managed package and rejects an unknown installed package clearly.
+
+- [x] **Step 1: Write failing tests** for catalog JSON and package-scoped update planning.
+- [x] **Step 2: Run the focused test files** and confirm the assertions fail for the existing implementation.
+- [x] **Step 3: Implement the smallest compatible fixes.**
+- [x] **Step 4: Run the focused tests** and confirm they pass.
+- [ ] **Step 5: Commit** the contract fixes separately.
+
+### Task 3: Record user testing and current product scope
+
+**Files:**
+
+- Create: `docs/USER_TEST_GUIDE.md`
+- Modify: `MASTER_PLAN.md`
+
+**Interfaces:**
+
+- The guide gives a real-profile-safe order of commands, says which commands change state, and gives rollback instructions.
+- `MASTER_PLAN.md` begins with the one authoritative unfinished-work section and moves stale immediate tasks out of the active path.
+
+- [x] **Step 1: Add a concise user testing guide** for daily use, discovery, optional dashboard, safe mutation, rollback, and advanced validation.
+- [x] **Step 2: Add the current remaining work section** and mark historic, non-essential ideas as deferred rather than pretending they are active product requirements.
+- [x] **Step 3: Run markdown and CLI smoke checks** to make sure command names match the real surface.
+- [ ] **Step 4: Commit** documentation separately.
+
+### Task 4: Validate the actual user journey
+
+**Files:**
+
+- Test: `tests/cli-help.test.ts`
+- Test: `tests/update.test.ts`
+- Test: `tests/dashboard.test.ts`
+
+- [x] **Step 1: Build and run** the CLI guide, catalog JSON, health, library, project recommendation preview, and dashboard endpoint checks without changing agent files.
+- [ ] **Step 2: Run** `npm run verify:full` **and inspect every failure if any.**
+- [ ] **Step 3: Review the diff for accidental profile/cache/secrets changes.**
+- [ ] **Step 4: Commit, then present the exact install/test/recovery commands to the user.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",