@boopkit/cli 0.6.9 → 0.6.11

package/README.md

@@ -67,7 +67,7 @@ Capabilities can declare `requires` relationships (e.g. `users-and-accounts` req
 
 ## Profiles
 
-A profile is where a project starts. Today there's one; more will follow as the common shapes of AI-first products become clearer.
+A profile names a set of capabilities. Two ship today.
 
 ### `web-app`
 
@@ -75,6 +75,16 @@ Full-stack web application — Express + Handlebars + Tailwind CSS + PostgreSQL
 
 Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`), and the `hello` demo capability.
 
+This is the profile `boop init` scaffolds from — it carries a kernel, so there is an application to write.
+
+### `development`
+
+The development capabilities on their own (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`) — no web layer, no API layer, no database.
+
+For a project with no application domain boop has anything to say about: a CLI, a library, a data pipeline. Those share no application layers at all, but they are developed the same way.
+
+It carries no kernel — no runtime, no port, no deploy target — so there is nothing for `boop init` to scaffold and `boop init --profile development` is refused. Use it by naming it as the `profile` in an existing project's `.boop/config.json`, or reach for `boop add` on the capabilities you want. Boop's own repository is the first project to declare it.
+
 List profiles with `boop list profiles`.
 
 ## Available Capabilities
@@ -119,10 +129,10 @@ Adding a capability installs its skills into your project's `skills/` directory.
 - **`coding`** — boop-coding-beads-flow, boop-coding-development, boop-coding-commit-changes, boop-coding-review-changes, boop-coding-debugging
 - **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
 - **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning
-- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what
+- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what, boop-skills-hyperlinking
 - **`testing`** — boop-testing-tdd-light, boop-testing-testing-express-web, boop-testing-testing
 - **`ux`** — boop-ux-purpose-judgement, boop-ux-visual-judgement, boop-ux-eval-and-refine-workflow, boop-ux-app-ui-dev-workflow
-- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow, boop-issue-sweep-workflow, boop-website-dev-workflow, boop-design-handoff-workflow, boop-knowledge-backfill
+- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow, boop-issue-sweep-workflow, boop-website-dev-workflow, boop-design-handoff-workflow, boop-knowledge-backfill, boop-stray-disposition
 
 **Application capabilities**
 

package/dist/capability-versions.json

@@ -1,21 +1,21 @@
 {
-  "@boopkit/cap-api": "0.4.2",
+  "@boopkit/cap-api": "0.4.4",
   "@boopkit/cap-background-jobs": "0.4.2",
   "@boopkit/cap-cloud-storage": "0.4.0",
   "@boopkit/cap-coding": "0.4.4",
   "@boopkit/cap-database": "0.4.3",
   "@boopkit/cap-email": "0.4.2",
-  "@boopkit/cap-hello": "0.4.0",
-  "@boopkit/cap-noticeboard": "0.4.0",
-  "@boopkit/cap-oauth-client": "0.1.0",
+  "@boopkit/cap-hello": "0.4.1",
+  "@boopkit/cap-noticeboard": "0.4.1",
+  "@boopkit/cap-oauth-client": "0.1.1",
   "@boopkit/cap-product-design": "0.6.7",
-  "@boopkit/cap-project-mgmt": "0.4.5",
+  "@boopkit/cap-project-mgmt": "0.4.9",
   "@boopkit/cap-services": "0.4.2",
-  "@boopkit/cap-skills": "0.5.3",
-  "@boopkit/cap-testing": "0.5.3",
-  "@boopkit/cap-users": "0.4.4",
+  "@boopkit/cap-skills": "0.5.4",
+  "@boopkit/cap-testing": "0.5.6",
+  "@boopkit/cap-users": "0.7.0",
   "@boopkit/cap-ux": "0.2.2",
-  "@boopkit/cap-web": "0.5.3",
-  "@boopkit/cap-workflows": "0.1.0",
+  "@boopkit/cap-web": "0.5.4",
+  "@boopkit/cap-workflows": "0.2.0",
   "@boopkit/logger": "0.4.0"
 }

package/dist/cli.js

