@3fn/core 14.1.0 → 15.0.0

package/dist/cli/attach.js

@@ -0,0 +1,423 @@
+"use strict";
+/**
+ * `npx designerpunk attach` — attach a harness (agents + MCP config + approvals)
+ * for one target (Spec 123 Task 16.2; design.md § "C20. The consumer emission
+ * lane — shipped inputs only"; C1's "(new) agent layer" row; C7's manifest).
+ *
+ * Unlike `init` (the once-ever birth event), `attach` is SAFE TO RE-RUN: it
+ * regenerates a target's agent layer and MCP wiring, and running it again on an
+ * already-attached target changes nothing it would not have written identically
+ * (19.8's collision rule governs what is "ours" to regenerate versus a path the
+ * consumer occupies with her own content).
+ *
+ * **Modes** (C20):
+ * - **born repo, no `--reference`** → full emission: the agent layer (charters,
+ *   identity member files, skill trees, the CLAUDE.md always-layer region) for
+ *   the selected target, plus that target's MCP config + approvals (all three
+ *   servers — the same shape `init` emits).
+ * - **`--reference`** (works regardless of birth state) → the CONSUME posture's
+ *   mechanical wiring: MCP config + approvals for ONLY the docs and application
+ *   servers (never `designerpunk-product`, and no agents, no birth). Writes a
+ *   `posture: 'consume'` manifest, which `findDesignSystemRoot` (C2) IGNORES as
+ *   a birth signal — a second `--reference` run re-runs clean, and a later
+ *   `init` still births (design.md C6: "attach --reference stays CONSUME").
+ * - **unborn, no `--reference`** → refuse, naming both paths (the catalog row).
+ * - **partial** → the partial-case message (shared with `init`/`generate`).
+ *
+ * **`attach` never appears without its object** (C20, DD4) — see
+ * `./shared/vocabulary.ts`'s `attachUsage()`, used at this file's dispatch
+ * point (`designerpunk.ts`'s help text) and already present verbatim in
+ * `initBornRepoMessage`'s catalog string.
+ *
+ * APPLICATION-TIME ADAPTATION (recorded in the Task 16.2 completion doc):
+ * design.md's C20 "Modes" list names only `born` / `--reference` / `unborn` /
+ * `partial`. `package-mode` (C2's own posture — a config without `tokenSource`)
+ * is unaddressed there. This module treats `package-mode` the same as `born`
+ * for `attach`'s purposes: attach is about the agent harness, not the token
+ * tier, and a `package-mode` repo already has a real `designerpunk.config.ts`,
+ * which is what "a design system here" means for this command. CONFIRMED by
+ * the PRIMARY at Task 16.5 (DD23 made `package-mode` a posture, not a partial;
+ * C20's Modes list predates that split).
+ *
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C20. The consumer emission lane"
+ * @see .kiro/specs/123-consumer-distribution/design.md § "C7. `sync` … Manifest"
+ */
+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.AttachManifestRecorder = exports.REFERENCE_SERVERS = void 0;
+exports.emitAgentLayer = emitAgentLayer;
+exports.previewAgentLayerMissing = previewAgentLayerMissing;
+exports.attachRefusal = attachRefusal;
+exports.runAttach = runAttach;
+exports.parseAttachArgs = parseAttachArgs;
+exports.resolveTarget = resolveTarget;
+exports.resolveAgentTarget = resolveAgentTarget;
+exports.applyEmittedFile = applyEmittedFile;
+exports.referenceOnlyTemplate = referenceOnlyTemplate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const resolvePackageRoot_1 = require("./shared/resolvePackageRoot");
+const bornRepo_1 = require("./shared/bornRepo");
+const errorCatalog_1 = require("./shared/errorCatalog");
+const kiro_1 = require("./shared/mcpConfig/kiro");
+const cc_1 = require("./shared/mcpConfig/cc");
+const Manifest_1 = require("./sync/Manifest");
+const NameContract_1 = require("./sync/NameContract");
+const RegionGrain_1 = require("./sync/RegionGrain");
+const crypto = __importStar(require("crypto"));
+function parseAttachArgs(argv) {
+    const opts = {};
+    for (const arg of argv) {
+        if (arg === '--reference') {
+            opts.reference = true;
+        }
+        else if (arg.startsWith('--target=')) {
+            opts.target = arg.slice('--target='.length);
+        }
+    }
+    return opts;
+}
+/** Load the compiled generator bundle an installed package ships (C20, C9). */
+function loadConsumerEntry(pkgRoot) {
+    const bundlePath = path.join(pkgRoot, 'dist/generator/consumer-entry.js');
+    if (!fs.existsSync(bundlePath)) {
+        throw new Error(`attach: the installed package has no dist/generator/consumer-entry.js — it was packed without its ` +
+            `prepack build. Run 'npm run build' in the package, or reinstall it.`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(bundlePath);
+}
+/** Resolve the target to act on: the requested `--target`, else the profile's declared default (DD9). Throws, naming the declared set, on an undeclared target. `verb` names the calling command in the message (`attach` by default; `init` passes its own). */
+function resolveTarget(requested, profile, verb = 'attach') {
+    const target = requested ?? profile.defaultTarget;
+    if (!profile.targets.includes(target)) {
+        throw new Error(`${verb}: target "${target}" is not declared by the installed package (declared: ${profile.targets.join(', ')})`);
+    }
+    return target;
+}
+/**
+ * Load the shipped consumer-entry bundle and resolve the target against the PACKAGED consumer
+ * profile (`loadConsumerProfile`'s packaged form — C12's single declared list; never a literal
+ * target list). `init` calls this up front so an undeclared `--target` or an unbuilt package
+ * fails before it writes anything; `emitAgentLayer` calls it again (the require is cached).
+ */
+function resolveAgentTarget(pkgRoot, requested, verb = 'attach') {
+    const entry = loadConsumerEntry(pkgRoot);
+    const profile = entry.loadPackagedConsumerProfile(pkgRoot);
+    return { entry, target: resolveTarget(requested, profile, verb), profile };
+}
+// ---------------------------------------------------------------------------
+// Manifest helpers
+// ---------------------------------------------------------------------------
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+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';
+    }
+}
+/** A brand-new manifest, for a repo `attach` meets with none yet (design.md C7's fields). */
+function freshManifest(pkgRoot, posture) {
+    return {
+        version: Manifest_1.MANIFEST_SCHEMA_VERSION,
+        posture,
+        installedVersion: readPackageVersion(pkgRoot),
+        contractHash: (0, NameContract_1.readContractHash)(pkgRoot),
+        attachedTargets: [],
+        entries: {},
+    };
+}
+/** Loads the manifest if present and readable, else a fresh one of `posture`. Refuses loudly on a corrupt manifest — never silently rebuilt (mirrors `sync`'s own rule; `Manifest.ts`'s header). */
+function loadOrCreateManifest(repoRoot, pkgRoot, posture) {
+    const load = (0, Manifest_1.loadManifest)(repoRoot);
+    if (load.kind === 'ok')
+        return load.manifest;
+    if (load.kind === 'corrupt') {
+        throw new Error(`attach: designerpunk.manifest.json at ${repoRoot} is not readable (${load.error}) — restore it from ` +
+            `version control before running attach.`);
+    }
+    return freshManifest(pkgRoot, posture);
+}
+/** `McpConfigManifestRecorder` over a `DesignerPunkManifest`'s `entries` (mirrors `init.ts`'s `ManifestBuilder`, scoped to recording — `attach` updates an EXISTING manifest rather than building a fresh one). */
+class AttachManifestRecorder {
+    constructor(manifest) {
+        this.manifest = manifest;
+    }
+    recordFile(relPath, absPath, origin) {
+        const content = fs.readFileSync(absPath, 'utf-8');
+        this.manifest.entries[(0, Manifest_1.toManifestPath)(relPath)] = { hash: hashContent(content), grain: 'file', origin };
+    }
+    recordKey(relPath, key, value) {
+        const keyPath = `${(0, Manifest_1.toManifestPath)(relPath)}#${key}`;
+        this.manifest.entries[keyPath] = { hash: hashContent(JSON.stringify(value)), grain: 'key', origin: 'emitted-key' };
+    }
+}
+exports.AttachManifestRecorder = AttachManifestRecorder;
+function recordEntry(manifest, key, entry) {
+    manifest.entries[(0, Manifest_1.toManifestPath)(key)] = entry;
+}
+/** Apply one `emitConsumer`-returned file-grain output. Never overwrites a path the manifest does not already attribute to DesignerPunk (Req 19.8: report the collision, never silently skip or overwrite). */
+function applyFileGrain(repoRoot, file, manifest, adoptIdentical = false) {
+    const abs = path.join(repoRoot, file.path);
+    const manifestKey = (0, Manifest_1.toManifestPath)(file.path);
+    const recorded = Object.prototype.hasOwnProperty.call(manifest.entries, manifestKey) ? manifest.entries[manifestKey] : undefined;
+    // Task 16.5: a release-1 COPY on a generated path (Kiro's `.kiro/agents/<a>.json`) is ours to replace only
+    // while its bytes still equal the copy recorded — an edited copy is hers (19.8: reported, never overwritten).
+    const alreadyOurs = recorded !== undefined &&
+        (recorded.origin !== 'copy' || (fs.existsSync(abs) && hashContent(fs.readFileSync(abs, 'utf-8')) === recorded.hash));
+    // `adoptIdentical` (init's `--re-scaffold` over a born repo's own generated files): a path that already holds
+    // EXACTLY the bytes about to be written is claimed, not reported — nothing is overwritten either way.
+    const identical = adoptIdentical && fs.existsSync(abs) && fs.readFileSync(abs, 'utf-8') === file.content;
+    if (fs.existsSync(abs) && !alreadyOurs && !identical) {
+        console.log(`  ⚠️  skipped: ${file.path} already exists and was not generated by DesignerPunk — not overwriting ` +
+            `(Req 19.8). Move it aside and re-run attach to let DesignerPunk generate it.`);
+        return 'collision';
+    }
+    const prior = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : undefined;
+    recordEntry(manifest, file.path, { hash: hashContent(file.content), grain: 'file', origin: 'generated' });
+    if (prior === file.content)
+        return 'unchanged';
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, file.content, 'utf-8');
+    return 'written';
+}
+/**
+ * Apply one `emitConsumer`-returned region-grain output (today: `CLAUDE.md`'s always-layer region — C19/C20).
+ * - the file is absent → created holding only the region (markers included);
+ * - the file exists with the marker pair → the region is spliced, outside bytes untouched;
+ * - the file exists WITHOUT markers and the manifest records NO region for it (the first attach into a
+ *   consumer's own `CLAUDE.md`) → the region is appended after her bytes, which stay in place (Task 16.5
+ *   correction: 16.2 reported this as "markers missing", so a consumer with an existing `CLAUDE.md` never
+ *   got the always-layer);
+ * - the file exists without markers but the manifest DOES record the region → the catalog's
+ *   "markers missing" string; nothing is written (she removed them — never re-appended over her choice).
+ * The region entry's hash is over `normalizeRegionContent` (the form `sync` compares).
+ */
+function applyRegionGrain(repoRoot, file, manifest) {
+    const abs = path.join(repoRoot, file.path);
+    const markers = (0, RegionGrain_1.regionMarkers)(file.path.endsWith('.md') ? RegionGrain_1.CLAUDE_MD_COMMENT : RegionGrain_1.GITIGNORE_COMMENT);
+    const manifestKey = `${(0, Manifest_1.toManifestPath)(file.path)}#managed`;
+    const entry = { hash: hashContent((0, RegionGrain_1.normalizeRegionContent)(file.content)), grain: 'region', origin: 'generated' };
+    if (!fs.existsSync(abs)) {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, (0, RegionGrain_1.wrapRegion)(markers, file.content), 'utf-8');
+        recordEntry(manifest, manifestKey, entry);
+        return 'written';
+    }
+    const existing = fs.readFileSync(abs, 'utf-8');
+    const recorded = Object.prototype.hasOwnProperty.call(manifest.entries, manifestKey);
+    if (!recorded && !(0, RegionGrain_1.extractRegion)(existing, markers).found) {
+        fs.writeFileSync(abs, (0, RegionGrain_1.appendRegion)(existing, markers, file.content), 'utf-8');
+        recordEntry(manifest, manifestKey, entry);
+        return 'written';
+    }
+    const result = (0, RegionGrain_1.spliceRegion)(existing, markers, file.content, file.path);
+    if (!result.ok) {
+        console.log(`  ⚠️  ${result.message}`);
+        return 'collision';
+    }
+    recordEntry(manifest, manifestKey, entry);
+    if (result.text === existing)
+        return 'unchanged';
+    fs.writeFileSync(abs, result.text, 'utf-8');
+    return 'written';
+}
+function applyEmittedFile(repoRoot, file, manifest, adoptIdentical = false) {
+    return file.grain === 'region' ? applyRegionGrain(repoRoot, file, manifest) : applyFileGrain(repoRoot, file, manifest, adoptIdentical);
+}
+// ---------------------------------------------------------------------------
+// MCP template
+// ---------------------------------------------------------------------------
+function readMcpTemplate(templatePath) {
+    if (!fs.existsSync(templatePath)) {
+        console.log(`  warning: MCP config template not found at ${templatePath}`);
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(templatePath, 'utf-8'));
+    }
+    catch {
+        console.log(`  warning: MCP config template at ${templatePath} is not valid JSON`);
+        return null;
+    }
+}
+/** `--reference`'s servers (C20): the docs and application servers only — never `designerpunk-product`. `sync` reads it too (a consume-posture manifest's package-side keys). */
+exports.REFERENCE_SERVERS = Object.freeze(['designerpunk-docs', 'designerpunk-application']);
+/** `--reference`'s scope (C20): the docs and application servers only — never `designerpunk-product`, and no agents. */
+function referenceOnlyTemplate(template) {
+    const allow = new Set(exports.REFERENCE_SERVERS);
+    const mcpServers = {};
+    for (const [key, value] of Object.entries(template.mcpServers)) {
+        if (allow.has(key))
+            mcpServers[key] = value;
+    }
+    return { mcpServers };
+}
+function scaffoldMcpConfig(target, template, repoRoot, pkgRoot, recorder) {
+    if (target === 'kiro') {
+        (0, kiro_1.scaffoldKiroMcpConfig)(template, path.join(repoRoot, '.kiro/settings/mcp.json'), recorder, repoRoot, pkgRoot);
+    }
+    else {
+        (0, cc_1.scaffoldClaudeCodeMcpConfig)(template, repoRoot, recorder, pkgRoot);
+    }
+}
+/**
+ * THE agent-layer code path — `attach`'s full emission, and the row `init` calls for the selected
+ * target (design.md C1's "(new) agent layer" row: "`attach` code path for the selected target …
+ * returns its emitted file list"). One implementation, two callers: the agent layer (charters,
+ * identity member files, skill trees, the `CLAUDE.md` region) through `emitConsumer`, then that
+ * target's MCP config + approvals (all three servers), every file and key recorded into
+ * `manifest` (`origin: 'generated'` / `'emitted-key'`), and `target` added to
+ * `manifest.attachedTargets`.
+ *
+ * `skipAgentFiles` (`init --skip-agents`) omits the agent files AND the `attachedTargets` entry —
+ * the target is MCP-wired but not "attached" (the same line `attach --reference` draws), so
+ * generated-surface `sync` never expects agent files that were deliberately not emitted.
+ */
+async function emitAgentLayer(opts) {
+    const { pkgRoot, repoRoot, manifest } = opts;
+    const { entry, target } = resolveAgentTarget(pkgRoot, opts.requestedTarget, opts.verb);
+    const outcome = { target, files: [], written: 0, unchanged: 0, collided: 0, warnings: [] };
+    if (!opts.skipAgentFiles) {
+        const result = await entry.emitConsumer({ packageRoot: pkgRoot, consumerRoot: repoRoot, target, mode: opts.mode });
+        outcome.warnings = result.warnings;
+        for (const warning of result.warnings) {
+            console.log(`  ⚠️  ${warning}`);
+        }
+        for (const file of result.files) {
+            const applied = applyEmittedFile(repoRoot, file, manifest, opts.adoptIdentical ?? false);
+            if (applied === 'written')
+                outcome.written++;
+            else if (applied === 'unchanged')
+                outcome.unchanged++;
+            else
+                outcome.collided++;
+            if (applied !== 'collision')
+                outcome.files.push(file.path);
+        }
+    }
+    const mcpTemplate = readMcpTemplate(path.join(pkgRoot, 'src/cli/templates/mcp-config.json.template'));
+    if (mcpTemplate) {
+        scaffoldMcpConfig(target, mcpTemplate, repoRoot, pkgRoot, new AttachManifestRecorder(manifest));
+    }
+    if (!opts.skipAgentFiles && !manifest.attachedTargets.includes(target)) {
+        manifest.attachedTargets = [...manifest.attachedTargets, target];
+    }
+    return outcome;
+}
+/** The repo-relative paths an agent-layer emission for `target` would create that do not exist in `repoRoot` today — `init --re-scaffold`'s "RE-ADDED" preview (Req 15A.3). Reads the package only; writes nothing. */
+async function previewAgentLayerMissing(pkgRoot, repoRoot, requestedTarget) {
+    const { entry, target } = resolveAgentTarget(pkgRoot, requestedTarget, 'init');
+    const result = await entry.emitConsumer({ packageRoot: pkgRoot, consumerRoot: repoRoot, target, mode: 'birth' });
+    return result.files.map((f) => f.path).filter((p) => !fs.existsSync(path.join(repoRoot, p)));
+}
+/** Full emission (born / package-mode): the agent layer + the full three-server MCP wiring, for one target. */
+async function attachBorn(pkgRoot, repoRoot, requestedTarget) {
+    const manifest = loadOrCreateManifest(repoRoot, pkgRoot, 'born');
+    const { target, written, unchanged, collided } = await emitAgentLayer({
+        pkgRoot,
+        repoRoot,
+        requestedTarget,
+        mode: 'attach',
+        manifest,
+    });
+    (0, Manifest_1.saveManifest)(repoRoot, manifest);
+    const parts = [`${written} file${written === 1 ? '' : 's'} written`];
+    if (unchanged > 0)
+        parts.push(`${unchanged} unchanged`);
+    if (collided > 0)
+        parts.push(`${collided} skipped (see warnings above)`);
+    console.log(`✓ Attached ${target} — ${parts.join(', ')}`);
+    console.log('');
+    console.log((0, errorCatalog_1.restartLineSequencedMessage)());
+}
+/** `--reference`: MCP config + approvals for docs + application only, a `posture: 'consume'` manifest, no agents, no birth (C20, DD22). */
+async function attachReference(pkgRoot, repoRoot, requestedTarget) {
+    const entry = loadConsumerEntry(pkgRoot);
+    const profile = entry.loadPackagedConsumerProfile(pkgRoot);
+    const target = resolveTarget(requestedTarget, profile);
+    const manifest = loadOrCreateManifest(repoRoot, pkgRoot, 'consume');
+    const mcpTemplate = readMcpTemplate(path.join(pkgRoot, 'src/cli/templates/mcp-config.json.template'));
+    if (mcpTemplate) {
+        scaffoldMcpConfig(target, referenceOnlyTemplate(mcpTemplate), repoRoot, pkgRoot, new AttachManifestRecorder(manifest));
+    }
+    (0, Manifest_1.saveManifest)(repoRoot, manifest);
+    console.log(`✓ Reference-wired ${target} — MCP config + approvals (docs + application servers), no agents`);
+    console.log('');
+    console.log((0, errorCatalog_1.restartLineNowMessage)());
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * The refusal `attach` (no `--reference`) gives in `repoRoot`, or `null` when it would run (born or
+ * package-mode). One rule for `attach` itself and for `sync --migrate-legacy`'s attach step (Task 16.5),
+ * so `sync` never offers an attach that `attach` would refuse.
+ */
+function attachRefusal(repoRoot) {
+    const dsRoot = (0, bornRepo_1.findDesignSystemRoot)(repoRoot);
+    if (dsRoot.state === 'unborn')
+        return { message: (0, errorCatalog_1.attachUnbornRepoMessage)(), root: repoRoot };
+    if (dsRoot.state === 'partial' && dsRoot.partialCase) {
+        return { message: (0, errorCatalog_1.partialCaseMessage)(dsRoot.root ?? repoRoot, dsRoot.partialCase, dsRoot.attemptedTokenSource), root: repoRoot };
+    }
+    return { message: null, root: dsRoot.root ?? repoRoot };
+}
+async function runAttach(argv) {
+    const opts = parseAttachArgs(argv);
+    const dest = process.cwd();
+    const pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(__dirname);
+    // `--reference` works regardless of birth state (C20: "unborn, or an existing
+    // consume-posture repo"; the C6 "attach --reference stays CONSUME" case runs
+    // it a second time over an already-wired repo too — 16.6's test).
+    if (opts.reference) {
+        await attachReference(pkgRoot, dest, opts.target);
+        return;
+    }
+    const refusal = attachRefusal(dest);
+    if (refusal.message !== null) {
+        console.error(`❌ ${refusal.message}`);
+        process.exit(1);
+        return;
+    }
+    // born or package-mode (see this file's header note on the package-mode adaptation).
+    await attachBorn(pkgRoot, refusal.root, opts.target);
+}
+//# sourceMappingURL=attach.js.map

package/dist/cli/designerpunk.d.ts

@@ -11,10 +11,56 @@
  * @see Spec 094 design.md § "Pipeline CLI"
  * @see Spec 095 design.md § "CLI MCP Commands"
  */
+/** @internal Exported for testing — dispatch reachability (Spec 123 Task 16.2, instrument row 4.6). */
+export declare function main(): Promise<void>;
+/**
+ * Resolve the component-schema scan root the token-index's consumer map reads
+ * (Class C′, Spec 118 Task 9.5.2; Spec 123 U1 fix-up, 2026-09-26 —
+ * `.kiro/issues/2026-09-26-product-server-component-root.md`'s sibling defect).
+ *
+ * Design intent, confirmed against requirements.md Req 3.5 (the tasks-round text):
+ * "The Class C′ fixture SHALL be re-premised: it builds on the `src/components/core`
+ * copy, which Requirement 19A removes ... It SHALL be re-authored to build the
+ * consumer's component tree FROM NOTHING" — i.e. in a BORN repo, the consumer's own
+ * (Model B) component tree is `<bornRoot>/src/components`, never `.../core` (Req
+ * 19A.2 removes the `core` copy; Req 19A.6 creates `src/components/` directly,
+ * empty). The consumer map SHALL therefore reflect THAT tree, not a path `init`
+ * no longer writes to.
+ *
+ * Every other state (package-mode — including the steward repo's own dev-mode
+ * classification — partial, unborn) is UNCHANGED: `<configDir>/src/components/core`,
+ * exactly as before this fix. `generate` already refuses outright on `partial`
+ * before this function is ever called (see the caller), so only 'born' and
+ * 'package-mode'/'unborn' are live branches here in practice.
+ *
+ * Legacy `core/` level (born only): a pre-123 consumer who has not yet run
+ * `sync --migrate-components` may still have real components nested at
+ * `src/components/core/<Name>/` (the pre-123 copy layout). Mirrors
+ * `ComponentIndexer.collectComponentSources`'s own precedence (Task 1.4): a
+ * `core/` directory that is NOT itself a component dir but CONTAINS component
+ * dirs is a legacy level, used only when the flat (post-123) root holds none.
+ */
+export declare function resolveComponentSchemaDir(dsRoot: Pick<import('./shared/bornRepo').DesignSystemRoot, 'state' | 'root'>, configDir: string): string;
 /** @internal Exported for testing */
 export declare function runGenerate(force?: boolean): Promise<void>;
 /** @internal Exported for testing */
 export declare function runProductOnly(force?: boolean): Promise<void>;
+/**
+ * Spawn a server as a child process. Uses node for bundled JS, tsx for TypeScript.
+ *
+ * Spec 123 Task 1.3 (C2 D-B3 / C3):
+ * - **User-set data-root env wins**: `process.env` is spread AFTER `envVars`, so
+ *   any data-root value the invoking shell/harness already set (e.g. a user's own
+ *   `COMPONENTS_DIR`) is never shadowed by this runner's own defaults.
+ * - **No `cwd` option is passed** — load-bearing: the spawned server's
+ *   `process.cwd()` is whatever the launching harness set, and `findDesignSystemRoot`
+ *   (C2) requires that inherited cwd to walk from the right place.
+ *
+ * @internal Exported for testing.
+ */
+export declare function spawnServer(entryPoint: string, envVars: Record<string, string>, bundled?: boolean): void;
+/** @internal Exported for testing — the "attach never appears without its object" check (vocabulary.ts, Task 16.2). */
+export declare function printHelp(): void;
 /** @internal Entry point for bin/designerpunk.js */
 export declare const __main: () => void;
 //# sourceMappingURL=designerpunk.d.ts.map