@3fn/core 14.0.0 → 15.0.0

package/dist/cli/init.js

@@ -1,12 +1,20 @@
 "use strict";
 /**
- * `npx designerpunk init` — Bootstrap a self-contained product repo.
+ * `npx designerpunk init` — the birth event (Spec 123, design.md C1).
  *
- * Copies tokens, components, themes, agents, and steering docs from the
- * DesignerPunk source into the current directory. Creates a designerpunk.config.ts
- * with theme registration. Products evolve independently after init.
+ * Under Model B, `init` runs ONCE per design system, ever. It copies the
+ * consumer's token tier (their language, wholesale), scaffolds the
+ * consumer-owned component directory, config and test tooling, and emits the
+ * agent layer plus MCP config for ONE target (`--target=<cc|kiro>`; bare
+ * `init` emits the profile's declared default) through `attach`'s code path
+ * (`emitAgentLayer`, C1's "(new) agent layer" row — the release-1 copies of
+ * `.kiro/agents` / `.kiro/steering` / `governance` are REMOVED). It REFUSES in
+ * a born, partial, or package-mode repo (`--re-scaffold` overrides, listing
+ * every file it would re-add first).
  *
- * @see .kiro/specs/097-product-mcp-intelligence-layer/cli-init-design.md
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C1. The birth event"
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C4. Rewrite-at-copy"
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C27. `init` UX"
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -42,14 +50,128 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnmappedSpecifierError = exports.ManifestBuilder = void 0;
 exports.runInit = runInit;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
 const readline = __importStar(require("readline"));
 const transforms_1 = require("./shared/transforms");
+Object.defineProperty(exports, "UnmappedSpecifierError", { enumerable: true, get: function () { return transforms_1.UnmappedSpecifierError; } });
 const resolvePackageRoot_1 = require("./shared/resolvePackageRoot");
+const NameContract_1 = require("./sync/NameContract");
+const bornRepo_1 = require("./shared/bornRepo");
+const errorCatalog_1 = require("./shared/errorCatalog");
+const attach_1 = require("./attach");
+const Manifest_1 = require("./sync/Manifest");
+/**
+ * Accumulates manifest entries across every step, written LAST (design.md C1's
+ * manifest row: "so no generated file lacks an entry"). Req 5.8: `src/tokens/**`
+ * NEVER gets an entry — no baseline applies to the consumer's own language.
+ */
+class ManifestBuilder {
+    constructor() {
+        /**
+         * The mutable state `emitAgentLayer` records into (the same `attach` code path writes
+         * `entries` and `attachedTargets` here) — `build()` reads it back, so no generated file
+         * lacks an entry. `attachedTargets` starts EMPTY: a target is added only when its agent
+         * layer is emitted (C9; never a literal target list — C12).
+         */
+        this.state = {
+            entries: {},
+            attachedTargets: [],
+        };
+    }
+    recordFile(relPath, absPath, origin) {
+        if (relPath.split(path.sep).join('/').startsWith('src/tokens/')) {
+            // Req 5.8 — no entry for the consumer's own copied token tier, ever.
+            return;
+        }
+        const content = fs.readFileSync(absPath, 'utf-8');
+        this.state.entries[relPath.split(path.sep).join('/')] = {
+            hash: hashContent(content),
+            grain: 'file',
+            origin,
+        };
+    }
+    recordKey(relPath, key, content) {
+        const keyPath = `${relPath.split(path.sep).join('/')}#${key}`;
+        this.state.entries[keyPath] = {
+            hash: hashContent(JSON.stringify(content)),
+            grain: 'key',
+            origin: 'emitted-key',
+        };
+    }
+    build(installedVersion, contractHash = '') {
+        return {
+            version: '1',
+            posture: 'born',
+            installedVersion,
+            // The installed package's type-contract hash (dist/name-contract.json
+            // `typeContract.hash`, Spec 123 Task 6 / DD11) — '' only when the package
+            // ships no contract, never a faked value.
+            contractHash,
+            attachedTargets: this.state.attachedTargets,
+            entries: this.state.entries,
+        };
+    }
+}
+exports.ManifestBuilder = ManifestBuilder;
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
 async function runInit(argv) {
     const opts = parseInitArgs(argv);
+    const dest = process.cwd();
+    const pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(__dirname);
+    const dsRoot = (0, bornRepo_1.findDesignSystemRoot)(dest);
+    // --- The selected target — resolved UP FRONT, so an undeclared `--target` (or a package
+    // packed without its prepack build) fails before init writes anything. Read through the
+    // PACKAGED consumer profile (`loadConsumerProfile`'s packaged form, C12/C9): bare `init`
+    // = the declared default, `--target=<t>` = `<t>`; no literal target list here. ---------
+    try {
+        (0, attach_1.resolveAgentTarget)(pkgRoot, opts.target, 'init');
+    }
+    catch (err) {
+        console.error(`❌ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return;
+    }
+    // --- Step 0: birth check (design.md C1 row 0; Req 15A.3) ---------------
+    if (!opts.reScaffold) {
+        if (dsRoot.state === 'born') {
+            console.error(`❌ ${(0, errorCatalog_1.initBornRepoMessage)(dsRoot.root ?? dest)}`);
+            process.exit(1);
+            return;
+        }
+        if (dsRoot.state === 'package-mode') {
+            console.error(`❌ ${(0, errorCatalog_1.packageModeIndexAbsentMessage)()}`);
+            process.exit(1);
+            return;
+        }
+        if (dsRoot.state === 'partial' && dsRoot.partialCase) {
+            console.error(`❌ ${(0, errorCatalog_1.partialCaseMessage)(dsRoot.root ?? dest, dsRoot.partialCase, dsRoot.attemptedTokenSource)}`);
+            process.exit(1);
+            return;
+        }
+        // unborn (or a consume-posture manifest, which C2 ignores) — proceed.
+    }
+    else {
+        // --re-scaffold: list every file that would be RE-ADDED before writing
+        // (Req 15A.3's flag: "resurrection is never silent even when chosen").
+        const wouldReadd = await previewReScaffold(pkgRoot, dest, opts);
+        if (wouldReadd.length > 0) {
+            console.log(`--re-scaffold: the following files will be RE-ADDED (they do not exist in this repo today):`);
+            for (const relPath of wouldReadd) {
+                console.log(`  - ${relPath}`);
+            }
+            const confirmed = await confirmReScaffold(opts.yes ?? false);
+            if (!confirmed) {
+                console.log('Aborted — nothing was written.');
+                return;
+            }
+        }
+    }
     if (!opts.name) {
         opts.name = await prompt('Product name: ');
     }
@@ -59,84 +181,145 @@ async function runInit(argv) {
     if (!opts.name || !opts.abbreviation) {
         console.error('❌ Name and abbreviation are required.');
         process.exit(1);
+        return;
     }
-    const pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(__dirname);
-    const dest = process.cwd();
-    // 1. .npmrc
-    createFileIfNotExists(path.join(dest, '.npmrc'), '@3fn:registry=https://npm.pkg.github.com\n', '.npmrc');
-    // 2. designerpunk.config.ts
-    createFileIfNotExists(path.join(dest, 'designerpunk.config.ts'), generateConfig(opts.name, opts.abbreviation), 'designerpunk.config.ts (dark + wcag themes registered)');
-    // 3. Token source (types ship alongside for relative import resolution)
-    const typesResult = copyDir(path.join(pkgRoot, 'src/types'), path.join(dest, 'src/types'), { exclude: ['__tests__', 'generated'] });
-    reportCopy('type definitions', typesResult);
-    // 3b. Token source — primitives and semantics (no transform needed; ../types/ resolves naturally)
-    const tokensResult = copyDir(path.join(pkgRoot, 'src/tokens'), path.join(dest, 'src/tokens'), { exclude: ['__tests__', 'component'] });
+    const manifest = new ManifestBuilder();
+    // No .npmrc scaffold: @3fn resolves from public npm (the primary registry,
+    // ruled 2026-09-20). A scoped registry mapping here would silently pin every
+    // consumer to GitHub Packages — see .kiro/issues/archive/2026-09-20-init-npmrc-registry-pin.md
+    // --- Step 2: designerpunk.config.ts (KEPT; couplings re-pointed per 1.2) ---
+    const configPath = path.join(dest, 'designerpunk.config.ts');
+    const configCreated = createFileIfNotExists(configPath, generateConfig(opts.name, opts.abbreviation), 'designerpunk.config.ts (dark + wcag themes registered)');
+    if (configCreated)
+        manifest.recordFile('designerpunk.config.ts', configPath, 'generated');
+    // --- Step 3: src/types — REMOVED (19A.3). Resolves via @3fn/core/types (C4). ---
+    // (no copyDir call — see rewriteByResolution's mapping table, Task 2.1)
+    // --- Step 3b: src/tokens (full tree) — KEPT + TRANSFORM (rewriteByResolution) ---
+    // The boundary is the WHOLE copied tier (src/tokens) for BOTH 3b and 3c (C4;
+    // Ada R2 pre-implementation fix) — never each copy step's own root.
+    const tierRoot = path.join(pkgRoot, 'src', 'tokens');
+    const tokensResult = copyDir(tierRoot, path.join(dest, 'src/tokens'), { exclude: ['__tests__', 'component'], transform: (content, srcAbsPath) => (0, transforms_1.rewriteByResolution)(content, srcAbsPath, tierRoot).content });
     reportCopy('token source', tokensResult);
-    // 3c. Token source — component tokens (with build import transform)
-    const componentTokensResult = copyDir(path.join(pkgRoot, 'src/tokens/component'), path.join(dest, 'src/tokens/component'), { exclude: ['__tests__'], transform: transforms_1.rewriteBuildImports });
+    // --- Step 3c: src/tokens/component — KEPT + TRANSFORM (same tier boundary) ---
+    const componentTokensResult = copyDir(path.join(pkgRoot, 'src/tokens/component'), path.join(dest, 'src/tokens/component'), { exclude: ['__tests__'], transform: (content, srcAbsPath) => (0, transforms_1.rewriteByResolution)(content, srcAbsPath, tierRoot).content });
     reportCopy('component tokens (token source)', componentTokensResult);
-    // 4. Components (with build import transform for token files)
-    if (!opts.skipComponents) {
-        const compResult = copyDir(path.join(pkgRoot, 'src/components/core'), path.join(dest, 'src/components/core'), { exclude: ['__tests__'], transform: transforms_1.rewriteBuildImports });
-        reportCopy('starter components', compResult);
+    // --- Step 4: src/components/core — REMOVED (Req 2's union replaces it) ---
+    if (opts.skipComponents) {
+        console.log('  note: --skip-components is a deprecated no-op — src/components/core is no longer copied (Requirement 2\'s component union replaces it).');
+    }
+    // --- Step 4′: consumer components dir — ADDED (Req 19A.6: created, empty) ---
+    const consumerComponentsDir = path.join(dest, 'src/components');
+    const consumerComponentsReadme = path.join(consumerComponentsDir, 'README.md');
+    if (!fs.existsSync(consumerComponentsDir)) {
+        fs.mkdirSync(consumerComponentsDir, { recursive: true });
+    }
+    const readmeCreated = createFileIfNotExists(consumerComponentsReadme, CONSUMER_COMPONENTS_README, 'src/components/README.md');
+    if (readmeCreated)
+        manifest.recordFile('src/components/README.md', consumerComponentsReadme, 'generated');
+    // --- Step 5: product/overview.yaml — UNCHANGED in U1 (Task 22 replaces it) ---
+    const overviewPath = path.join(dest, 'product/overview.yaml');
+    const overviewCreated = createFileIfNotExists(overviewPath, generateOverview(opts.name), 'product/overview.yaml');
+    if (overviewCreated)
+        manifest.recordFile('product/overview.yaml', overviewPath, 'generated');
+    // --- Step 6 (new): the agent layer + MCP config for the selected target — `attach`'s code
+    // path (`emitAgentLayer`, C1's "(new) agent layer" row; C20). Replaces release-1's copy
+    // rows 6/7/7b (`.kiro/agents`, `.kiro/steering`, `governance`) and row 8's both-target MCP
+    // emission: ONE target's charters, identity member files, skill trees, `CLAUDE.md` region,
+    // MCP config and approvals. Every file and key it writes is recorded into the manifest
+    // (`origin: 'generated'` / `'emitted-key'`) and the target joins `attachedTargets` — only
+    // when the agent files were emitted (`--skip-agents` leaves it out). ----------------------
+    if (opts.skipAgents) {
+        console.log('  note: --skip-agents omits the agent layer (the target\'s MCP config is still wired; it is not recorded as attached — run `npx designerpunk attach --target=<cc|kiro>` to add it).');
     }
-    // 5. product/overview.yaml
-    createFileIfNotExists(path.join(dest, 'product/overview.yaml'), generateOverview(opts.name), 'product/overview.yaml');
-    // 6. Agent templates
+    const layer = await (0, attach_1.emitAgentLayer)({
+        pkgRoot,
+        repoRoot: dest,
+        requestedTarget: opts.target,
+        mode: 'birth',
+        manifest: manifest.state,
+        verb: 'init',
+        skipAgentFiles: opts.skipAgents ?? false,
+        adoptIdentical: true, // `--re-scaffold` over her own generated files: identical bytes are claimed, never reported as collisions
+    });
     if (!opts.skipAgents) {
-        const agentsResult = copyDir(path.join(pkgRoot, '.kiro/agents'), path.join(dest, '.kiro/agents'));
-        reportCopy('agent templates', agentsResult);
+        const parts = [`${layer.written} file${layer.written === 1 ? '' : 's'} written`];
+        if (layer.unchanged > 0)
+            parts.push(`${layer.unchanged} unchanged`);
+        if (layer.collided > 0)
+            parts.push(`${layer.collided} skipped (see warnings above)`);
+        console.log(`✓ Agent layer (${layer.target}): ${parts.join(', ')}`);
     }
-    // 7. Steering docs (identity docs — stay in .kiro/steering/ per Spec 119-A)
-    const steeringResult = copyDir(path.join(pkgRoot, '.kiro/steering'), path.join(dest, '.kiro/steering'));
-    reportCopy('steering docs', steeringResult);
-    // 7b. Governance docs (relocated non-identity corpus — Spec 119-A two-root split)
-    const governanceResult = copyDir(path.join(pkgRoot, 'governance'), path.join(dest, 'governance'));
-    reportCopy('governance docs', governanceResult);
-    // 8. .kiro/settings/mcp.json — scaffold MCP config from canonical template
-    scaffoldMcpConfig(path.join(pkgRoot, 'src/cli/templates/mcp-config.json.template'), path.join(dest, '.kiro/settings/mcp.json'));
-    // 9. Test configuration
-    createFileIfNotExists(path.join(dest, 'jest.config.js'), `module.exports = {\n  ...require('@3fn/core/jest-preset'),\n  roots: ['<rootDir>/src'],\n};\n`, 'jest.config.js');
-    createFileIfNotExists(path.join(dest, 'tsconfig.test.json'), JSON.stringify({
+    // --- Step 9: test configuration — KEPT, purpose stated (C27 A13) ---
+    const jestConfigPath = path.join(dest, 'jest.config.js');
+    const jestConfigCreated = createFileIfNotExists(jestConfigPath, `module.exports = {\n  ...require('@3fn/core/jest-preset'),\n  roots: ['<rootDir>/src'],\n};\n`, 'jest.config.js', (0, errorCatalog_1.jestConfigCollisionMessage)());
+    if (jestConfigCreated)
+        manifest.recordFile('jest.config.js', jestConfigPath, 'generated');
+    // No `paths` overrides: subpath types resolve through the package exports map
+    // to compiled dist d.ts (Spec 118). Re-pinning them to raw src/ undoes the
+    // package's own resolution contract — see
+    // .kiro/issues/archive/2026-09-20-init-tsconfig-src-repin.md
+    const tsconfigTestPath = path.join(dest, 'tsconfig.test.json');
+    const tsconfigTestCreated = createFileIfNotExists(tsconfigTestPath, JSON.stringify({
         compilerOptions: {
             target: 'ES2020',
-            module: 'commonjs',
-            moduleResolution: 'bundler',
+            // Spec 123 Task 2.5: `node16` resolves `@3fn/core/*` subpaths through
+            // the package's `exports` map (`bundler` would too, but requires
+            // `module` >= es2015/preserve — TS5095 — which would make ts-jest's
+            // runtime transform (jest-preset.ts reads THIS tsconfig) emit ESM
+            // `import`/`export`, which Jest's default CommonJS module system
+            // cannot execute). `node16`, unlike plain `commonjs`, understands
+            // `exports` maps while still emitting CommonJS for a package with no
+            // `"type": "module"` (verified: a `.ts` file compiles to `"use
+            // strict"; Object.defineProperty(exports, ...)`).
+            module: 'node16',
+            moduleResolution: 'node16',
             strict: true,
             esModuleInterop: true,
             skipLibCheck: true,
             resolveJsonModule: true,
             downlevelIteration: true,
             types: ['jest', 'node'],
-            baseUrl: '.',
-            paths: {
-                '@3fn/core/blend': ['./node_modules/@3fn/core/src/blend/index.ts'],
-                '@3fn/core/build': ['./node_modules/@3fn/core/src/build/tokens/index.ts'],
-                '@3fn/core/types': ['./node_modules/@3fn/core/src/types/index.ts'],
-                '@3fn/core/testing': ['./node_modules/@3fn/core/src/testing/index.ts'],
-                '@3fn/core/config': ['./node_modules/@3fn/core/src/config/index.ts'],
-            },
         },
         include: ['src/**/*'],
     }, null, 2) + '\n', 'tsconfig.test.json');