@@ -91,6 +91,7 @@ program
     .option('--prune', 'Remove deprecated scaffold files from disk (creates .bak backup)')
     .option('--skip-npm', 'Skip npm update (only re-scaffold from installed versions)')
     .option('--tag <tag>', 'Use a specific npm dist-tag instead of major-version pinning (e.g. beta)')
+    .option('--fix-scripts', 'Rewrite package.json scripts that contradict shipped runner settings')
     .option('--json', 'Output structured JSON')
     .action(update_1.runUpdate);
 program

package/dist/commands/init.js

@@ -71,8 +71,21 @@ function runInit(name, options) {
         process.exitCode = 1;
         return;
     }
+    // --- Guard: a profile with no kernel has no application to scaffold ---
+    // `boop init` exists to write a running project from kernel templates. A
+    // profile that names only development capabilities (profiles/development/)
+    // has no runtime, port or deploy target to render them with, so refuse here
+    // rather than emit a project that cannot start.
+    if (!profile.kernel) {
+        console.error(`Error: Profile "${profileName}" carries no kernel, so there is nothing to scaffold.`);
+        console.error('It declares capabilities for a project that already exists: name it as the "profile" in that');
+        console.error(`project's .boop/config.json, or run \`boop add\` for the capabilities you want.`);
+        process.exitCode = 1;
+        return;
+    }
+    const kernel = profile.kernel;
     // --- Node version check ---
