@boopkit/cli 0.6.9 → 0.6.11

package/dist/lib/stale-scripts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Detect package.json scripts that contradict the runner settings a capability
+ * now ships, and offer the edit that reconciles them.
+ *
+ * The case this exists for: `cap-testing` used to ship `"test": "jest --runInBand"`.
+ * It now ships a `jest.config.js` carrying `maxWorkers` and `workerIdleMemoryLimit`
+ * instead, because in-band execution runs every test file through one process that
+ * Jest never recycles, and a long suite dies as that process's heap grows.
+ *
+ * `boop update` cannot simply fix those projects. Scripts are merged only when
+ * absent (see `merge-scripts` in lib/execute.ts), which is the right default —
+ * clobbering a script somebody customised would be worse than leaving it stale.
+ * So the old command survives the update, and because a CLI `--runInBand` is the
+ * first and unconditional branch of Jest's `shouldRunInBand()`, it overrides the
+ * new config entirely. That is the state worth warning about: the project now has
+ * a config file that looks like the fix, reads like the fix in review, and does
+ * nothing at all.
+ *
+ * Warning rather than prompting is deliberate. `boop update` is usually run by an
+ * agent, often inside `boop loop`, where there is no terminal to answer a question
+ * and a blocking prompt would hang the run. The warning therefore has to carry
+ * everything needed to act: which script, what is wrong with it, and the exact
+ * command that fixes it.
+ */
+export interface StaleScript {
+    /** The script's key in package.json, e.g. `test`. */
+    name: string;
+    /** The command as it stands today. */
+    command: string;
+    /** What the command becomes once the offending flags are removed. */
+    rewritten: string;
+    /** The flags that triggered the finding, in the order they appeared. */
+    flags: string[];
+}
+/**
+ * Pure: given a package.json `scripts` object, return the scripts whose command
+ * forces in-band Jest execution and therefore defeats the shipped config.
+ */
+export declare function findStaleRunnerScripts(scripts: Record<string, string> | undefined): StaleScript[];
+/**
+ * Apply the findings to the project's package.json.
+ *
+ * A finding is only applied when the script still holds exactly the command the
+ * finding was made against. Anything else means the file changed underneath us,
+ * and rewriting it then would discard somebody's edit. Returns the findings that
+ * were actually written.
+ */
+export declare function rewriteStaleRunnerScripts(targetDir: string, stale: StaleScript[]): StaleScript[];
+/**
+ * The warning shown after an update. Written to be actionable by an agent reading
+ * it in a transcript with no other context.
+ */
+export declare function formatStaleScriptWarning(stale: StaleScript[]): string;

