@3fn/core 14.0.0 → 15.0.0

package/src/cli/init.ts

@@ -1,481 +0,0 @@
-/**
- * `npx designerpunk init` — Bootstrap a self-contained product repo.
- *
- * 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.
- *
- * @see .kiro/specs/097-product-mcp-intelligence-layer/cli-init-design.md
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as readline from 'readline';
-import { rewriteBuildImports } from './shared/transforms';
-import { resolvePackageRoot } from './shared/resolvePackageRoot';
-
-interface InitOptions {
-  name?: string;
-  abbreviation?: string;
-  skipComponents?: boolean;
-  skipAgents?: boolean;
-}
-
-export async function runInit(argv: string[]): Promise<void> {
-  const opts = parseInitArgs(argv);
-
-  if (!opts.name) {
-    opts.name = await prompt('Product name: ');
-  }
-  if (!opts.abbreviation) {
-    opts.abbreviation = await prompt('Abbreviation: ');
-  }
-
-  if (!opts.name || !opts.abbreviation) {
-    console.error('❌ Name and abbreviation are required.');
-    process.exit(1);
-  }
-
-  const pkgRoot = 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'] },
-  );
-  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: rewriteBuildImports },
-  );
-  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: rewriteBuildImports },
-    );
-    reportCopy('starter components', compResult);
-  }
-
-  // 5. product/overview.yaml
-  createFileIfNotExists(
-    path.join(dest, 'product/overview.yaml'),
-    generateOverview(opts.name),
-    'product/overview.yaml',
-  );
-
-  // 6. Agent templates
-  if (!opts.skipAgents) {
-    const agentsResult = copyDir(
-      path.join(pkgRoot, '.kiro/agents'),
-      path.join(dest, '.kiro/agents'),
-    );
-    reportCopy('agent templates', agentsResult);
-  }
-
-  // 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({
-      compilerOptions: {
-        target: 'ES2020',
-        module: 'commonjs',
-        moduleResolution: 'bundler',
-        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
-# 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
-`,
-    '.designerpunkignore',
-  );
-
-  // 11. Next steps
-  console.log(`
-Your product "${opts.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
-
-To customize your visual language:
-  • Edit src/tokens/ to change base values and design intent
-  • Run \`npx designerpunk generate\` after changes
-
-Note: Token values have mathematical relationships (modular scale,
-baseline grid). The validator will warn if changes break these
-relationships during generation.
-
-💡 After future upgrades, run \`npx designerpunk sync\` to apply updates.
-`);
-}
-
-function parseInitArgs(argv: string[]): InitOptions {
-  const opts: InitOptions = {};
-  for (let i = 0; i < argv.length; i++) {
-    switch (argv[i]) {
-      case '--name':
-        opts.name = argv[++i];
-        break;
-      case '--abbreviation':
-        opts.abbreviation = argv[++i];
-        break;
-      case '--skip-components':
-        opts.skipComponents = true;
-        break;
-      case '--skip-agents':
-        opts.skipAgents = true;
-        break;
-    }
-  }
-  return opts;
-}
-
-function prompt(question: string): Promise<string> {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
-
-function createFileIfNotExists(filePath: string, content: string, label: string): void {
-  if (fs.existsSync(filePath)) {
-    console.log(`  skipped: ${label} (already exists)`);
-    return;
-  }
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, content, 'utf-8');
-  console.log(`✓ Created ${label}`);
-}
-
-interface CopyOptions {
-  exclude?: string[];
-  /** Optional transform applied to file content (only .ts files) before writing. */
-  transform?: (content: string) => string;
-}
-
-/**
- * Result of a copyDir operation.
- *
- * NOTE: The summary output format emitted by `reportCopy()` below is part of
- * Gap 3's public behavior — asserted by the integration test at
- * `src/cli/__tests__/init.test.ts`. Intentional format changes can update
- * the assertion alongside the code; the contract catches unintended drift,
- * not wording freezes.
- */
-interface CopyResult {
-  added: number;
-  skipped: number;
-  skippedFiles: string[]; // Tracked up to 10; used for per-file output when count is small
-  warnings: string[];
-}
-
-const SKIPPED_FILE_LIST_THRESHOLD = 10;
-
-/**
- * Recursively copy `src` → `dest` in merge mode.
- *
- * Semantics:
- * - If a destination file already exists, it is NEVER overwritten (consumer edits
- *   are preserved).
- * - Files whose basename matches `opts.exclude` are skipped entirely.
- * - Missing destination directories are created as needed.
- * - Returns counts of added and skipped files for caller-side summary.
- *
- * 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.
- */
-function copyDir(src: string, dest: string, opts?: CopyOptions): CopyResult {
-  const result: CopyResult = { added: 0, skipped: 0, skippedFiles: [], warnings: [] };
-
-  if (!fs.existsSync(src)) {
-    result.warnings.push(`source not found: ${src}`);
-    return result;
-  }
-
-  copyDirRecursive(src, dest, opts, result);
-  return result;
-}
-
-function copyDirRecursive(
-  src: string,
-  dest: string,
-  opts: CopyOptions | undefined,
-  result: CopyResult,
-): void {
-  fs.mkdirSync(dest, { recursive: true });
-
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const basename = entry.name;
-    if (opts?.exclude?.includes(basename)) continue;
-
-    const srcPath = path.join(src, basename);
-    const destPath = path.join(dest, basename);
-
-    if (entry.isDirectory()) {
-      copyDirRecursive(srcPath, destPath, opts, result);
-    } else if (entry.isFile()) {
-      if (fs.existsSync(destPath)) {
-        result.skipped++;
-        if (result.skippedFiles.length < SKIPPED_FILE_LIST_THRESHOLD) {
-          result.skippedFiles.push(path.relative(process.cwd(), destPath));
-        }
-      } else {
-        if (opts?.transform && basename.endsWith('.ts')) {
-          const content = fs.readFileSync(srcPath, 'utf-8');
-          fs.writeFileSync(destPath, opts.transform(content), 'utf-8');
-        } else {
-          fs.copyFileSync(srcPath, destPath);
-        }
-        result.added++;
-      }
-    }
-  }
-}
-
-/**
- * Emit the summary output for a copyDir operation.
- * See CopyResult's NOTE about integration-test contract on output format.
- */
-function reportCopy(label: string, result: CopyResult): void {
-  for (const warning of result.warnings) {
-    console.log(`  warning: ${warning}`);
-  }
-
-  if (result.added === 0 && result.skipped === 0) return;
-
-  const parts: string[] = [];
-  if (result.added > 0) {
-    parts.push(`${result.added} new file${result.added === 1 ? '' : 's'}`);
-  }
-  if (result.skipped > 0) {
-    parts.push(
-      `${result.skipped} existing file${result.skipped === 1 ? '' : 's'} preserved`,
-    );
-  }
-  console.log(`✓ ${label}: ${parts.join(', ')}`);
-
-  // Per-file list only when skipped count is small — avoids log flood on large merges
-  if (result.skipped > 0 && result.skipped <= SKIPPED_FILE_LIST_THRESHOLD) {
-    for (const file of result.skippedFiles) {
-      console.log(`    preserved: ${file}`);
-    }
-  }
-}
-
-/**
- * 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: string, destPath: string): void {
-  if (!fs.existsSync(templatePath)) {
-    console.log(`  warning: MCP config template not found at ${templatePath}`);
-    return;
-  }
-
-  const templateContent = fs.readFileSync(templatePath, 'utf-8');
-  let template: { mcpServers: Record<string, unknown> };
-  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: string;
-  let existing: { mcpServers?: Record<string, unknown>; [key: string]: unknown };
-  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: string[] = [];
-  const skipped: string[] = [];
-
-  for (const [key, value] of Object.entries(template.mcpServers)) {
-    if (key in (existing.mcpServers as Record<string, unknown>)) {
-      skipped.push(key);
-    } else {
-      (existing.mcpServers as Record<string, unknown>)[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: string, abbreviation: string): string {
-  return `import { defineConfig } from '@3fn/core/config';
-import { darkSemanticOverrides } from './src/tokens/themes/dark/SemanticOverrides.ts';
-import { wcagSemanticOverrides } from './src/tokens/themes/wcag/SemanticOverrides.ts';
-
-export default defineConfig({
-  name: '${name}',
-  abbreviation: '${abbreviation}',
-  tokenSource: './src/tokens',
-  componentTokens: ['./src/components/core', './src/tokens/component'],
-  themes: [
-    { name: 'dark', mode: 'dark', overrides: darkSemanticOverrides },
-    { name: 'wcag', mode: 'light', overrides: wcagSemanticOverrides },
-  ],
-  output: './dist/tokens',
-});
-`;
-}
-
-function generateOverview(name: string): string {
-  return `# ${name} — Product Overview
-
-## Product Context
-name: ${name}
-description: "[CUSTOMIZE] Describe your product"
-domain: "[CUSTOMIZE] Your product domain"
-
-## Principles
-- "[CUSTOMIZE] Add your design principles"
-
-## Platform Status
-web: not-started
-ios: not-started
-android: not-started
-`;
-}

package/src/cli/loadComponentTokens.ts

@@ -1,145 +0,0 @@
-/**
- * Component Token Loader
- *
- * Discovers component token files from local source and harvests the rich
- * `RegisteredComponentToken[]` carried back on each `defineComponentTokens` result's
- * non-enumerable brand. This loader is the SOLE writer to the canonical
- * `ComponentTokenRegistry` (Spec 124): `defineComponentTokens` no longer self-registers,
- * so the cross-boundary shared-singleton desync is eliminated.
- *
- * Discovery sources (order is load-bearing — see below):
- * 1. {tokenSourceRoot}/component/ — scan for *.ts files (dedicated directory)
- * 2. componentTokenDirs from config — scan for *.tokens.ts / tokens.ts files (broader dirs)
- *
- * Ordering (Spec 124, R6 / Task-2 ordering spike): the committed `components.yaml`
- * ordering is directory-SCAN order, NOT a sort. The harvest therefore preserves
- * Source-1-then-Source-2 traversal, each directory in `readdirSync` order, and within each
- * module the `Object.values(mod)` × per-branded-array (authored) order. NO sort is
- * introduced — a sort would reorder to alphabetical and break the R6 `git diff` gate.
- *
- * @see Spec 104 design.md § "Component Token Loader"
- * @see .kiro/specs/124-component-token-return-contract/design.md (the branded-return harvest)
- * @see .kiro/specs/124-component-token-return-contract/findings/r6-ordering-spike.md
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import type { ResolvedConfig } from '../config/ConfigLoader';
-import { scopedTsRequire, type TsModuleLoader } from '../config/scopedTsRequire';
-import { ComponentTokenRegistry } from '../registries/ComponentTokenRegistry';
-import type { RegisteredComponentToken } from '../registries/ComponentTokenRegistry';
-import { getTokenContract } from '../build/tokens';
-
-/**
- * Discover component token files and harvest branded results into the canonical
- * `ComponentTokenRegistry` as the sole writer. Returns all harvested tokens for
- * downstream consumers.
- *
- * The harvest inspects each loaded module's exports (`Object.values(mod)`) and collects
- * the rich tokens from any export carrying the {@link getTokenContract} brand — by
- * direct / `hasOwnProperty` access, never by enumerating a candidate's keys (Spec 124,
- * R3). Unbranded exports (plain value-maps, getters, string consts, type aliases,
- * re-export aliases) harvest to zero. Re-export aliases are deduped first-seen-wins.
- *
- * @param config - Resolved pipeline configuration.
- * @param loadModule - Injectable runtime-TS resolution seam (Spec 118 Task 9.5). Defaults
- *   to {@link scopedTsRequire} (Approach A scoped `tsx/cjs/api`) — the per-site scope that
- *   makes this consumer-`.ts` load independent of the bin's global register. In-process
- *   jest callers inject a jest-compatible loader; the build script injects the ambient tsx
- *   loader (a plain `require`). See {@link scopedTsRequire} for why.
- */
-export function loadComponentTokens(
-  config: ResolvedConfig,
-  loadModule: TsModuleLoader = scopedTsRequire,
-): RegisteredComponentToken[] {
-  // Harvested rich tokens in traversal order (Source-1-then-Source-2; per-module export
-  // order; per-branded-array authored order). Deduped by token `name` across modules.
-  const harvested: RegisteredComponentToken[] = [];
-  const seenNames = new Set<string>();
-
-  // Source 1: Auto-discover from {tokenSourceRoot}/component/
-  const componentSubdir = path.join(config.tokenSourceRoot, 'component');
-  if (fs.existsSync(componentSubdir)) {
-    const files = fs.readdirSync(componentSubdir)
-      .filter(f => f.endsWith('.ts') && !f.endsWith('.test.ts') && !f.endsWith('.d.ts'));
-    for (const file of files) {
-      const mod = loadModule(path.join(componentSubdir, file), __filename);
-      harvestModule(mod, harvested, seenNames);
-    }
-  }
-
-  // Source 2: Explicit componentTokens directories (*.tokens.ts / tokens.ts pattern)
-  for (const dir of config.componentTokenDirs) {
-    if (!fs.existsSync(dir)) continue;
-    scanForTokenFiles(dir, loadModule, harvested, seenNames);
-  }
-
-  // Sole writer to the canonical registry (Spec 124, R5 AC2), in traversal order so that
-  // ComponentTokenRegistry.getAll() (Map-insertion order) feeds generateTokenIndex in the
-  // committed `components.yaml` sequence (R6).
-  for (const token of harvested) {
-    ComponentTokenRegistry.register(token);
-  }
-
-  return ComponentTokenRegistry.getAll();
-}
-
-/**
- * Harvest branded `defineComponentTokens` results from a single loaded module's exports.
- *
- * Iterates `Object.values(mod)` (declaration/export order) and, for each export carrying
- * the brand (read via {@link getTokenContract} — direct/`hasOwnProperty`, never key
- * enumeration), appends its rich tokens in authored array order. Dedupe is two-layer:
- * a re-exported alias points at the same object (skipped by `seenObjects` within the
- * module), and a token `name` already harvested from any module is skipped (first-seen
- * wins) so a re-export alias never moves or duplicates an entry.
- */
-function harvestModule(
-  mod: unknown,
-  harvested: RegisteredComponentToken[],
-  seenNames: Set<string>,
-): void {
-  if (mod == null || typeof mod !== 'object') return;
-
-  const seenObjects = new Set<unknown>();
-  for (const exported of Object.values(mod as Record<string, unknown>)) {
-    if (exported == null || typeof exported !== 'object') continue;
-    // Same branded object reachable by two export names (re-export alias): collect once.
-    if (seenObjects.has(exported)) continue;
-
-    const tokens = getTokenContract(exported);
-    if (!tokens) continue;
-    seenObjects.add(exported);
-
-    for (const token of tokens) {
-      // First-seen-wins across modules (a genuine duplicate name is caught by the
-      // registry's conflict throw at write time).
-      if (seenNames.has(token.name)) continue;
-      seenNames.add(token.name);
-      harvested.push(token);
-    }
-  }
-}
-
-/**
- * Recursively scan a directory for *.tokens.ts / tokens.ts files, load each through the
- * injected runtime-TS resolution seam, and harvest branded results in scan order.
- */
-function scanForTokenFiles(
-  dir: string,
-  loadModule: TsModuleLoader,
-  harvested: RegisteredComponentToken[],
-  seenNames: Set<string>,
-): void {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory() && entry.name !== '__tests__' && entry.name !== 'node_modules') {
-      scanForTokenFiles(fullPath, loadModule, harvested, seenNames);
-    } else if (entry.isFile() && (entry.name.endsWith('.tokens.ts') || entry.name === 'tokens.ts') && !entry.name.endsWith('.test.ts')) {
-      const mod = loadModule(fullPath, __filename);
-      harvestModule(mod, harvested, seenNames);
-    }
-  }
-}