-    // 10. .designerpunkignore
-    createFileIfNotExists(path.join(dest, '.designerpunkignore'), `# DesignerPunk Sync Ignore
+    if (tsconfigTestCreated)
+        manifest.recordFile('tsconfig.test.json', tsconfigTestPath, 'generated');
+    // --- Step 10: .designerpunkignore — KEPT (C1 row 10); its example comment names the
+    // generated agent files a consumer may want to keep edits to (Task 16.3). The comment is
+    // text only: sync never reads a package copy of this file, so an unedited release-1
+    // `.designerpunkignore` is not reclassified by this change. ----------------------------
+    const ignorePath = path.join(dest, '.designerpunkignore');
+    const ignoreCreated = createFileIfNotExists(ignorePath, `# DesignerPunk Sync Ignore
 # Files listed here are never touched by \`npx designerpunk sync\`.
 # Uses .gitignore syntax: globs, exact paths, # comments.
 
-# Example: keep a custom agent prompt
-# .kiro/agents/custom-agent.md
+# Example: keep your edits to a generated agent file (sync would otherwise offer to overwrite it)
+# .claude/agents/ada.md
+# .kiro/agents/ada.json
+# .kiro/agents/ada-prompt.md
+# Agents you write yourself are never managed and need no entry here.
 `, '.designerpunkignore');
-    // 11. Next steps
+    if (ignoreCreated)
+        manifest.recordFile('.designerpunkignore', ignorePath, 'generated');
+    // --- Manifest — written LAST (design.md C1's manifest row): every file and key above,
+    // including the generated agent layer and the MCP config keys ----------------------------
+    const installedVersion = readPackageVersion(pkgRoot);
+    const manifestPath = path.join(dest, 'designerpunk.manifest.json');
+    // Serialized by sync's manifest writer (stable order, one entry per line — C7), so the first sync does not rewrite it.
+    fs.writeFileSync(manifestPath, (0, Manifest_1.serializeManifest)(manifest.build(installedVersion, (0, NameContract_1.readContractHash)(pkgRoot))), 'utf-8');
+    console.log('✓ Created designerpunk.manifest.json');
+    // --- Next steps (C27 erratum; Req 15.8, 15.9, 19.6) ----------------------
+    printNextSteps(opts.name);
+}
+/** The U1 terminal output — every line true of what U1's `init` actually did, with the sequenced restart row printed LAST (C27 erratum, Le-T5). */
+function printNextSteps(name) {
     console.log(`
-Your product "${opts.name}" is ready.
+Your product "${name}" is ready.
 
 Next steps:
-  1. Set GITHUB_TOKEN env var (read:packages scope)
-  2. npm install
-  3. npm install --save-dev jest @types/jest ts-jest jest-environment-jsdom
-  4. npx designerpunk generate      # Generate platform tokens
-  5. npx jest                        # Run component tests
+  1. npm install
+  2. npm install --save-dev jest @types/jest ts-jest jest-environment-jsdom
+  3. npx designerpunk generate
 
 To customize your visual language:
   • Edit src/tokens/ to change base values and design intent
@@ -147,11 +330,21 @@ baseline grid). The validator will warn if changes break these
 relationships during generation.
 
 💡 After future upgrades, run \`npx designerpunk sync\` to apply updates.
+
+${(0, errorCatalog_1.cloneHatchMessage)()}
+
+${(0, errorCatalog_1.personalNoteNamingMessage)()}
+
+${(0, errorCatalog_1.restartLineSequencedMessage)()}
 `);
 }
 function parseInitArgs(argv) {
     const opts = {};
     for (let i = 0; i < argv.length; i++) {
+        if (argv[i].startsWith('--target=')) {
+            opts.target = argv[i].slice('--target='.length);
+            continue;
+        }
         switch (argv[i]) {
             case '--name':
                 opts.name = argv[++i];
@@ -165,6 +358,15 @@ function parseInitArgs(argv) {
             case '--skip-agents':
                 opts.skipAgents = true;
                 break;
+            case '--re-scaffold':
+                opts.reScaffold = true;
+                break;
+            case '--target':
+                opts.target = argv[++i];
+                break;
+            case '--yes':
+                opts.yes = true;
+                break;
         }
     }
     return opts;
@@ -178,14 +380,92 @@ function prompt(question) {
         });
     });
 }
