@3fn/core 14.1.0 → 15.0.0

package/dist/cli/designerpunk.js

@@ -47,8 +47,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__main = void 0;
+exports.main = main;
+exports.resolveComponentSchemaDir = resolveComponentSchemaDir;
 exports.runGenerate = runGenerate;
 exports.runProductOnly = runProductOnly;
+exports.spawnServer = spawnServer;
+exports.printHelp = printHelp;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const child_process_1 = require("child_process");
@@ -59,12 +63,17 @@ const resolveTokens_1 = require("./resolveTokens");
 const loadComponentTokens_1 = require("./loadComponentTokens");
 const validate_1 = require("./validate");
 const init_1 = require("./init");
+const attach_1 = require("./attach");
 const validateProductTokens_1 = require("./validateProductTokens");
 const generateProductTokens_1 = require("./generateProductTokens");
 const ComponentTokenRegistry_1 = require("../registries/ComponentTokenRegistry");
 const staleness_1 = require("./staleness");
 const sync_1 = require("./sync");
 const resolvePackageRoot_1 = require("./shared/resolvePackageRoot");
+const bornRepo_1 = require("./shared/bornRepo");
+const errorCatalog_1 = require("./shared/errorCatalog");
+const vocabulary_1 = require("./shared/vocabulary");
+/** @internal Exported for testing — dispatch reachability (Spec 123 Task 16.2, instrument row 4.6). */
 async function main() {
     const command = process.argv[2];
     const flags = process.argv.slice(3);
@@ -84,6 +93,9 @@ async function main() {
         case 'init':
             await (0, init_1.runInit)(process.argv.slice(3));
             break;
+        case 'attach':
+            await (0, attach_1.runAttach)(process.argv.slice(3));
+            break;
         case 'mcp:app':
             await runMcpApp();
             break;
@@ -127,9 +139,101 @@ async function runValidateCommand() {
         process.exit(1);
     }
 }
+/**
+ * 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.
+ */
+function resolveComponentSchemaDir(dsRoot, configDir) {
+    if (dsRoot.state !== 'born' || !dsRoot.root) {
+        return path.resolve(configDir, 'src/components/core');
+    }
+    const isComponentDir = (dir) => {
+        try {
+            const files = fs.readdirSync(dir);
+            return files.some((f) => f.endsWith('.schema.yaml')) || files.includes('contracts.yaml');
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasComponentDirs = (dir) => {
+        try {
+            return fs
+                .readdirSync(dir, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .some((d) => isComponentDir(path.join(dir, d.name)));
+        }
+        catch {
+            return false;
+        }
+    };
+    const flatRoot = path.resolve(dsRoot.root, 'src/components');
+    if (hasComponentDirs(flatRoot))
+        return flatRoot;
+    const legacyRoot = path.join(flatRoot, 'core');
+    if (!isComponentDir(legacyRoot) && hasComponentDirs(legacyRoot))
+        return legacyRoot;
+    // Neither holds components yet (a freshly-born repo, README-only) — the flat
+    // (post-123) convention is the correct root regardless; buildConsumerMap
+    // returns an empty map for it, which is correct (no consumers to report).
+    return flatRoot;
+}
+/**
+ * The catalogued line for a component-token load failure. A
+ * `ComponentTokenFileLoadError` (recognised by `name`, so it survives a mocked module)
+ * names its file; the family-mismatch guard's message selects that row. Anything else
+ * the harvest throws (e.g. a duplicate-name conflict) keeps the pipeline's existing
+ * "System token generation failed" form — still one line, no stack.
+ */
+function componentTokenLoadFailureMessage(err, root) {
+    const e = err;
+    if (e && e.name === 'ComponentTokenFileLoadError' && typeof e.file === 'string' && typeof e.reason === 'string') {
+        // Repo-relative with `/` separators — the catalog row keys its remedies on the path prefix.
+        const rel = (path.relative(root, e.file) || e.file).split(path.sep).join('/');
+        return /^Token family mismatch/.test(e.reason)
+            ? (0, errorCatalog_1.componentTokenFamilyMismatchMessage)(rel, e.reason)
+            : (0, errorCatalog_1.componentTokenFileLoadFailedMessage)(rel, e.reason);
+    }
+    return `System token generation failed: ${err instanceof Error ? err.message : String(err)}`;
+}
 /** @internal Exported for testing */
 async function runGenerate(force = false) {
-    const config = await (0, ConfigLoader_1.loadConfig)(process.cwd());
+    // Spec 123 Task 1.5 (C2 consumer #4): BOTH the read side (the config) and the
+    // write side (token-index/ and platform output) anchor to the discovered ROOT —
+    // never a bare process.cwd() — so `generate` behaves correctly from a
+    // subdirectory of a born/package-mode repo, and REFUSES in a partial one rather
+    // than guessing (all four partial sub-cases carry their own catalog string).
+    const dsRoot = (0, bornRepo_1.findDesignSystemRoot)(process.cwd());
+    if (dsRoot.state === 'partial' && dsRoot.partialCase) {
+        console.error(`❌ ${(0, errorCatalog_1.partialCaseMessage)(dsRoot.root ?? process.cwd(), dsRoot.partialCase, dsRoot.attemptedTokenSource)}`);
+        process.exit(1);
+        return;
+    }
+    const generateRoot = dsRoot.root ?? process.cwd();
+    const config = await (0, ConfigLoader_1.loadConfig)(generateRoot);
     const tokens = (0, resolveTokens_1.resolveTokens)(config);
     // Load component tokens from source presence (the convention dir
     // {tokenSourceRoot}/component/ and configured componentTokenDirs), regardless of
@@ -137,7 +241,19 @@ async function runGenerate(force = false) {
     // wrong axis — componentTokenDirs resolve to real source files in BOTH modes, so
     // package-mode `generate` silently zeroed component tokens. Loading + the "none found"
     // warning are now driven by source presence, fired in all modes.
-    const componentTokens = (0, loadComponentTokens_1.loadComponentTokens)(config);
+    // A component-token module that throws while it loads (e.g. defineComponentTokens's
+    // family-mismatch guard on a pre-123 copied file) stops generate with a catalogued
+    // message naming the file — never the CLI's "Unexpected error" stack trace
+    // (.kiro/issues/2026-10-02-generate-stack-trace-on-component-token-family-mismatch.md).
+    let componentTokens;
+    try {
+        componentTokens = (0, loadComponentTokens_1.loadComponentTokens)(config);
+    }
+    catch (err) {
+        console.error(`❌ ${componentTokenLoadFailureMessage(err, generateRoot)}`);
+        process.exit(1);
+        return;
+    }
     if (componentTokens.length === 0) {
         console.warn(`⚠️  No component token files found.\n` +
             `   Searched: ${path.relative(process.cwd(), config.tokenSourceRoot)}/component/\n` +
@@ -160,19 +276,28 @@ async function runGenerate(force = false) {
         // Single shared mode resolution (Spec 117 Task 3): generateTokenFiles writes dist AND
         // returns the resolved truth; the index consumes the SAME object — no re-derivation.
         const modeResolved = (0, generateTokenFiles_1.generateTokenFiles)(tokens, config);
-        // Class C′ (Spec 118 Task 9.5.2, ratified default-only): resolve the component-schema
-        // scan root from the consumer's config so the token-index's consumer map reflects the
-        // consumer's design system — the same source the application MCP reads. Default to
-        // `<configDir>/src/components/core` (the location `init` writes to and MCP's
-        // COMPONENTS_DIR points at). Resolved HERE (config in scope), passed into the
-        // generator, which stays a pure function of its inputs.
-        const componentSchemaDir = path.resolve(config.configDir, 'src/components/core');
-        (0, generateTokenIndex_1.generateTokenIndex)(path.resolve(process.cwd(), 'token-index'), {
+        // Class C′ (Spec 118 Task 9.5.2, ratified default-only; U1 fix-up 2026-09-26 —
+        // `.kiro/issues/2026-09-26-product-server-component-root.md`): resolve the
+        // component-schema scan root from the consumer's config so the token-index's
+        // consumer map reflects the consumer's design system — the same source the
+        // application MCP reads. In a BORN repo that is `<bornRoot>/src/components`
+        // (Req 19A.2/19A.6 — `init` no longer writes a `core/` copy); every other
+        // state keeps `<configDir>/src/components/core` (the steward repo's own
+        // package-mode classification is UNCHANGED). See `resolveComponentSchemaDir`
+        // above. Resolved HERE (config + dsRoot in scope), passed into the generator,
+        // which stays a pure function of its inputs.
+        const componentSchemaDir = resolveComponentSchemaDir(dsRoot, config.configDir);
+        // WRITE side anchored at generateRoot, never a bare process.cwd() (Spec 123 C2/Task 1.5).
+        (0, generateTokenIndex_1.generateTokenIndex)(path.resolve(generateRoot, 'token-index'), {
             primitiveTokens: tokens.primitiveTokens,
             semanticTokens: tokens.semanticTokens,
             componentTokens: ComponentTokenRegistry_1.ComponentTokenRegistry.getAll(),
             modeResolved,
             componentSchemaDir,
+            // DD24: the live tier this index's data came from — written into
+            // token-index/meta.json so the theme readers can follow it later,
+            // wherever this index ends up being served from.
+            tierDir: config.tokenSourceRoot,
         });
         console.log('✅ System tokens generated');
     }
@@ -246,25 +371,29 @@ async function runProductOnly(force = false) {
 async function runMcpApp() {
     const pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(__dirname);
     const serverBundle = path.join(pkgRoot, 'dist/mcp/application-mcp.js');
-    const componentsDir = path.join(pkgRoot, 'src/components/core');
+    // CONSUMER-OWNED roots (COMPONENTS_DIR, TOKEN_INDEX_DIR) get NO runner default
+    // (Spec 123 Task 1.3, design.md § "C3. The root-policy table as code" — the
+    // Runner table's "Runner default: none" row). The server's own bootstrap now
+    // resolves these itself via `findDesignSystemRoot` + the birth-aware resolvers
+    // (`resolveComponentRoots` / `resolveTokenIndexRoot`), which know about
+    // born/package-mode/partial/unborn — a hardcoded pkgRoot value here would
+    // silently shadow that resolution (and any user-set env) forever.
     const patternsDir = path.join(pkgRoot, 'experience-patterns');
     const templatesDir = path.join(pkgRoot, 'layout-templates');
     const guidanceDir = path.join(pkgRoot, 'family-guidance');
     const registryPath = path.join(pkgRoot, 'family-registry.yaml');
-    const tokenIndexDir = path.join(pkgRoot, 'token-index');
     const designLanguagePath = path.join(pkgRoot, 'design-philosophy.yaml');
     console.error('DesignerPunk Application MCP');
     console.error(`  Protocol: stdio`);
-    console.error(`  Data: ${componentsDir}`);
     console.error(`  Server: ${serverBundle}`);
     console.error('  Starting...\n');
+    // PACKAGE-OWNED roots keep their pkgRoot default (Runner table: "Runner
+    // default: pkgRoot"). `spawnServer` still lets a user-set env value win.
     const envVars = {
-        COMPONENTS_DIR: componentsDir,
         PATTERNS_DIR: patternsDir,
         TEMPLATES_DIR: templatesDir,
         GUIDANCE_DIR: guidanceDir,
         REGISTRY_PATH: registryPath,
-        TOKEN_INDEX_DIR: tokenIndexDir,
     };
     if (fs.existsSync(designLanguagePath)) {
         envVars.DESIGN_LANGUAGE_PATH = designLanguagePath;
@@ -285,25 +414,33 @@ async function runMcpDocs() {
 async function runMcpProduct() {
     const pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(__dirname);
     const serverBundle = path.join(pkgRoot, 'dist/mcp/product-mcp.js');
-    const productDir = process.env.PRODUCT_DIR || path.resolve(process.cwd(), 'product');
-    const componentDir = path.join(pkgRoot, 'src/components/core');
-    const tokenIndexDir = path.join(pkgRoot, 'token-index');
     console.error('DesignerPunk Product MCP');
     console.error(`  Protocol: stdio`);
-    console.error(`  Data: ${productDir}`);
     console.error(`  Server: ${serverBundle}`);
     console.error('  Starting...\n');
-    spawnServer(serverBundle, {
-        PRODUCT_DIR: productDir,
-        COMPONENT_DIR: componentDir,
-        TOKEN_INDEX_DIR: tokenIndexDir,
-    }, true);
+    // PRODUCT_DIR, COMPONENT_DIR and TOKEN_INDEX_DIR are all CONSUMER-OWNED roots
+    // (Spec 123 Task 1.3): the runner sets NO default for any of them. The
+    // server's own bootstrap resolves them via `findDesignSystemRoot` +
+    // `resolveProductRoot` / `resolveComponentRoots` / `resolveTokenIndexRoot`.
+    spawnServer(serverBundle, {}, true);
 }
-/** Spawn a server as a child process. Uses node for bundled JS, tsx for TypeScript. */
+/**
+ * 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.
+ */
 function spawnServer(entryPoint, envVars, bundled = false) {
     const runner = bundled ? 'node' : resolveTsRunner();
     const child = (0, child_process_1.spawn)(runner, [entryPoint], {
-        env: { ...process.env, ...envVars },
+        env: { ...envVars, ...process.env },
         stdio: 'inherit',
     });
     child.on('error', (err) => {
@@ -354,22 +491,21 @@ async function runFigmaCommand(script) {
     });
 }
 async function runSyncCommand() {
-    const flags = process.argv.slice(3);
-    await (0, sync_1.runSync)({
-        dryRun: flags.includes('--dry-run'),
-        force: flags.includes('--accept-all') || flags.includes('--force'),
-        projectRoot: process.cwd(),
-    });
+    await (0, sync_1.runSync)({ ...(0, sync_1.parseSyncArgs)(process.argv.slice(3)), projectRoot: process.cwd() });
 }
+/** @internal Exported for testing — the "attach never appears without its object" check (vocabulary.ts, Task 16.2). */
 function printHelp() {
     console.log(`
 DesignerPunk Pipeline CLI
 
 Usage:
   npx designerpunk init            Bootstrap a new product repo
+  npx designerpunk attach --target=<cc|kiro>              ${(0, vocabulary_1.attachUsage)()}
+  npx designerpunk attach --target=<cc|kiro> --reference  MCP config + approvals only (no agents) — read DesignerPunk without becoming it
   npx designerpunk sync            Detect and apply package updates
   npx designerpunk sync --dry-run  Preview what sync would do (no changes)
-  npx designerpunk sync --accept-all    Accept all updates without prompting
+  npx designerpunk sync --apply   Apply updates without the confirmation prompt (off a terminal)
+  npx designerpunk sync --migrate-legacy  Remove an earlier init's copied agents/steering/governance, then ${(0, vocabulary_1.attachUsage)()} in the same run
   npx designerpunk generate        Generate token files from designerpunk.config.ts
   npx designerpunk generate --force              Regenerate all (skip staleness check)
   npx designerpunk generate --product-only       Skip system tokens, regenerate product only
@@ -387,7 +523,8 @@ Init options:
   --name <name>                    Product name (prompted if omitted)
   --abbreviation <abbr>            Short form (prompted if omitted)
   --skip-components                Don't copy starter components
-  --skip-agents                    Don't copy agent templates
+  --target=<cc|kiro>               Harness to set up (agents + MCP config); default: the package's declared default
+  --skip-agents                    Don't generate the agent layer
 
 Generate options:
   --force                          Skip staleness detection, always regenerate

package/dist/cli/figma-extract.js

@@ -67,6 +67,15 @@ const DesignExtractor_1 = require("../figma/DesignExtractor");
 const ComponentAnalysisGenerator_1 = require("../figma/ComponentAnalysisGenerator");
 const preflight_1 = require("../figma/preflight");
 const portCleanup_1 = require("../figma/portCleanup");
+const bornRepo_1 = require("./shared/bornRepo");
+/**
+ * Anchor `designerpunk.config.ts` lookup at the DesignerPunk root (Spec 123 C2
+ * consumer #5), not a bare `process.cwd()` — a script run from a subdirectory of a
+ * born repo still finds the real config instead of silently falling back to `dist/`.
+ */
+function resolveConfigDir() {
+    return (0, bornRepo_1.findDesignSystemRoot)(process.cwd()).root ?? process.cwd();
+}
 /**
  * Parse a Figma design URL into fileKey, nodeId, and fileUrl.
  * Returns null if the URL is not a valid Figma design URL.
@@ -163,7 +172,7 @@ function parseArgs(argv) {
 /** Default path to the DTCG token file — checks config output dir first, falls back to dist/. */
 const DTCG_INPUT_PATH = (() => {
     // Try config-specified output directory
-    const configPath = path.resolve('designerpunk.config.ts');
+    const configPath = path.join(resolveConfigDir(), 'designerpunk.config.ts');
     if (fs.existsSync(configPath)) {
         try {
             const raw = fs.readFileSync(configPath, 'utf-8');

package/dist/cli/figma-push.js

@@ -66,6 +66,15 @@ const TokenSyncWorkflow_1 = require("../figma/TokenSyncWorkflow");
 const ConsoleMCPClientImpl_1 = require("../figma/ConsoleMCPClientImpl");
 const preflight_1 = require("../figma/preflight");
 const portCleanup_1 = require("../figma/portCleanup");
+const bornRepo_1 = require("./shared/bornRepo");
+/**
+ * Anchor `designerpunk.config.ts` lookup at the DesignerPunk root (Spec 123 C2
+ * consumer #5), not a bare `process.cwd()` — a script run from a subdirectory of a
+ * born repo still finds the real config instead of silently falling back to `dist/`.
+ */
+function resolveConfigDir() {
+    return (0, bornRepo_1.findDesignSystemRoot)(process.cwd()).root ?? process.cwd();
+}
 /**
  * Parse process.argv into structured arguments.
  *
@@ -124,7 +133,7 @@ function parseArgs(argv) {
 /** Default path to the DTCG token file. */
 /** Resolve DTCG input path — checks config output dir first, falls back to dist/. */
 const DTCG_INPUT_PATH = (() => {
-    const configPath = path.resolve('designerpunk.config.ts');
+    const configPath = path.join(resolveConfigDir(), 'designerpunk.config.ts');
     if (fs.existsSync(configPath)) {
         try {
             const raw = fs.readFileSync(configPath, 'utf-8');
@@ -141,7 +150,7 @@ const DTCG_INPUT_PATH = (() => {
 })();
 /** Default path for the Figma format output. */
 const FIGMA_OUTPUT_PATH = (() => {
-    const configPath = path.resolve('designerpunk.config.ts');
+    const configPath = path.join(resolveConfigDir(), 'designerpunk.config.ts');
     if (fs.existsSync(configPath)) {
         try {
             const raw = fs.readFileSync(configPath, 'utf-8');

package/dist/cli/init.d.ts

@@ -1,11 +1,42 @@
 /**
- * `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"
  */
+import { UnmappedSpecifierError } from './shared/transforms';
+import type { ManifestEntry, ManifestOrigin, HarnessTarget } from './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.
+ */
+export declare class ManifestBuilder {
+    /**
+     * 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).
+     */
+    readonly state: {
+        entries: Record<string, ManifestEntry>;
+        attachedTargets: HarnessTarget[];
+    };
+    recordFile(relPath: string, absPath: string, origin: ManifestOrigin): void;
+    recordKey(relPath: string, key: string, content: unknown): void;
+    build(installedVersion: string, contractHash?: string): Record<string, unknown>;
+}
 export declare function runInit(argv: string[]): Promise<void>;
+export { UnmappedSpecifierError };
 //# sourceMappingURL=init.d.ts.map