-    const requiredNodeVersion = profile.kernel.nodeVersion;
+    const requiredNodeVersion = kernel.nodeVersion;
     if (requiredNodeVersion && !process.env.BOOP_SKIP_VERSION_CHECK) {
         const minVersion = requiredNodeVersion.replace(/^[>=^~]+/, '');
         const currentMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -126,14 +139,14 @@ function runInit(name, options) {
     // --- Scaffold kernel ---
     const variables = {
         projectName: name,
-        port: profile.kernel.port,
-        scripts: profile.kernel.scripts,
-        nodeVersion: profile.kernel.nodeVersion ?? '>=18.0.0',
+        port: kernel.port,
+        scripts: kernel.scripts,
+        nodeVersion: kernel.nodeVersion ?? '>=18.0.0',
         ...hookVars,
     };
     const kernelFiles = (0, scaffold_1.scaffoldKernel)(targetDir, variables);
     // --- Merge kernel dependencies ---
-    (0, scaffold_1.mergePackageJson)(targetDir, profile.kernel.dependencies, profile.kernel.devDependencies, undefined, { skipBackup: true });
+    (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
     // --- Create minimal manifest so capability hash storage can find config.json ---
     (0, project_1.writeProjectManifest)(targetDir, {
         name,
@@ -183,7 +196,7 @@ function runInit(name, options) {
         (0, scaffold_1.scaffoldKernel)(targetDir, variables, true);
         // Re-scaffolding overwrites package.json (template has empty deps),
         // so re-merge kernel deps + cap package deps that were added earlier.
-        (0, scaffold_1.mergePackageJson)(targetDir, profile.kernel.dependencies, profile.kernel.devDependencies, undefined, { skipBackup: true });
+        (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
         (0, scaffold_1.mergePackageJson)(targetDir, undefined, undefined, capDeps, { skipBackup: true });
     }
     // Post-install conflict check (when preflight was deferred)

package/dist/commands/list.js

@@ -35,7 +35,11 @@ function listProfilesCommand() {
     for (const p of profiles) {
         console.log(`  ${p.name}`);
         console.log(`    ${p.description}`);
-        console.log(`    runtime: ${p.kernel.runtime} | deploy: ${p.kernel.deploy} | port: ${p.kernel.port}`);
+        // A profile with no application domain carries no kernel, so there is no
+        // runtime line to print for it.
+        if (p.kernel) {
+            console.log(`    runtime: ${p.kernel.runtime} | deploy: ${p.kernel.deploy} | port: ${p.kernel.port}`);
+        }
         const grouped = new Map();
         for (const capName of p.defaultCapabilities) {
             const cap = (0, capability_1.getCapability)(capName);

package/dist/commands/status.js

@@ -180,6 +180,8 @@ async function enrichWithSetupChecks(data, envValues, projectDir, projectName) {
             type: c.type,
             label: (0, interpolate_1.interpolate)(c.label, vars),
             hint: c.hint ? (0, interpolate_1.interpolate)(c.hint, vars) : undefined,
+            // Probe queries are literal SQL — pass them through untouched.
+            query: c.query,
         }));
         // Extract this capability's .prisma files for scoped prisma-migrate checks
         const prismaFiles = capDef?.files?.filter(f => f.endsWith('.prisma'));

package/dist/commands/update.d.ts

@@ -6,5 +6,6 @@ export interface UpdateOptions {
     json?: boolean;
     skipNpm?: boolean;
     tag?: string;
+    fixScripts?: boolean;
 }
 export declare function runUpdate(capabilityName: string | undefined, options: UpdateOptions): void;

package/dist/commands/update.js

@@ -41,6 +41,7 @@ const project_1 = require("../lib/project");
 const capability_1 = require("../lib/capability");
 const update_1 = require("../lib/update");
 const scaffold_1 = require("../lib/scaffold");
+const stale_scripts_1 = require("../lib/stale-scripts");
 function runUpdate(capabilityName, options) {
     const targetDir = process.cwd();
     // Must be in a boop project
@@ -95,8 +96,9 @@ function runUpdate(capabilityName, options) {
     }
     // Dry run: show plans and exit
     if (options.dryRun) {
+        const stale = detectStaleScripts(targetDir);
         if (options.json) {
-            console.log(JSON.stringify({ capabilities: plans }, null, 2));
+            console.log(JSON.stringify({ capabilities: plans, staleScripts: stale }, null, 2));
             return;
         }
         for (const plan of plans) {
@@ -114,6 +116,9 @@ function runUpdate(capabilityName, options) {
                 console.log(`  ${icon} ${action.relativePath} — ${action.reason}`);
             }
         }
+        if (stale.length > 0) {
+            console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(stale)}`);
+        }
         return;
     }
     // Execute updates
@@ -141,9 +146,21 @@ function runUpdate(capabilityName, options) {
     if (!options.dryRun) {
         (0, scaffold_1.linkSkillsToClaude)(targetDir);
     }
+    // A script that contradicts the settings a capability now ships survives the
+    // update, because scripts are only merged when absent. Say so, or fix it on
+    // request. See lib/stale-scripts.ts for why this is a warning and not a prompt.
+    const stale = detectStaleScripts(targetDir);
+    const fixedScripts = options.fixScripts ? (0, stale_scripts_1.rewriteStaleRunnerScripts)(targetDir, stale) : [];
+    const remainingStale = options.fixScripts
+        ? stale.filter((f) => !fixedScripts.some((a) => a.name === f.name))
+        : stale;
     // Output
     if (options.json) {
-        console.log(JSON.stringify({ capabilities: results }, null, 2));
+        console.log(JSON.stringify({
+            capabilities: results,
+            staleScripts: remainingStale,
+            fixedScripts,
+        }, null, 2));
         return;
     }
     console.log(`\n${'─'.repeat(40)}`);
@@ -182,6 +199,29 @@ function runUpdate(capabilityName, options) {
             }
         }
     }
+    for (const fixed of fixedScripts) {
+        console.log(`\n\x1b[32m✓\x1b[0m package.json script "${fixed.name}" rewritten: ${fixed.command} → ${fixed.rewritten}`);
+    }
+    if (remainingStale.length > 0) {
+        console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(remainingStale)}`);
+    }
+}
+/**
+ * Read the project's package.json scripts and return those that contradict the
+ * runner settings the capabilities now ship. Missing or unreadable package.json
+ * is not an error here — this check is advisory and must never fail an update.
+ */
+function detectStaleScripts(targetDir) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return [];
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return (0, stale_scripts_1.findStaleRunnerScripts)(pkg.scripts);
+    }
+    catch {
+        return [];
+    }
 }
 /**
  * Diagnose why no update plans were generated and return a specific message.

package/dist/lib/capability.d.ts

@@ -5,6 +5,17 @@ import { CapabilityMetadata } from './config';
  * Returns null if not found.
  */
 export declare function getPackageDir(name: string, searchPaths?: string[]): string | null;
+/**
+ * The capability name a package directory ships — the name a project's
+ * `.boop/config.json` records for it.
+ *
+ * Usually that is the directory name minus `cap-`, but the two are allowed to
+ * differ and `capability.json` is the authority: `packages/cap-users` ships
+ * `users-and-accounts`. Reading the directory alone is a pure filesystem
+ * lookup, so it works against a source tree that has never been built or
+ * installed — which is what the installed-layout generator needs.
+ */
+export declare function capabilityNameForPackageDir(pkgDir: string): string;
 /**
  * Look up a capability in the baked-in catalog by name.
  * Returns the catalog entry (with package field) or null if not found.

package/dist/lib/capability.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPackageDir = getPackageDir;
+exports.capabilityNameForPackageDir = capabilityNameForPackageDir;
 exports.getCatalogEntry = getCatalogEntry;
 exports.listCapabilities = listCapabilities;
 exports.getCapability = getCapability;
@@ -59,6 +60,31 @@ function getPackageDir(name, searchPaths) {
         return findPackageDirByCapabilityName(name, paths);
     }
 }
+/**
+ * The capability name a package directory ships — the name a project's
+ * `.boop/config.json` records for it.
+ *
+ * Usually that is the directory name minus `cap-`, but the two are allowed to
+ * differ and `capability.json` is the authority: `packages/cap-users` ships
+ * `users-and-accounts`. Reading the directory alone is a pure filesystem
+ * lookup, so it works against a source tree that has never been built or
+ * installed — which is what the installed-layout generator needs.
+ */
+function capabilityNameForPackageDir(pkgDir) {
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    if (fs.existsSync(capJsonPath)) {
+        try {
+            const { name } = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+            if (typeof name === 'string' && name.length > 0)
+                return name;
+        }
+        catch {
+            // An unreadable capability.json is not worth failing over here; the
+            // directory name is the same answer in every case but the mismatches.
+        }
+    }
+    return path.basename(pkgDir).replace(/^cap-/, '');
+}
 /**
  * Read capability metadata from a package's capability.json.
  * Returns null if the package is not found or has no capability.json.

package/dist/lib/config.d.ts

@@ -14,7 +14,12 @@ export interface ProfileMetadata {
     name: string;
     description: string;
     defaultCapabilities: string[];
-    kernel: KernelConfig;
+    /**
+     * Optional: every field of KernelConfig parameterises the scaffolding of a
+     * running web process, so a profile with no application domain (see
+     * `profiles/development/`) has no honest values to put here and omits it.
+     */
+    kernel?: KernelConfig;
 }
 export interface CapabilityScript {
     cmd: string;
@@ -34,9 +39,16 @@ export interface CapabilityEnvVar {
     required?: 'boot' | 'runtime';
 }
 export interface CapabilitySetupCheck {
-    type: 'env-set' | 'service' | 'database' | 'prisma-migrate' | 'prisma-generate';
+    type: 'env-set' | 'service' | 'database' | 'prisma-migrate' | 'prisma-generate' | 'probe';
     label: string;
     hint?: string;
+    /**
+     * For `type: 'probe'` only — a read-only SQL query the capability asserts
+     * about its own data. The check passes when the query returns no rows. The
+     * query runs in a read-only transaction, so it cannot write. Ignored by
+     * every other check type.
+     */
+    query?: string;
 }
 export interface CapabilityPostInstall {
     prerequisites?: string[];

package/dist/lib/db-status.d.ts

@@ -51,6 +51,22 @@ export declare function isPrismaClientGenerated(projectDir: string): boolean;
  * Returns true if in sync, false if not, null if prisma not available.
  */
 export declare function checkPrismaMigrateStatus(projectDir: string): Promise<boolean | null>;
+/**
+ * Run a capability-supplied read-only data probe.
+ *
+ * The query is executed in a read-only transaction (via PGOPTIONS), so a probe
+ * that accidentally contains a write raises "cannot execute … in a read-only
+ * transaction" rather than mutating anything. The probe is a positive detector:
+ * it reports a violation ONLY when it observes one.
+ *
+ * Returns:
+ *   true  — clean: the query returned no rows.
+ *   false — violation: the query returned at least one row.
+ *   null  — could not run (psql missing, DB unreachable, table absent, or the
+ *           query errored). The caller treats this as "no violation observed"
+ *           so an un-runnable probe never raises a false alarm.
+ */
+export declare function checkDataProbe(dbUrl: string, query: string): Promise<boolean | null>;
 export interface SetupStep {
     label: string;
     done: boolean;
@@ -73,4 +89,5 @@ export declare function runSetupChecks(checks: {
     type: string;
     label: string;
     hint?: string;
+    query?: string;
 }[], envValues: Map<string, string>, projectDir: string, projectName: string, prismaFiles?: string[]): Promise<SetupStep[]>;

package/dist/lib/db-status.js

@@ -43,6 +43,7 @@ exports.checkTablesExist = checkTablesExist;
 exports.hasPrismaModels = hasPrismaModels;
 exports.isPrismaClientGenerated = isPrismaClientGenerated;
 exports.checkPrismaMigrateStatus = checkPrismaMigrateStatus;
+exports.checkDataProbe = checkDataProbe;
 exports.runSetupChecks = runSetupChecks;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -258,11 +259,46 @@ function checkPrismaMigrateStatus(projectDir) {
     });
 }
 /**
- * Run a single setup check by type. Returns true/false for pass/fail.
+ * Run a capability-supplied read-only data probe.
+ *
+ * The query is executed in a read-only transaction (via PGOPTIONS), so a probe
+ * that accidentally contains a write raises "cannot execute … in a read-only
+ * transaction" rather than mutating anything. The probe is a positive detector:
+ * it reports a violation ONLY when it observes one.
+ *
+ * Returns:
+ *   true  — clean: the query returned no rows.
+ *   false — violation: the query returned at least one row.
+ *   null  — could not run (psql missing, DB unreachable, table absent, or the
+ *           query errored). The caller treats this as "no violation observed"
+ *           so an un-runnable probe never raises a false alarm.
+ */
+function checkDataProbe(dbUrl, query) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('psql', [dbUrl, '-tAc', query], {
+            timeout: 3000,
+            // Force a read-only session: any write in the query fails at the server.
+            env: { ...process.env, PGOPTIONS: '-c default_transaction_read_only=on' },
+        }, (error, stdout) => {
+            if (error) {
+                // psql not installed, DB unreachable, missing table, or a query error.
+                // None of these is an observed violation, so don't raise a false alarm.
+                resolve(null);
+            }
+            else {
+                // With -tA a zero-row result is empty output; any output means the
+                // query found a violating row.
+                resolve(stdout.trim() === '' ? true : false);
+            }
+        });
+    });
+}
+/**
+ * Run a single setup check. Returns true/false for pass/fail.
  * Checks can depend on earlier results via ctx.results.
  */
-async function runCheck(type, ctx) {
-    switch (type) {
+async function runCheck(check, ctx) {
+    switch (check.type) {
         case 'env-set': {
             const dbUrl = ctx.envValues.get('DATABASE_URL');
             return !!dbUrl;
@@ -319,6 +355,20 @@ async function runCheck(type, ctx) {
         case 'prisma-generate': {
             return isPrismaClientGenerated(ctx.projectDir);
         }
+        case 'probe': {
+            // A read-only data probe: passes when the capability's query finds no
+            // violating rows. Needs a query and a database URL; without either there
+            // is nothing to observe, so it passes rather than raising a false alarm.
+            if (!check.query)
+                return true;
+            const dbUrl = ctx.envValues.get('DATABASE_URL');
+            if (!dbUrl)
+                return true;
+            const result = await checkDataProbe(dbUrl, check.query);
+            // Only an observed violation (result === false) fails the check; a probe
+            // that could not run (null) is treated as clean.
+            return result !== false;
+        }
         default:
             return false;
     }
@@ -331,7 +381,7 @@ async function runSetupChecks(checks, envValues, projectDir, projectName, prisma
     const ctx = { envValues, projectDir, projectName, results: new Map(), prismaFiles };
     const steps = [];
     for (const check of checks) {
-        const done = await runCheck(check.type, ctx);
+        const done = await runCheck(check, ctx);
         ctx.results.set(check.type, done);
         let hint = check.hint;
         // When prisma-migrate fails and no migrations exist yet, the first

package/dist/lib/install-layout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The single answer to "where does a file land when it is installed".
+ *
+ * `boop add` copies a capability's files into a project and `boop init` copies a
+ * profile's reference pages; before this module the mapping from source file to
+ * destination path was written out twice — once read-only inside `planAdd`, once
+ * while copying inside `copyFromPackage` — so the two could disagree about what a
+ * project receives and nothing would notice. Everything here is a pure read: it
+ * looks at a package or profile directory and returns `Placement[]`. It never
+ * writes, never needs a `targetDir`, and never touches `.boop/`.
+ *
+ * Three consumers depend on it: `copyFromPackage` (src/lib/scaffold.ts),
+ * `planAdd` (src/lib/preflight.ts) and `tools/generate-installed-layout.ts`,
+ * which materialises the installed layout inside the boop repository itself.
+ * Adding a fourth answer to this question is the defect this module exists to
+ * prevent.
+ */
+/** `skill` files land under `skills/`; `scaffold` files land wherever the package's scaffold tree says. */
+export type PlacementKind = 'skill' | 'scaffold';
+/**
+ * What ships a file. `hand-authored` is not an installable thing — it labels a
+ * file that already exists in a tree the mirror writes into, so a collision with
+ * one can be reported with the same machinery.
+ */
+export type PlacementOwnerKind = 'capability' | 'profile' | 'hand-authored';
+export interface Placement {
+    /** 'cap-database', 'web-app', or 'skills/boop-dolt-recovery' — the thing that ships this file. */
+    owner: string;
+    ownerKind: PlacementOwnerKind;
+    /** Absolute path of the file inside the package or profile directory. */
+    source: string;
+    /** Where it lands, POSIX-relative to the project root, e.g. 'skills/boop-database-prisma/SKILL.md'. */
+    dest: string;
+    kind: PlacementKind;
+}
+/** Two or more different sources claiming one destination. */
+export interface PlacementCollision {
+    dest: string;
+    placements: Placement[];
+}
+export declare class PlacementCollisionError extends Error {
+    readonly collisions: PlacementCollision[];
+    constructor(collisions: PlacementCollision[]);
+}
+/** How a collision names each side: the owner, and for hand-authored files, that nothing ships it. */
+export declare function describePlacementOwner(placement: Placement): string;
+/**
+ * Placements for an already-resolved capability package directory.
+ *
+ * `capabilityPlacements` delegates here once it has resolved a name to a package;
+ * the generator calls it directly because it walks `packages/cap-*` on disk and
+ * has no need of npm module resolution (and must not require a build).
+ */
+export declare function capabilityPlacementsFromDir(pkgDir: string): Placement[];
+/**
+ * Every file a capability ships and where it lands in a project.
+ *
+ * Resolves the capability the way `boop add` does — the installed package first,
+ * then the `capabilities/` source tree that only test fixtures still use.
+ */
+export declare function capabilityPlacements(capabilityName: string, searchPaths?: string[]): Placement[];
+/**
+ * Every file a profile ships and where it lands, mirroring `boop init`
+ * (src/commands/init.ts) — today that is the profile's reference pages.
+ */
+export declare function profilePlacements(profileName: string, repoRoot?: string): Placement[];
+/**
+ * The directory-level view of a skill's placements: one entry per skill folder.
+ *
+ * The mirror materialises a skill as a single link to its folder rather than a
+ * link per file, and this derives that view from the same placement list rather
+ * than re-deriving `skills/<name>` from a package layout a second time.
+ */
+export declare function skillDirectoryPlacements(placements: Placement[]): Placement[];
+/** Every destination claimed by two or more different source files. */
+export declare function findPlacementCollisions(placements: Placement[]): PlacementCollision[];
+/**
+ * Throw if any destination is claimed twice.
+ *
+ * The install path would not throw — `safeCopyDir` applies `onConflict: 'skip'`
+ * per file, so a second claimant silently half-merges into the first. That is
+ * fine to warn about while installing one capability into a project and fatal
+ * when writing a mirror of the whole library, which is why this is a separate
+ * assertion rather than something `planAdd` inherits.
+ */
+export declare function assertNoPlacementCollisions(placements: Placement[]): void;