package/dist/lib/stale-scripts.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Detect package.json scripts that contradict the runner settings a capability
+ * now ships, and offer the edit that reconciles them.
+ *
+ * The case this exists for: `cap-testing` used to ship `"test": "jest --runInBand"`.
+ * It now ships a `jest.config.js` carrying `maxWorkers` and `workerIdleMemoryLimit`
+ * instead, because in-band execution runs every test file through one process that
+ * Jest never recycles, and a long suite dies as that process's heap grows.
+ *
+ * `boop update` cannot simply fix those projects. Scripts are merged only when
+ * absent (see `merge-scripts` in lib/execute.ts), which is the right default —
+ * clobbering a script somebody customised would be worse than leaving it stale.
+ * So the old command survives the update, and because a CLI `--runInBand` is the
+ * first and unconditional branch of Jest's `shouldRunInBand()`, it overrides the
+ * new config entirely. That is the state worth warning about: the project now has
+ * a config file that looks like the fix, reads like the fix in review, and does
+ * nothing at all.
+ *
+ * Warning rather than prompting is deliberate. `boop update` is usually run by an
+ * agent, often inside `boop loop`, where there is no terminal to answer a question
+ * and a blocking prompt would hang the run. The warning therefore has to carry
+ * everything needed to act: which script, what is wrong with it, and the exact
+ * command that fixes it.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findStaleRunnerScripts = findStaleRunnerScripts;
+exports.rewriteStaleRunnerScripts = rewriteStaleRunnerScripts;
+exports.formatStaleScriptWarning = formatStaleScriptWarning;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Jest's in-band flag and its single-letter alias. */
+const IN_BAND_FLAGS = new Set(['--runInBand', '--runInBand=true', '-i']);
+/**
+ * Does this command invoke Jest? Matched on the token's basename so that `jest`,
+ * `npx jest` and `node_modules/.bin/jest` all count, while a command that merely
+ * contains the same characters somewhere does not.
+ */
+function invokesJest(tokens) {
+    return tokens.some((token) => {
+        if (token.startsWith('-'))
+            return false;
+        const base = path.basename(token);
+        return base === 'jest' || base === 'jest.js';
+    });
+}
+/**
+ * Pure: given a package.json `scripts` object, return the scripts whose command
+ * forces in-band Jest execution and therefore defeats the shipped config.
+ */
+function findStaleRunnerScripts(scripts) {
+    if (!scripts)
+        return [];
+    const findings = [];
+    for (const [name, command] of Object.entries(scripts)) {
+        if (typeof command !== 'string')
+            continue;
+        const tokens = command.split(/\s+/).filter(Boolean);
+        if (!invokesJest(tokens))
+            continue;
+        const flags = tokens.filter((t) => IN_BAND_FLAGS.has(t));
+        if (flags.length === 0)
+            continue;
+        findings.push({
+            name,
+            command,
+            rewritten: tokens.filter((t) => !IN_BAND_FLAGS.has(t)).join(' '),
+            flags,
+        });
+    }
+    return findings;
+}
+/**
+ * Apply the findings to the project's package.json.
+ *
+ * A finding is only applied when the script still holds exactly the command the
+ * finding was made against. Anything else means the file changed underneath us,
+ * and rewriting it then would discard somebody's edit. Returns the findings that
+ * were actually written.
+ */
+function rewriteStaleRunnerScripts(targetDir, stale) {
+    if (stale.length === 0)
+        return [];
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return [];
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    if (!pkg.scripts)
+        return [];
+    const applied = [];
+    for (const finding of stale) {
+        if (pkg.scripts[finding.name] !== finding.command)
+            continue;
+        pkg.scripts[finding.name] = finding.rewritten;
+        applied.push(finding);
+    }
+    if (applied.length > 0) {
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    return applied;
+}
+/**
+ * The warning shown after an update. Written to be actionable by an agent reading
+ * it in a transcript with no other context.
+ */
+function formatStaleScriptWarning(stale) {
+    if (stale.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`\x1b[33mWARN\x1b[0m ${stale.length === 1 ? 'A package.json script forces' : `${stale.length} package.json scripts force`} Jest to run in band, which overrides the settings this capability ships.`);
+    for (const finding of stale) {
+        lines.push(`  ${finding.name}:  ${finding.command}`);
+        lines.push(`  ${' '.repeat(finding.name.length)}   \x1b[32m→ ${finding.rewritten}\x1b[0m`);
+    }
+    lines.push('');
+    lines.push('  Why it matters: in band, every test file runs through one process that Jest');
+    lines.push('  never recycles, so the heap grows for the whole run until a long suite dies.');
+    lines.push('  The scaffolded jest.config.js sets maxWorkers and workerIdleMemoryLimit to');
+    lines.push('  bound that, but a command-line --runInBand wins over both, so the config is');
+    lines.push('  present and inert until this script changes.');
+    lines.push('');
+    lines.push('  boop did not change it for you because it does not overwrite scripts you may');
+    lines.push('  have customised. To apply the edit above:');
+    lines.push('');
+    lines.push('    \x1b[36mboop update --fix-scripts\x1b[0m');
+    return lines.join('\n');
+}

package/dist/lib/update.js

@@ -49,6 +49,7 @@ const scaffold_1 = require("./scaffold");
 const capability_1 = require("./capability");
 const project_1 = require("./project");
 const safe_io_1 = require("./safe-io");
+const install_layout_1 = require("./install-layout");
 /**
  * Compare a file's current hash against a stored hash.
  */
@@ -84,30 +85,11 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
     const storedHashes = meta?.fileHashes || {};
     const actions = [];
     let unchangedCount = 0;
-    // Collect files from package scaffold dir
+    // Where each of the package's files lands — the same answer `boop add` used to
+    // put them there, so an update compares like with like.
     const packageFiles = new Map(); // relPath → absolute source path
-    if (boopkit.scaffoldDir) {
-        const scaffoldDir = path.join(pkgDir, boopkit.scaffoldDir);
-        if (fs.existsSync(scaffoldDir)) {
-            collectFiles(scaffoldDir, scaffoldDir, packageFiles);
-        }
-    }
-    // Collect files from package skills dir (both flat files and folder-based skills)
-    if (boopkit.skillsDir) {
-        const skillsDir = path.join(pkgDir, boopkit.skillsDir);
-        if (fs.existsSync(skillsDir)) {
-            const entries = fs.readdirSync(skillsDir);
-            for (const entry of entries) {
-                const srcPath = path.join(skillsDir, entry);
-                if (fs.statSync(srcPath).isDirectory()) {
-                    const subFiles = new Map();
-                    collectFiles(srcPath, srcPath, subFiles);
-                    for (const [subRel, subAbs] of subFiles) {
-                        packageFiles.set(path.join('skills', entry, subRel), subAbs);
-                    }
-                }
-            }
-        }
+    for (const placement of (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir)) {
+        packageFiles.set(placement.dest, placement.source);
     }
     // For each file in the package, determine action
     for (const [relPath, srcPath] of packageFiles) {
@@ -276,7 +258,7 @@ function executeUpdatePlan(plan, options = {}) {
         const destPath = path.join(plan.targetDir, action.relativePath);
         switch (action.action) {
             case 'overwrite': {
-                const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                const srcPath = resolveSourcePath(plan.packageDir, action.relativePath);
                 if (srcPath) {
                     fs.mkdirSync(path.dirname(destPath), { recursive: true });
                     fs.copyFileSync(srcPath, destPath);
@@ -289,7 +271,7 @@ function executeUpdatePlan(plan, options = {}) {
                 const isLocallyDeleted = action.reason === 'Locally deleted';
                 if (isLocallyDeleted && options.restore) {
                     // Restore mode: re-add locally deleted files
-                    const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                    const srcPath = resolveSourcePath(plan.packageDir, action.relativePath);
                     if (srcPath) {
                         fs.mkdirSync(path.dirname(destPath), { recursive: true });
                         fs.copyFileSync(srcPath, destPath);
@@ -299,7 +281,7 @@ function executeUpdatePlan(plan, options = {}) {
                 }
                 else if (!isLocallyDeleted && options.force) {
                     // Force mode: backup and overwrite modified files
-                    const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                    const srcPath = resolveSourcePath(plan.packageDir, action.relativePath);
                     if (srcPath) {
                         if (fs.existsSync(destPath)) {
                             (0, safe_io_1.createBackup)(destPath);
@@ -322,7 +304,7 @@ function executeUpdatePlan(plan, options = {}) {
                 break;
             }
             case 'add': {
-                const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                const srcPath = resolveSourcePath(plan.packageDir, action.relativePath);
                 if (srcPath) {
                     fs.mkdirSync(path.dirname(destPath), { recursive: true });
                     fs.copyFileSync(srcPath, destPath);
@@ -374,37 +356,12 @@ function executeUpdatePlan(plan, options = {}) {
     return result;
 }
 /**
- * Resolve the source path for a relative file path from the package.
- */
-function resolveSourcePath(pkgDir, boopkit, relativePath) {
-    // Skills are stored as skills/<filename> or skills/<folder>/<file> in relPath
-    if (relativePath.startsWith('skills/') && boopkit.skillsDir) {
-        const subPath = relativePath.slice('skills/'.length);
-        const srcPath = path.join(pkgDir, boopkit.skillsDir, subPath);
-        return fs.existsSync(srcPath) ? srcPath : null;
-    }
-    // Scaffold files
-    if (boopkit.scaffoldDir) {
-        const srcPath = path.join(pkgDir, boopkit.scaffoldDir, relativePath);
-        return fs.existsSync(srcPath) ? srcPath : null;
-    }
-    return null;
-}
-/**
- * Recursively collect files from a directory into a map of relPath → absPath.
+ * Resolve the source path a project-relative file was installed from — the
+ * placement list read backwards, so it cannot disagree with what was copied.
  */
-function collectFiles(baseDir, dir, result) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            collectFiles(baseDir, fullPath, result);
-        }
-        else {
-            const relPath = path.relative(baseDir, fullPath);
-            result.set(relPath, fullPath);
-        }
-    }
+function resolveSourcePath(pkgDir, relativePath) {
+    const placement = (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir).find(p => p.dest === relativePath);
+    return placement && fs.existsSync(placement.source) ? placement.source : null;
 }
 /**
  * Format an update result as a human-readable summary line.

package/docs/init.md

@@ -33,7 +33,12 @@ Available profiles:
     runtime: node | deploy: heroku | port: 3000
 ```
 
-Right now the built-in profile is `web-app`.
+`web-app` is the only profile `boop init` can scaffold from.
+The other built-in profile, `development`, carries development capabilities and no application domain,
+so it has no runtime, port or deploy target to scaffold with —
+`boop init --profile development` is refused with a pointer to the two ways it is meant to be used:
+naming it as the `profile` in an existing project's `.boop/config.json`,
+or `boop add` for the capabilities you want.
 
 ## What It Creates
 

package/docs/skills.md

@@ -37,6 +37,7 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-skills-agent-surface-design** — When you design or audit tool surfaces (tools, schemas, APIs, conventions) that LLM agents will reach for, decide where to put the friction — adapt the system to the agent, or make the existing thing more discoverable. Last resort: prompt-engineer.
 - **boop-get-smart** — When there is a recurring fault in your own behaviour during a chat, run the five whys to find its root cause, and agree a change with the operator that makes it less likely.
 - **boop-so-what** — When the operator asks for the so-what, or says some version of 'thanks for the essay', compress what you just produced into three sentences about what they should care about.
+- **boop-skills-hyperlinking** — When you need to add, review, or repair a `## Related` section that points one skill at another, follow these rules for what earns a link, how to phrase it, which way it points, how many are too many, and how to write a path that survives `boop add`.
 
 ### `testing` — Jest testing setup
 
@@ -62,6 +63,7 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-website-dev-workflow** — When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance.
 - **boop-design-handoff-workflow** — When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run.
 - **boop-knowledge-backfill** — When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established.
+- **boop-stray-disposition** — When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do.
 
 ## Application capabilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [
@@ -22,13 +22,17 @@
   },
   "scripts": {
     "build": "tsc && node tools/generate-version-manifest.js",
+    "typecheck": "tsc -p tsconfig.test.json",
     "skills:index": "node tools/generate-skills-index.js",
+    "skills:layout": "tsx tools/generate-installed-layout.ts",
+    "skills:audit": "npm run --silent skills:layout -- --check && node tools/audit-skill-links.js",
     "build:caps": "./tools/build-caps.sh",
     "publish": "./tools/publish-caps.sh",
     "release": "./tools/publish-caps.sh --release",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
-    "test": "jest"
+    "test": "jest",
+    "pretest": "npm run skills:layout"
   },
   "keywords": [],
   "license": "ISC",

package/profiles/development/profile.md

@@ -0,0 +1,79 @@
+---
+name: development
+description: Development skills only — for a project with no application domain (a CLI, a library, a data pipeline)
+defaultCapabilities:
+  # Development
+  - coding
+  - testing
+  - project-mgmt
+  - product-design
+  - skills
+  - workflows
+---
+
+# Development Profile
+
+The development capabilities on their own,
+with no application domain attached.
+
+A project has two independent things going on:
+what it *is* — a web app, a CLI, a library, a data pipeline —
+and what its team *does with it* — write code, test it, plan it, design it, document it.
+The `web-app` profile bundles both,
+because a full-stack web application needs both.
+This profile is the second half by itself,
+for a project whose domain boop has nothing to say about.
+
+That is what makes it reusable past boop.
+A TypeScript CLI, a published library and an ETL job
+share no application layers at all,
+but they are all developed the same way.
+
+## What You Get
+
+Six capabilities, all of them `type: development` —
+pure skill bundles that guide agent behaviour,
+plus the handful of dev dependencies those skills assume:
+
+- **coding** — development conventions, code style, commit and debugging skills
+- **testing** — Jest setup, test utilities, the TDD-Lite workflow
+- **project-mgmt** — beads issue tracking and planning skills
+- **product-design** — feature requirements, engineering design, documentation skills
+- **skills** — skill authoring, discovery and maintenance
+- **workflows** — the end-to-end development and writing workflows
+
+No web layer, no API layer, no service layer, no database.
+Add any of those with `boop add` if the project grows an application domain.
+
+## Two Deliberate Omissions
+
+### No kernel
+
+`web-app` carries a `kernel` block: a node runtime, a Heroku deploy target,
+port 3000, an Express dependency set and the scripts that start a server.
+Every field in it exists to parameterise the scaffolding of a running web process.
+
+This profile scaffolds no application,
+so it has no runtime to name, no port to listen on and no deploy target.
+Filling those in with plausible-looking values
+would be inventing facts the profile does not have,
+and it would make `boop init --profile development`
+emit an Express `src/app.ts` that imports a dependency the profile never installs.
+
+So `kernel` is absent, and `ProfileMetadata.kernel` is optional to allow it.
+The consequence is deliberate: `boop init --profile development` is refused
+with a message pointing at the two ways this profile is actually meant to be used —
+name it in an existing project's `.boop/config.json`,
+or `boop add` these capabilities one at a time.
+The capabilities carry their own dependencies (`jest`, `ts-jest`, `beads`),
+so nothing is lost by having no kernel to merge them from.
+
+### No reference/
+
+`web-app` ships `reference/architecture.ref.md` and `reference/message-queue-patterns.ref.md`,
+because it has an architecture to describe.
+This profile has none — the reference pages it would want
+already ship with the capabilities themselves.
+There is no `profiles/development/reference/` directory rather than an empty one,
+because the installed-layout generator walks every profile directory
+and an empty directory is a promise of content that never arrives.

package/profiles/web-app/profile.md

@@ -25,16 +25,16 @@ kernel:
   nodeVersion: ">=24.0.0"
   dependencies: []
   devDependencies:
-    - typescript
-    - tsx
-    - nodemon
-    - "@types/express"
-    - "@types/node"
+    - typescript@^5
+    - tsx@^4
+    - nodemon@^3
+    - "@types/express@^5"
+    - "@types/node@^25"
   scripts:
     start: "tsx src/server.ts"
     dev: "nodemon --exec tsx src/server.ts"
     build: "tsc"
-    test: "jest --runInBand"
+    test: "jest"
 ---
 
 # Web App Profile