-function createFileIfNotExists(filePath, content, label) {
+/**
+ * Ask for confirmation before a `--re-scaffold` write. On a TTY, prompts
+ * interactively. Off a TTY, requires `--yes` (Req 15A.3's flag semantics).
+ */
+async function confirmReScaffold(yesFlag) {
+    if (!process.stdin.isTTY) {
+        return yesFlag;
+    }
+    const answer = await prompt('Proceed and re-add the files listed above? [y/N] ');
+    return /^y(es)?$/i.test(answer);
+}
+/** Every root `init` still COPIES from, for the `--re-scaffold` preview: the token tree only. The agent layer is generated, not copied — its preview comes from the emission itself (`previewAgentLayerMissing`). */
+function copiedRoots(pkgRoot) {
+    return [{ src: path.join(pkgRoot, 'src/tokens'), dest: 'src/tokens', exclude: ['__tests__'] }];
+}
+/** List every file `init --re-scaffold` would (re-)add — i.e. every source file currently missing at its destination, plus every agent-layer file the emission would create. Never mutates the filesystem. */
+async function previewReScaffold(pkgRoot, dest, opts) {
+    const missing = [];
+    for (const root of copiedRoots(pkgRoot)) {
+        if (!fs.existsSync(root.src))
+            continue;
+        walkMissing(root.src, path.join(dest, root.dest), root.exclude ?? [], missing, dest);
+    }
+    if (!opts.skipAgents) {
+        missing.push(...(await (0, attach_1.previewAgentLayerMissing)(pkgRoot, dest, opts.target)));
+    }
+    const scaffoldFiles = [
+        'designerpunk.config.ts',
+        'product/overview.yaml',
+        'jest.config.js',
+        'tsconfig.test.json',
+        '.designerpunkignore',
+        'src/components/README.md',
+    ];
+    for (const relPath of scaffoldFiles) {
+        if (!fs.existsSync(path.join(dest, relPath))) {
+            missing.push(relPath);
+        }
+    }
+    return missing;
+}
+function walkMissing(src, dest, exclude, out, destRoot) {
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (exclude.includes(entry.name))
+            continue;
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            walkMissing(srcPath, destPath, exclude, out, destRoot);
+        }
+        else if (entry.isFile()) {
+            if (!fs.existsSync(destPath)) {
+                out.push(path.relative(destRoot, destPath));
+            }
+        }
+    }
+}
+function readPackageVersion(pkgRoot) {
+    try {
+        const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+        return typeof pkgJson.version === 'string' ? pkgJson.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+const CONSUMER_COMPONENTS_README = `# Your Components
+
+This directory is yours. Components you add here appear ALONGSIDE
+DesignerPunk's ecosystem components — never instead of them. A component
+you add with the same name as one of DesignerPunk's wins on that name
+(your fork), and everything else keeps coming from the package.
+
+DesignerPunk's own components are consumed by name via \`npm update\` —
+they are not copied here. See the install doc's "Your first component"
+section for the merge model.
+`;
+function createFileIfNotExists(filePath, content, label, collisionMessage) {
     if (fs.existsSync(filePath)) {
-        console.log(`  skipped: ${label} (already exists)`);
-        return;
+        console.log(collisionMessage ? `  ${collisionMessage}` : `  skipped: ${label} (already exists)`);
+        return false;
     }
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, content, 'utf-8');
     console.log(`✓ Created ${label}`);
+    return true;
 }
 const SKIPPED_FILE_LIST_THRESHOLD = 10;
 /**
@@ -198,6 +478,10 @@ const SKIPPED_FILE_LIST_THRESHOLD = 10;
  * - Missing destination directories are created as needed.
  * - Returns counts of added and skipped files for caller-side summary.
  *
+ * An `UnmappedSpecifierError` thrown by `opts.transform` propagates OUT of this
+ * function — the copy fails loudly (design.md C4) rather than writing a
+ * silently-broken file.
+ *
  * This replaces the previous directory-level skip behavior (Spec 102 Gap 3):
  * a pre-existing destination directory no longer blocks the copy; individual
  * file collisions are handled instead.
@@ -233,7 +517,7 @@ function copyDirRecursive(src, dest, opts, result) {
             else {
                 if (opts?.transform && basename.endsWith('.ts')) {
                     const content = fs.readFileSync(srcPath, 'utf-8');
-                    fs.writeFileSync(destPath, opts.transform(content), 'utf-8');
+                    fs.writeFileSync(destPath, opts.transform(content, srcPath), 'utf-8');
                 }
                 else {
                     fs.copyFileSync(srcPath, destPath);
@@ -268,85 +552,6 @@ function reportCopy(label, result) {
         }
     }
 }
-/**
- * Scaffold `.kiro/settings/mcp.json` from the canonical template (Spec 102 Gap 5).
- *
- * Three behaviors depending on destination state:
- *
- * 1. **Destination doesn't exist** → create from template verbatim. Consumers
- *    get DesignerPunk's two MCP entries (`designerpunk-docs`, `designerpunk-application`)
- *    with full autoApprove arrays and direct-node invocation paths.
- *
- * 2. **Destination exists, neither DesignerPunk entry present** → merge: add
- *    the two DesignerPunk entries to the existing `mcpServers` object, preserving
- *    any other consumer-configured MCPs.
- *
- * 3. **Destination exists, one or both DesignerPunk entries already present** →
- *    skip the conflicting entries with a prominent warning. Don't overwrite —
- *    consumer customizations are sacred. Any NOT-yet-present DesignerPunk entry
- *    is still added (partial merge).
- *
- * NOTE: The output format emitted here is part of Gap 5's public behavior —
- * asserted by the integration test at `src/cli/__tests__/init.test.ts`.
- */
-function scaffoldMcpConfig(templatePath, destPath) {
-    if (!fs.existsSync(templatePath)) {
-        console.log(`  warning: MCP config template not found at ${templatePath}`);
-        return;
-    }
-    const templateContent = fs.readFileSync(templatePath, 'utf-8');
-    let template;
-    try {
-        template = JSON.parse(templateContent);
-    }
-    catch {
-        console.log(`  warning: MCP config template at ${templatePath} is not valid JSON`);
-        return;
-    }
-    // Case 1: destination doesn't exist — create from template verbatim
-    if (!fs.existsSync(destPath)) {
-        fs.mkdirSync(path.dirname(destPath), { recursive: true });
-        fs.writeFileSync(destPath, templateContent, 'utf-8');
-        const keys = Object.keys(template.mcpServers).join(' + ');
-        console.log(`✓ Created .kiro/settings/mcp.json (${keys})`);
-        return;
-    }
-    // Cases 2 + 3: destination exists — merge carefully
-    let existingRaw;
-    let existing;
-    try {
-        existingRaw = fs.readFileSync(destPath, 'utf-8');
-        existing = JSON.parse(existingRaw);
-    }
-    catch {
-        console.log(`  warning: .kiro/settings/mcp.json exists but is not valid JSON; leaving unchanged`);
-        return;
-    }
-    if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
-        existing.mcpServers = {};
-    }
-    const added = [];
-    const skipped = [];
-    for (const [key, value] of Object.entries(template.mcpServers)) {
-        if (key in existing.mcpServers) {
-            skipped.push(key);
-        }
-        else {
-            existing.mcpServers[key] = value;
-            added.push(key);
-        }
-    }
-    if (added.length > 0) {
-        fs.writeFileSync(destPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
-        console.log(`✓ .kiro/settings/mcp.json: added ${added.join(' + ')}`);
-    }
-    else if (skipped.length === Object.keys(template.mcpServers).length) {
-        console.log(`  skipped: .kiro/settings/mcp.json (all DesignerPunk entries already present)`);
-    }
-    for (const key of skipped) {
-        console.log(`  ⚠️  .kiro/settings/mcp.json already has '${key}' entry; left unchanged. If outdated, delete the entry and re-run init, or update manually.`);
-    }
-}
 function generateConfig(name, abbreviation) {
     return `import { defineConfig } from '@3fn/core/config';
 import { darkSemanticOverrides } from './src/tokens/themes/dark/SemanticOverrides.ts';
@@ -356,7 +561,7 @@ export default defineConfig({
   name: '${name}',
   abbreviation: '${abbreviation}',
   tokenSource: './src/tokens',
-  componentTokens: ['./src/components/core', './src/tokens/component'],
+  componentTokens: ['./src/components', './src/tokens/component'],
   themes: [
     { name: 'dark', mode: 'dark', overrides: darkSemanticOverrides },
     { name: 'wcag', mode: 'light', overrides: wcagSemanticOverrides },

package/dist/cli/loadComponentTokens.d.ts

@@ -43,4 +43,29 @@ import type { RegisteredComponentToken } from '../registries/ComponentTokenRegis
  *   loader (a plain `require`). See {@link scopedTsRequire} for why.
  */
 export declare function loadComponentTokens(config: ResolvedConfig, loadModule?: TsModuleLoader): RegisteredComponentToken[];
+/**
+ * A component-token module threw while it loaded — most often `defineComponentTokens`'s
+ * own guard (e.g. the family-mismatch guard, #127) rejecting a call at module scope.
+ * Carries the FILE, which the guard's message does not name (it names the component), so
+ * `generate` can report the file in a catalogued message instead of escaping to the CLI's
+ * "Unexpected error" stack trace (`.kiro/issues/2026-10-02-generate-stack-trace-on-component-token-family-mismatch.md`).
+ * `name` is set explicitly so callers may recognise it without `instanceof`.
+ */
+export declare class ComponentTokenFileLoadError extends Error {
+    readonly file: string;
+    readonly reason: string;
+    constructor(file: string, reason: string);
+}
+/**
+ * The harvest-zero lint's warning message (Spec 123 C11, Req 8).
+ *
+ * NOTE: design.md's C11 entry is "Unchanged" and carries no exact-string catalog row for
+ * this warning (unlike most 123 catalog strings elsewhere in the spec). This wording
+ * follows design-outline.md § 4.5's proposed phrasing as closely as an implementation
+ * string can: *"this scanned file harvested zero component tokens; if you meant to
+ * register values, call `defineComponentTokens`"* (Lina, R1). Flagged for a Thurgood
+ * erratum to add the row to design.md's catalog rather than leaving this the sole source
+ * of truth for the string.
+ */
+export declare function harvestZeroWarning(file: string): string;
 //# sourceMappingURL=loadComponentTokens.d.ts.map