loadout-ai 0.7.0 → 0.9.0

package/dist/src/core/reporting/completion.js

@@ -1,139 +1,91 @@
-const commands = [
-    "guide",
-    "advanced",
-    "setup",
-    "upgrade",
-    "init",
-    "lock",
-    "export",
-    "import",
-    "audit",
-    "create",
-    "pack",
-    "publish",
-    "search",
-    "add",
-    "unadd",
-    "list",
-    "scan",
-    "reconcile",
-    "status",
-    "versions",
-    "skill-audit",
-    "doctor",
-    "health",
-    "compare",
-    "optimize",
-    "activate",
-    "enable",
-    "disable",
-    "adopt",
-    "library",
-    "update",
-    "rollback",
-    "discover",
-    "candidate",
-    "review-queue",
-    "review",
-    "alerts",
-    "alert-ignore",
-    "alert-pin",
-    "alert-unpin",
-    "alert-pins",
-    "mcp",
-    "mcp-recipe",
-    "mcp-config",
-    "models",
-    "credentials",
-    "schedule",
-    "unschedule",
-    "autopilot",
-    "tool",
-    "report",
-    "share",
-    "card",
-    "compare-loadouts",
-    "badge",
-    "inspect",
-    "evaluate",
-    "watch",
-    "sandbox-run",
-    "codex-mcp-config",
-    "plan",
-    "install",
-    "convert",
-    "canary",
-    "capabilities",
-    "catalog",
-    "profiles",
-    "recommend",
-    "improve",
-    "improve-feedback",
-    "sync",
-    "outcome",
-    "outcomes",
-    "remove",
-    "uninstall",
-    "serve",
-    "completion",
-];
-const modelCommands = ["status", "set", "verify"];
-const credentialCommands = ["status", "set", "check", "delete"];
-const candidateCommands = ["list", "inspect", "propose"];
+let registry = [];
+/** Called once at startup with the assembled program. */
+export function registerCompletionCommands(tree) {
+    registry = tree
+        .filter((entry) => entry.name && entry.name !== "help")
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function completionCommands() {
+    return registry.map((entry) => entry.name);
+}
+export function completionSubcommands(name) {
+    return registry.find((entry) => entry.name === name)?.subcommands ?? [];
+}
+/** Every executable top-level and parent/child command path. */
+export function completionCommandPaths() {
+    return registry.flatMap((entry) => [
+        entry.name,
+        ...entry.subcommands.map((subcommand) => `${entry.name} ${subcommand}`),
+    ]);
+}
 export function renderShellCompletion(shell) {
-    const words = commands.join(" ");
+    const words = completionCommands().join(" ");
+    const parents = registry.filter((entry) => entry.subcommands.length > 0);
     switch (shell) {
-        case "bash":
+        case "bash": {
+            const bashCases = parents
+                .map((entry) => `      "${entry.name}") candidates="${entry.subcommands.join(" ")}" ;;`)
+                .join("\n");
             return `# Loadout command completion
 _loadout() {
   local current="\${COMP_WORDS[COMP_CWORD]}"
   local commands="${words}"
+  local candidates=""
   if [[ COMP_CWORD -eq 1 ]]; then
-    COMPREPLY=( $(compgen -W "$commands" -- "$current") )
-  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "models" ]]; then
-    COMPREPLY=( $(compgen -W "${modelCommands.join(" ")}" -- "$current") )
-  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "credentials" ]]; then
-    COMPREPLY=( $(compgen -W "${credentialCommands.join(" ")}" -- "$current") )
-  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "candidate" ]]; then
-    COMPREPLY=( $(compgen -W "${candidateCommands.join(" ")}" -- "$current") )
+    candidates="$commands"
+  elif [[ COMP_CWORD -eq 2 ]]; then
+    case "\${COMP_WORDS[1]}" in
+${bashCases}
+    esac
   fi
+  COMPREPLY=( $(compgen -W "$candidates" -- "$current") )
 }
 complete -F _loadout loadout
 `;
-        case "zsh":
+        }
+        case "zsh": {
+            const zshCases = parents
+                .map((entry) => `    '${entry.name}') _values '${entry.name} command' ${entry.subcommands.map((command) => `'${command}'`).join(" ")} ;;`)
+                .join("\n");
             return `#compdef loadout
-typeset -a commands model_commands credential_commands candidate_commands
-commands=(${commands.map((command) => `'${command}'`).join(" ")})
-model_commands=(${modelCommands.map((command) => `'${command}'`).join(" ")})
-credential_commands=(${credentialCommands.map((command) => `'${command}'`).join(" ")})
-candidate_commands=(${candidateCommands.map((command) => `'${command}'`).join(" ")})
+typeset -a commands
+commands=(${completionCommands()
+                .map((command) => `'${command}'`)
+                .join(" ")})
 if (( CURRENT == 2 )); then
   _describe 'command' commands
-elif (( CURRENT == 3 )) && [[ $words[2] == models ]]; then
-  _describe 'models command' model_commands
-elif (( CURRENT == 3 )) && [[ $words[2] == credentials ]]; then
-  _describe 'credentials command' credential_commands
-elif (( CURRENT == 3 )) && [[ $words[2] == candidate ]]; then
-  _describe 'candidate command' candidate_commands
+elif (( CURRENT == 3 )); then
+  case $words[2] in
+${zshCases}
+  esac
 fi
 `;
+        }
         case "fish":
             return [
-                ...commands.map((command) => `complete -c loadout -f -n '__fish_use_subcommand' -a ${command}`),
-                ...modelCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from models' -a ${command}`),
-                ...credentialCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from credentials' -a ${command}`),
-                ...candidateCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from candidate' -a ${command}`),
+                ...completionCommands().map((command) => `complete -c loadout -f -n '__fish_use_subcommand' -a ${command}`),
+                ...parents.flatMap((entry) => entry.subcommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from ${entry.name}' -a ${command}`)),
             ]
                 .join("\n")
                 .concat("\n");
-        case "powershell":
+        case "powershell": {
+            const powershellCases = parents
+                .map((entry, index) => `${index === 0 ? "if" : "elseif"} ($elements.Count -ge 2 -and $elements[1] -eq '${entry.name}') { @(${entry.subcommands.map((command) => `'${command}'`).join(", ")}) }`)
+                .join(" ");
+            const topLevel = `@(${completionCommands()
+                .map((command) => `'${command}'`)
+                .join(", ")})`;
+            const powershellCandidates = powershellCases
+                ? `${powershellCases} else { ${topLevel} }`
+                : topLevel;
             return `Register-ArgumentCompleter -Native -CommandName loadout -ScriptBlock {
   param($wordToComplete, $commandAst, $cursorPosition)
   $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
-  $candidates = if ($elements.Count -ge 2 -and $elements[1] -eq 'models') { @(${modelCommands.map((command) => `'${command}'`).join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'credentials') { @(${credentialCommands.map((command) => `'${command}'`).join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'candidate') { @(${candidateCommands.map((command) => `'${command}'`).join(", ")}) } else { @(${commands.map((command) => `'${command}'`).join(", ")}) }
+  $candidates = ${powershellCandidates}
   $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
 }
 `;
+        }
     }
 }
 export function parseCompletionShell(value) {

package/dist/src/core/reporting/doctor.js

@@ -1,7 +1,7 @@
 import { access, constants } from "node:fs/promises";
 import { dirname } from "node:path";
 import { detectAgents, directoryExists, loadoutHome, userHome, } from "../agents/paths.js";
-import { inspectAgents } from "../agents/agent-inspection.js";
+import { countComponentUnits, inspectAgents, } from "../agents/agent-inspection.js";
 async function writable(path) {
     // A not-yet-created directory is healthy when any existing ancestor is
     // writable; this handles first-run paths such as ~/.agents/skills.
@@ -83,13 +83,11 @@ export function formatDoctorReport(report, options = {}) {
     if (installed.length) {
         lines.push("DETECTED AGENTS");
         for (const entry of installed) {
-            const skillCount = entry.inventory.components
-                .filter((c) => c.scanned && c.directoryExists)
-                .reduce((sum, c) => sum + c.entries.length, 0);
+            const skillCount = entry.inventory.components.reduce((sum, component) => sum + countComponentUnits(component), 0);
             const supported = entry.inventory.components
                 .filter((c) => c.compatibility === "native" || c.compatibility === "adapted")
                 .map((c) => c.type);
-            lines.push(`  ✓ ${entry.agent.displayName}`, `    ${entry.agent.skillsDirectory}`, `    ${skillCount} items | supports: ${supported.join(", ")}`);
+            lines.push(`  ✓ ${entry.agent.displayName}`, `    ${entry.agent.skillsDirectory}`, `    ${skillCount} skills | supports: ${supported.join(", ")}`);
             if (entry.issues.length) {
                 for (const issue of entry.issues)
                     lines.push(`    ⚠ ${issue}`);
@@ -129,7 +127,7 @@ export function formatDoctorReport(report, options = {}) {
         lines.push("  Install an AI coding agent (Claude Code, Codex, Cursor, etc.),", "  then run `loadout doctor` again.");
     }
     else {
-        lines.push("  loadout status        see what's managed", "  loadout setup         install a curated skill set", "  loadout route         find the right model for your task", "  loadout health        check for updates");
+        lines.push("  loadout status        see what's managed", "  loadout setup         install a curated skill set", "  loadout health        check for updates");
     }
     return lines.join("\n");
 }

package/dist/src/core/runtime/bounded-json.js

@@ -0,0 +1,65 @@
+function combinedSignal(caller, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    return caller ? AbortSignal.any([caller, timeout]) : timeout;
+}
+async function readBoundedBody(response, maxBytes, label) {
+    const length = response.headers.get("content-length");
+    if (length !== null && /^\d+$/.test(length) && Number(length) > maxBytes) {
+        throw new Error(`${label} response exceeds the size limit`);
+    }
+    if (!response.body) {
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength > maxBytes)
+            throw new Error(`${label} response exceeds the size limit`);
+        return bytes;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel(`${label} response exceeds the size limit`);
+                throw new Error(`${label} response exceeds the size limit`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+/** Fetch and parse untrusted JSON without allowing an unbounded wait or body. */
+export async function boundedJson(fetcher, input, init, limits) {
+    if (!Number.isFinite(limits.timeoutMs) || limits.timeoutMs <= 0)
+        throw new Error("JSON request timeout must be greater than zero");
+    if (!Number.isSafeInteger(limits.maxBytes) || limits.maxBytes <= 0)
+        throw new Error("JSON response byte limit must be a positive integer");
+    const response = await fetcher(input, {
+        ...init,
+        signal: combinedSignal(init.signal, limits.timeoutMs),
+    });
+    const body = await readBoundedBody(response, limits.maxBytes, limits.label);
+    if (!response.ok)
+        return { response, value: undefined };
+    try {
+        return {
+            response,
+            value: JSON.parse(new TextDecoder().decode(body)),
+        };
+    }
+    catch {
+        throw new Error(`${limits.label} returned malformed JSON`);
+    }
+}

package/dist/src/core/runtime/github.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { loadoutHome } from "../agents/paths.js";
+import { boundedJson } from "./bounded-json.js";
 function normalizeRepository(input) {
     const value = input
         .trim()
@@ -44,10 +45,13 @@ export async function fetchGitHubMetadata(input, options = {}) {
     if (process.env.GITHUB_TOKEN)
         headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
     let response;
+    let value;
     try {
-        response = await fetcher(`https://api.github.com/repos/${repository}`, {
-            headers,
-        });
+        ({ response, value } = await boundedJson(fetcher, `https://api.github.com/repos/${repository}`, { headers }, {
+            timeoutMs: 30_000,
+            maxBytes: 4 * 1024 * 1024,
+            label: "GitHub metadata",
+        }));
     }
     catch (error) {
         if (cached)
@@ -60,21 +64,27 @@ export async function fetchGitHubMetadata(input, options = {}) {
             return cached;
         throw new Error(`GitHub metadata request failed (${response.status}${rateLimited ? ", rate limit exceeded" : ""}) for ${repository}`);
     }
-    const value = (await response.json());
+    if (!value || typeof value !== "object")
+        throw new Error(`GitHub metadata response is invalid for ${repository}`);
+    const record = value;
     const metadata = {
         repository,
-        stars: typeof value.stargazers_count === "number" ? value.stargazers_count : 0,
-        description: typeof value.description === "string" ? value.description : "",
-        defaultBranch: typeof value.default_branch === "string" ? value.default_branch : "main",
-        topics: Array.isArray(value.topics)
-            ? value.topics.filter((topic) => typeof topic === "string")
+        stars: typeof record.stargazers_count === "number" ? record.stargazers_count : 0,
+        description: typeof record.description === "string" ? record.description : "",
+        defaultBranch: typeof record.default_branch === "string"
+            ? record.default_branch
+            : "main",
+        topics: Array.isArray(record.topics)
+            ? record.topics.filter((topic) => typeof topic === "string")
             : [],
-        openIssues: typeof value.open_issues_count === "number" ? value.open_issues_count : 0,
-        archived: value.archived === true,
-        lastUpdatedAt: typeof value.updated_at === "string"
-            ? value.updated_at
+        openIssues: typeof record.open_issues_count === "number"
+            ? record.open_issues_count
+            : 0,
+        archived: record.archived === true,
+        lastUpdatedAt: typeof record.updated_at === "string"
+            ? record.updated_at
             : new Date().toISOString(),
-        pushedAt: typeof value.pushed_at === "string" ? value.pushed_at : null,
+        pushedAt: typeof record.pushed_at === "string" ? record.pushed_at : null,
         fetchedAt: new Date().toISOString(),
     };
     await mkdir(join(loadoutHome(), "cache", "github-metadata"), {
@@ -107,8 +117,13 @@ export async function fetchGitHubReleaseMetadata(input, options = {}) {
     if (process.env.GITHUB_TOKEN)
         headers.authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
     let response;
+    let releases;
     try {
-        response = await fetcher(`https://api.github.com/repos/${repository}/releases?per_page=1`, { headers });
+        ({ response, value: releases } = await boundedJson(fetcher, `https://api.github.com/repos/${repository}/releases?per_page=1`, { headers }, {
+            timeoutMs: 30_000,
+            maxBytes: 4 * 1024 * 1024,
+            label: "GitHub releases",
+        }));
     }
     catch (error) {
         if (cached)
@@ -120,7 +135,6 @@ export async function fetchGitHubReleaseMetadata(input, options = {}) {
             return cached;
         throw new Error(`GitHub release request failed (${response.status}) for ${repository}`);
     }
-    const releases = (await response.json());
     const release = Array.isArray(releases) ? releases[0] : undefined;
     const record = release && typeof release === "object" ? release : {};
     const assets = Array.isArray(record.assets)

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

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { createCredentialResolver } from "../routing/credentials.js";
+import { createCredentialResolver } from "../agents/credentials.js";
 import { planMcpConfig } from "./mcp.js";
 /**
  * Small, source-linked recipes. These configure a connection only; authorizing

package/dist/src/core/workspace/active-policy.js

@@ -378,7 +378,7 @@ export async function planProjectActivation(projectPath, options = {}) {
 }
 export async function applyProjectActivation(plan) {
     if (!plan.activation || !plan.selected.length)
-        throw new Error("No reviewed library skills were selected for activation");
+        return null;
     return applyActivationChange(plan.activation, {
         preflight: async () => {
             const requested = plan.agentPlans.map((item) => item.agent);

package/docs/CANDIDATE_INTELLIGENCE.md

@@ -93,10 +93,16 @@ powers, platform behavior, category, and catalog policy.
 
 ## Distribute a trusted catalog release
 
-Maintainers sign a technically screened full catalog array with an Ed25519 key kept outside the
+> **Not implemented.** The signing flow below is a design sketch. `loadout keygen`,
+> `loadout catalog-sign`, and `loadout catalog-update` do not exist in the CLI
+> today; the catalog ships in the package and is verified by the evidence gate
+> instead. Kept here as the intended shape, not as instructions.
+
+Maintainers would sign a technically screened full catalog array with an Ed25519 key kept outside the
 repository:
 
 ```bash
+# Design sketch — these commands do not exist yet.
 loadout keygen --private-key /secure/catalog-private.pem \
   --public-key ./catalog-public.pem
 loadout catalog-sign --catalog ./catalog/packages.json \
@@ -104,9 +110,10 @@ loadout catalog-sign --catalog ./catalog/packages.json \
   --output ./catalog.signed.json
 ```
 
-Users preview the verified release before trusting it:
+Users would preview the verified release before trusting it:
 
 ```bash
+# Design sketch — these commands do not exist yet.
 loadout catalog-update --source ./catalog.signed.json \
   --public-key ./catalog-public.pem
 loadout catalog-update --source ./catalog.signed.json \

package/docs/CATALOG.md

@@ -12,7 +12,7 @@ Thank you to every maintainer and contributor whose work appears here. Loadout d
 - **License** is the SPDX identifier recorded in `catalog/packages.json` from GitHub metadata. **Review required** corresponds to `NOASSERTION`: no SPDX identifier was reported, so users must inspect the upstream terms instead of assuming permission.
 - **Reviewed revision** links to the immutable commit inspected for catalog admission. It is not necessarily the newest upstream commit.
 
-The machine-readable catalog remains the source of truth. Run `loadout catalog --coverage --json` to inspect coverage and `loadout capabilities` to inspect what each local agent adapter can actually manage.
+The machine-readable catalog remains the source of truth. Run `loadout catalog --coverage --json` to inspect coverage and `loadout doctor --verbose` to inspect what each local agent adapter can actually manage.
 
 ## All 53 credited repositories
 

package/docs/CREDENTIAL_AND_UPDATE_POLICY.md

@@ -26,6 +26,6 @@ verification restores the snapshot and quarantines the candidate commit. A user
 revoke a policy at any time; revocation prevents future mutations but never deletes
 existing snapshots.
 
-The local `loadout canary` command implements the non-mutating static gate. A
+Update safety runs as a non-mutating static gate during `loadout upgrade` previews. A
 transaction layer must provide verification and promotion callbacks before a
 candidate can be promoted; the command itself never installs a candidate.

package/docs/DEMO_SCRIPT.md

@@ -10,7 +10,7 @@ not show the retired dashboard. The final YouTube upload must be public.
 2. Confirm the release and product health:
 
    ```bash
-   npm install --global loadout-ai@0.5.9
+   npm install --global loadout-ai@0.9.0
    hash -r
    loadout --version
    loadout health
@@ -107,33 +107,32 @@ loadout install --mode custom --package humanizer --agents codex
 > skill such as Humanizer can be installed directly through Custom mode. Each path
 > discloses permissions and credentials before approval.
 
-### 2:05 to 2:25: today and tomorrow
+### 2:05 to 2:28: hand work from Claude Code to Codex
 
 **Screen:**
 
 ```bash
-loadout update
-loadout candidate list --limit 5
+loadout skills install loadout-handoff --yes
+loadout handoff codex "write tests for the auth module" --context "see src/auth.ts"
+loadout handoff
 ```
 
 **Say:**
 
-> Update checks managed pinned sources without silently changing them. The discovery
-> feed watches a wider ecosystem and ranks new projects for review. A repository can
-> be noticed quickly without being trusted or installed blindly.
+> Loadout also gives Claude Code and Codex a tiny shared handoff log. Claude can leave
+> a bounded task with context, and Codex sees it when the next session checks its
+> inbox. It is intentionally a local file workflow—not a background service or a live
+> chat channel.
 
-### 2:25 to 2:48: Codex, GPT-5.6, and close
+### 2:28 to 2:48: close
 
-**Screen:** README section “Built with Codex and GPT-5.6”, then return to the hero.
+**Screen:** Return to the README hero and the handoff row in the workflow image.
 
 **Say:**
 
-> We used Codex and GPT-5.6 throughout the build: architecture, threat modelling,
-> cross-platform implementation, repo-wide debugging, tests, and the real founder
-> acceptance loop. Those tests caught rollback, project-scope, inventory, and update
-> bugs on my actual Codex and Claude profiles. Loadout itself stays local and does not
-> require an OpenAI API key. One command gives your AI agents a loadout you can
-> understand, improve, and undo.
+> Loadout stays local and does not require an LLM API key to manage skills. One CLI
+> gives your coding agents a setup you can inspect, improve, pass work through, and
+> undo. Agent extensions, under control.
 
 ## Final edit and upload
 
@@ -142,15 +141,12 @@ loadout candidate list --limit 5
 - Add a small title card: **Loadout: Agent extensions, under control.**
 - Export under three minutes and upload publicly to YouTube.
 - Watch the uploaded video once, confirm audio and text are legible, then paste the
-  exact public URL into README and Devpost.
+  exact public URL into the README.
 
 ## Submission checklist
 
 - [ ] Public YouTube video is under three minutes and its URL opens signed out.
-- [ ] Voiceover explains the product, Codex usage, and GPT-5.6 usage.
-- [ ] `/feedback` was run in Codex and the session ID is in Devpost.
-- [ ] Repository URL is accessible to Devpost and OpenAI.
-- [ ] README has npm setup and the judge testing path.
-- [ ] Every teammate has accepted the Devpost invitation.
-- [ ] Category is **Developer Tools**.
-- [ ] Submission is submitted, not left as a draft.
+- [ ] Voiceover shows preview, rollback, and Claude Code ↔ Codex handoff.
+- [ ] Repository and npm links open in a signed-out browser.
+- [ ] README installation and user-test paths match the published version.
+- [ ] No terminal frame exposes tokens, usernames, or private repository names.