@boopkit/cli 0.6.9 → 0.6.10

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.10",
   "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