loadout-ai 0.4.0 → 0.4.1

package/dist/src/core/recommend.js

@@ -15,6 +15,7 @@ const SIGNAL_FILES = new Set([
     "next.config.mjs",
     "vite.config.ts",
     "playwright.config.ts",
+    "SECURITY.md",
     ".git",
 ]);
 /** Additive machine-readable boundary for every rule-selected recommendation list. */
@@ -22,6 +23,45 @@ export const RECOMMENDATION_BOUNDARY = Object.freeze({
     selectionMethod: "deterministic-project-signal-rules",
     qualityEvidence: "not-established",
 });
+const SIGNAL_LABELS = {
+    "javascript/typescript": "TypeScript",
+    playwright: "Playwright",
+    "node-cli": "Node CLI",
+    "npm-package": "npm package",
+    release: "release automation",
+    mcp: "MCP tooling",
+    security: "security policy",
+    commander: "Commander",
+    zod: "Zod",
+    vitest: "Vitest",
+    jest: "Jest",
+};
+const SIGNAL_DISPLAY_ORDER = [
+    "javascript/typescript",
+    "playwright",
+    "node-cli",
+    "npm-package",
+    "release",
+    "mcp",
+    "security",
+    "commander",
+    "zod",
+    "vitest",
+    "jest",
+];
+export function formatDetectedSignals(signals) {
+    const values = new Set([
+        ...signals.languages,
+        ...signals.frameworks,
+        ...signals.roles,
+        ...signals.tools,
+    ]);
+    const ordered = [
+        ...SIGNAL_DISPLAY_ORDER.filter((value) => values.delete(value)),
+        ...values,
+    ];
+    return ordered.map((value) => SIGNAL_LABELS[value] ?? value).join(", ");
+}
 export async function scanProject(root = process.cwd()) {
     const absolute = resolve(root);
     const entries = await readdir(absolute, { withFileTypes: true });
@@ -31,6 +71,8 @@ export async function scanProject(root = process.cwd()) {
         .sort();
     const languages = new Set();
     const frameworks = new Set();
+    const roles = new Set();
+    const tools = new Set();
     if (files.includes("package.json")) {
         languages.add("javascript/typescript");
         try {
@@ -44,8 +86,28 @@ export async function scanProject(root = process.cwd()) {
                 frameworks.add("vue");
             if (deps.svelte)
                 frameworks.add("svelte");
-            if (deps.playwright || deps["@playwright/test"])
+            if (deps.playwright || deps["@playwright/test"]) {
                 frameworks.add("playwright");
+                tools.add("playwright");
+            }
+            if (deps.vitest)
+                tools.add("vitest");
+            if (deps.jest)
+                tools.add("jest");
+            if (deps.commander)
+                tools.add("commander");
+            if (deps.zod)
+                tools.add("zod");
+            if (pkg.bin)
+                roles.add("node-cli");
+            if (pkg.publishConfig || pkg.private === false)
+                roles.add("npm-package");
+            const scripts = pkg.scripts ?? {};
+            if (scripts.prepack ||
+                Object.keys(scripts).some((name) => /(?:package|release)/.test(name)))
+                roles.add("release");
+            if ((pkg.keywords ?? []).some((keyword) => /(?:^|-)mcp(?:-|$)/i.test(keyword)))
+                roles.add("mcp");
         }
         catch {
             /* malformed project metadata is reported through an empty framework set */
@@ -65,22 +127,37 @@ export async function scanProject(root = process.cwd()) {
         languages.add(".net");
     if (files.some((file) => file.startsWith("next.config")))
         frameworks.add("next.js");
-    if (files.includes("playwright.config.ts"))
+    if (files.includes("playwright.config.ts")) {
         frameworks.add("playwright");
+        tools.add("playwright");
+    }
+    if (files.includes("SECURITY.md"))
+        roles.add("security");
     return {
         root: absolute,
         languages: [...languages],
         frameworks: [...frameworks],
+        roles: [...roles],
+        tools: [...tools],
         files,
     };
 }
 export function recommendPackages(signals, catalog) {
-    const ids = new Set(catalog.map((pkg) => pkg.id));
+    const packages = new Map(catalog.map((pkg) => [pkg.id, pkg]));
     const result = [];
     const add = (packageId, reason, confidence) => {
-        if (ids.has(packageId) &&
-            !result.some((item) => item.packageId === packageId))
-            result.push({ packageId, reason, confidence });
+        const pkg = packages.get(packageId);
+        if (pkg && !result.some((item) => item.packageId === packageId))
+            result.push({
+                packageId,
+                reason,
+                confidence,
+                kind: pkg.components?.includes("skill")
+                    ? "skill-library"
+                    : pkg.components?.some((component) => component === "mcp" || component === "plugin")
+                        ? "mcp-runtime"
+                        : "unavailable",
+            });
     };
     add("superpowers", "Useful engineering planning, testing, and review workflows for most repositories.", "high");
     add("context7", "Current library documentation helps agents avoid outdated APIs.", signals.languages.length ? "high" : "medium");
@@ -129,6 +206,7 @@ export function personalizeRecommendations(recommendations, signals, outcomes, a
         packageId: item.packageId,
         reason: item.reason,
         confidence: item.confidence,
+        kind: item.kind,
         ...(item.localOutcomeAdjustment !== undefined
             ? { localOutcomeAdjustment: item.localOutcomeAdjustment }
             : {}),
@@ -174,14 +252,22 @@ export function profileManifestPackages(profile, catalog) {
 export function formatRecommendations(signals, recommendations) {
     const lines = [
         `Project: ${basename(signals.root)}`,
-        `Detected: ${[...signals.languages, ...signals.frameworks].join(", ") || "no known project signals"}`,
+        `Detected: ${formatDetectedSignals(signals) || "no known project signals"}`,
         "",
         "Rule-based project suggestions:",
         "Rules use detected project signals and catalog membership; they do not prove package quality.",
     ];
     if (!recommendations.length)
         lines.push("  No matching catalog packages found.");
-    for (const item of recommendations)
-        lines.push(`  ${item.packageId} [${item.confidence}] — ${item.reason}`);
+    const kindLabels = {
+        "skill-library": "skill library",
+        "mcp-runtime": "MCP/runtime setup",
+        unavailable: "unavailable",
+    };
+    for (const item of recommendations) {
+        lines.push(`  ${item.packageId} [${item.confidence}, ${kindLabels[item.kind]}] — ${item.reason}`);
+        if (item.kind === "mcp-runtime")
+            lines.push("    Explicit setup only; preview credentials and permissions before enabling it.");
+    }
     return lines.join("\n");
 }

package/dist/src/core/target-occupancy.js

@@ -0,0 +1,50 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Inspect a prospective skill target without following symlinks or executing
+ * any content. Missing paths and recursively empty directories are safe to
+ * replace; every uncertain state fails closed.
+ */
+export async function inspectTargetOccupancy(path, maximumEntries = 10_000) {
+    let root;
+    try {
+        root = await lstat(path);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return { occupied: false };
+        return { occupied: true, reason: "unreadable" };
+    }
+    if (root.isSymbolicLink())
+        return { occupied: true, reason: "symlink" };
+    if (!root.isDirectory())
+        return { occupied: true, reason: "unsupported" };
+    const queue = [path];
+    let inspected = 0;
+    while (queue.length) {
+        const directory = queue.pop();
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return { occupied: true, reason: "unreadable" };
+        }
+        for (const entry of entries) {
+            inspected += 1;
+            if (inspected > maximumEntries)
+                return { occupied: true, reason: "inspection-limit" };
+            if (entry.isDirectory() && !entry.isSymbolicLink())
+                queue.push(join(directory, entry.name));
+            else
+                return {
+                    occupied: true,
+                    reason: entry.isSymbolicLink() ? "symlink" : "content",
+                };
+        }
+    }
+    return { occupied: false };
+}

package/docs/USER_TEST_GUIDE.md

@@ -26,15 +26,19 @@ Loadout-managed skills from your own pre-existing skills. `health` checks local
 loadout catalog --json
 loadout candidate list --limit 10
 loadout recommend --project .
-loadout optimize --project .
+loadout optimize --project . --agents codex,claude-code --limit 30
 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.
+absolute path. `recommend` labels ordinary skill libraries separately from MCP or
+runtime integrations that require explicit setup. `optimize` is still a preview
+until `--yes` is supplied. Its limit applies separately to every agent and includes
+both Loadout-managed and pre-existing unmanaged skills, so Claude and Codex can
+receive different numbers of additions. `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
 
@@ -64,6 +68,10 @@ loadout setup --mode power --agents codex,claude-code
 loadout setup --mode maximum --agents codex,claude-code
 ```
 
+Maximum stores reviewed copies in Loadout's disabled library; it does not expose the
+whole catalog to each agent. Follow it with `loadout optimize --project .
+--agents codex,claude-code --limit 30` to preview a compact project-aware working set.
+
 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
@@ -161,7 +169,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.4.1` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,
@@ -172,6 +180,10 @@ loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
   legacy snapshot without post-mutation evidence. Run `loadout health --explain` and
   inspect the affected path before deciding whether an explicit force option is
   appropriate; do not delete the path merely to make the command pass.
+- **Activation reports fewer additions for one agent:** this is expected when that
+  agent already has unmanaged or managed skills. `--limit` is a total per-agent
+  ceiling, not a request to add that many new skills. Recursively empty rollback
+  directories do not consume capacity and are safe for Loadout to reuse.
 - **A fetch, discovery, or update check fails:** retry only after checking network,
   proxy, DNS, and source-host access. Local inventory, library, health, rollback, and
   offline fixture tests remain separate; an unavailable live check is not a pass.