@chemx/starter-kit 26.9.21-8 → 26.9.24-393

package/cli/create.spec.js

@@ -63,7 +63,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--help'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --help');
@@ -78,7 +78,7 @@ describe('Scaffolding Entrypoint Invocations', () => {
     const result = spawnSync('node', [CREATE_BIN, '--version'], {
       encoding: 'utf-8',
       cwd: tmpBase,
-      timeout: 5000
+      timeout: 15000
     });
 
     assert.equal(result.status, 0, 'Should exit with code 0 on --version');

package/cli/exploder.js

@@ -0,0 +1,258 @@
+/**
+ * Chemical X Capsule Exploder
+ * Atomically unpacks a "liquid" single-file compact capsule into a standard crystalline multi-file directory capsule.
+ * Transactional: Uses .temp.bak and rolls back if post-unpack verification fails.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import * as babelParser from '@babel/parser';
+import { toPascalCase } from './generator-templates/naming.js';
+import { buildComponentSpec, buildIndex } from './generator-templates/specs.js';
+import { buildTypesIndex } from './generator-templates/types.js';
+import { detectTestRunner } from './project-detector.js';
+
+export const parseCompactFile = (content, ext = 'tsx') => {
+  const isTsx = ext === 'tsx' || ext === 'jsx';
+  const plugins = ['typescript'];
+  if (isTsx) plugins.push('jsx');
+
+  const ast = babelParser.parse(content, {
+    sourceType: 'module',
+    plugins
+  });
+
+  const lines = content.split('\n');
+  const getSlice = (node) => {
+    return lines.slice(node.loc.start.line - 1, node.loc.end.line).join('\n');
+  };
+
+  const typesProps = [];
+  const typesState = [];
+  let controllerHookCode = null;
+  let componentCode = null;
+  const reactImports = new Set();
+
+  for (const node of ast.program.body) {
+    if (node.type === 'ImportDeclaration') {
+      if (node.source.value === 'react') {
+        for (const spec of node.specifiers) {
+          if (spec.imported?.name) reactImports.add(spec.imported.name);
+        }
+      }
+      continue;
+    }
+
+    // Capture TypeScript interfaces and type aliases
+    const isExportedType = node.type === 'ExportNamedDeclaration' &&
+      (node.declaration?.type === 'TSInterfaceDeclaration' || node.declaration?.type === 'TSTypeAliasDeclaration');
+
+    if (isExportedType) {
+      const typeName = node.declaration.id?.name || '';
+      const slice = getSlice(node);
+      const isPropsOrEmits = typeName.includes('Props') || typeName.includes('Emits');
+      if (isPropsOrEmits) {
+        typesProps.push(slice);
+      } else {
+        typesState.push(slice);
+      }
+      continue;
+    }
+
+    // Capture Controller Hook
+    const isExportedVar = node.type === 'ExportNamedDeclaration' && node.declaration?.type === 'VariableDeclaration';
+    if (isExportedVar) {
+      const decl = node.declaration.declarations[0];
+      const varName = decl?.id?.name || '';
+      const isControllerHook = varName.startsWith('use') && varName.endsWith('Controller');
+      if (isControllerHook) {
+        controllerHookCode = getSlice(node);
+        continue;
+      }
+      if (varName && !varName.startsWith('use')) {
+        componentCode = getSlice(node);
+        continue;
+      }
+    }
+
+    if (node.type === 'ExportDefaultDeclaration') {
+      continue;
+    }
+  }
+
+  return {
+    typesProps: typesProps.join('\n\n'),
+    typesState: typesState.join('\n\n'),
+    controllerHookCode,
+    componentCode,
+    reactImports: Array.from(reactImports)
+  };
+};
+
+export const explodeCapsule = (targetFilePath, options = {}) => {
+  const cwd = options.cwd || process.cwd();
+  const absPath = path.resolve(cwd, targetFilePath);
+
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`Target file not found at ${absPath}`);
+  }
+
+  const stat = fs.statSync(absPath);
+  if (stat.isDirectory()) {
+    throw new Error(`Target ${targetFilePath} is already a directory capsule.`);
+  }
+
+  const fileName = path.basename(absPath);
+  const ext = path.extname(absPath).replace('.', '');
+  const capsuleName = fileName.replace(/\.[^.]+$/, '');
+  const parentDir = path.dirname(absPath);
+  const targetDir = path.join(parentDir, capsuleName);
+  const bakPath = `${absPath}.temp.bak`;
+
+  if (fs.existsSync(targetDir)) {
+    throw new Error(`Destination directory ${capsuleName} already exists.`);
+  }
+
+  const content = fs.readFileSync(absPath, 'utf-8');
+  const baseSlug = capsuleName.replace(/^[a-z]+-/, '');
+  const pascalName = toPascalCase(baseSlug);
+
+  if (options.dryRun) {
+    parseCompactFile(content, ext);
+    return {
+      success: true,
+      dryRun: true,
+      capsuleName,
+      targetDir: path.relative(cwd, targetDir),
+      files: [
+        `${capsuleName}.${ext}`,
+        `${capsuleName}.controller.ts`,
+        `${capsuleName}.spec.ts`,
+        'index.ts',
+        'types/props.d.ts',
+        'types/state.d.ts',
+        'types/index.ts',
+        'types.d.ts'
+      ]
+    };
+  }
+
+  // 1. Transactional Backup Snapshot
+  fs.copyFileSync(absPath, bakPath);
+
+  try {
+    const parsed = parseCompactFile(content, ext);
+
+    // 2. Create Directory Capsule Structure
+    fs.mkdirSync(targetDir, { recursive: true });
+    const typesDir = path.join(targetDir, 'types');
+    fs.mkdirSync(typesDir, { recursive: true });
+
+    // 3. Types Files
+    let propsContent = parsed.typesProps || `export interface ${pascalName}Props {\n  readonly className?: string;\n}\n`;
+    const usesReactNode = propsContent.includes('ReactNode') && !propsContent.includes("from 'react'");
+    if (usesReactNode) {
+      propsContent = `import type { ReactNode } from 'react';\n\n${propsContent}`;
+    }
+    const stateContent = parsed.typesState || `export interface ${pascalName}State {\n  readonly isActive: boolean;\n}\n`;
+
+    fs.writeFileSync(path.join(typesDir, 'props.d.ts'), `${propsContent}\n`, 'utf-8');
+    fs.writeFileSync(path.join(typesDir, 'state.d.ts'), `${stateContent}\n`, 'utf-8');
+    fs.writeFileSync(path.join(typesDir, 'index.ts'), buildTypesIndex(['props', 'state']), 'utf-8');
+    fs.writeFileSync(path.join(targetDir, 'types.d.ts'), "export * from './types/index';\n", 'utf-8');
+
+    // 4. Controller File
+    const hookCode = parsed.controllerHookCode ||
+      `export const use${pascalName}Controller = () => {\n  const [isActive, setIsActive] = useState<boolean>(false);\n  return { isActive };\n};`;
+    const controllerImports = "import { useState, useMemo } from 'react';\n";
+    fs.writeFileSync(path.join(targetDir, `${capsuleName}.controller.ts`), `${controllerImports}\n${hookCode}\n`, 'utf-8');
+
+    // 5. Component File
+    const compImports = `import type { ${pascalName}Props } from './types';\nimport { use${pascalName}Controller } from './${capsuleName}.controller';\n\n`;
+    const compBody = parsed.componentCode || `export const ${pascalName} = ({ className = '' }: ${pascalName}Props) => {\n  return <div className="${capsuleName}" />;\n};`;
+    const compContent = `${compImports}${compBody}\n\nexport default ${pascalName};\n`;
+    fs.writeFileSync(path.join(targetDir, `${capsuleName}.${ext}`), compContent, 'utf-8');
+
+    // 6. Index & Spec
+    const hasController = Boolean(parsed.controllerHookCode);
+    const runner = detectTestRunner(targetDir);
+    fs.writeFileSync(path.join(targetDir, 'index.ts'), buildIndex(capsuleName, pascalName, ext, hasController), 'utf-8');
+    fs.writeFileSync(path.join(targetDir, `${capsuleName}.spec.ts`), buildComponentSpec(capsuleName, pascalName, hasController, runner), 'utf-8');
+
+    // 7. Verify Unpacked Directory (Syntactic AST Parse Verification)
+    babelParser.parse(fs.readFileSync(path.join(targetDir, `${capsuleName}.${ext}`), 'utf-8'), {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx']
+    });
+
+    // 8. Success: Delete source file and backup
+    fs.unlinkSync(absPath);
+    if (fs.existsSync(bakPath)) fs.unlinkSync(bakPath);
+
+    return {
+      success: true,
+      capsuleName,
+      targetDir: path.relative(cwd, targetDir),
+      files: [
+        `${capsuleName}.${ext}`,
+        `${capsuleName}.controller.ts`,
+        `${capsuleName}.spec.ts`,
+        'index.ts',
+        'types/props.d.ts',
+        'types/state.d.ts',
+        'types/index.ts',
+        'types.d.ts'
+      ]
+    };
+  } catch (err) {
+    // Transactional Rollback
+    if (fs.existsSync(targetDir)) {
+      fs.rmSync(targetDir, { recursive: true, force: true });
+    }
+    if (fs.existsSync(bakPath)) {
+      fs.copyFileSync(bakPath, absPath);
+      fs.unlinkSync(bakPath);
+    }
+    throw new Error(`Explode transaction aborted and rolled back: ${err.message}`);
+  }
+};
+
+export const runExplodeCli = async (rawArgs = [], isCli = true) => {
+  const isJson = rawArgs.includes('--json');
+  const isDryRun = rawArgs.includes('--dry-run') || rawArgs.includes('-n');
+  const target = rawArgs.find((a) => !a.startsWith('-'));
+
+  if (!target) {
+    const msg = 'Usage: npx chemx explode <file-path> [--dry-run] [--json]';
+    if (isJson) {
+      process.stdout.write(JSON.stringify({ error: msg, success: false }) + '\n');
+    } else {
+      process.stderr.write(`\x1b[31m✕ Error: ${msg}\x1b[0m\n`);
+    }
+    if (isCli) process.exit(1);
+    return { error: msg, success: false };
+  }
+
+  try {
+    const result = explodeCapsule(target, { dryRun: isDryRun });
+    if (isJson) {
+      process.stdout.write(JSON.stringify(result) + '\n');
+    } else {
+      process.stdout.write(`\n\x1b[1m\x1b[32m✔ Successfully exploded capsule:\x1b[0m \x1b[36m${result.targetDir}/\x1b[0m\n`);
+      for (const f of result.files) {
+        process.stdout.write(`  \x1b[32m✔\x1b[0m ${f}\n`);
+      }
+      process.stdout.write('\n');
+    }
+    if (isCli) process.exit(0);
+    return result;
+  } catch (err) {
+    if (isJson) {
+      process.stdout.write(JSON.stringify({ error: err.message, success: false }) + '\n');
+    } else {
+      process.stderr.write(`\x1b[31m✕ Error: ${err.message}\x1b[0m\n`);
+    }
+    if (isCli) process.exit(1);
+    throw err;
+  }
+};

package/cli/exploder.spec.js

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCompactFile, explodeCapsule } from './exploder.js';
+
+const SAMPLE_COMPACT_CODE = `import type { ReactNode } from 'react';
+import { useState } from 'react';
+
+export interface CounterProps {
+  readonly className?: string;
+  readonly children?: ReactNode;
+  readonly initialCount?: number;
+}
+
+export interface CounterState {
+  readonly count: number;
+}
+
+export const useCounterController = (options: { initialCount?: number } = {}) => {
+  const [count, setCount] = useState<number>(options.initialCount || 0);
+  const increment = () => setCount((c) => c + 1);
+  return { count, increment };
+};
+
+export const Counter = ({ className = '', initialCount = 0 }: CounterProps) => {
+  const { count, increment } = useCounterController({ initialCount });
+  return (
+    <div className={\`m-counter \${className}\`.trim()}>
+      <button type="button" onClick={increment}>Count: {count}</button>
+    </div>
+  );
+};
+
+export default Counter;
+`;
+
+test('exploder: parseCompactFile extracts types, controller, and component sections', () => {
+  const parsed = parseCompactFile(SAMPLE_COMPACT_CODE, 'tsx');
+  assert.ok(parsed.typesProps.includes('CounterProps'), 'Must extract CounterProps');
+  assert.ok(parsed.typesState.includes('CounterState'), 'Must extract CounterState');
+  assert.ok(parsed.controllerHookCode.includes('useCounterController'), 'Must extract controller hook');
+  assert.ok(parsed.componentCode.includes('export const Counter'), 'Must extract component body');
+});
+
+test('exploder: explodeCapsule unpacks single file into multi-file capsule and removes .temp.bak', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-explode');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const compactFile = path.join(tmpDir, 'm-counter.tsx');
+  fs.writeFileSync(compactFile, SAMPLE_COMPACT_CODE, 'utf-8');
+
+  const result = explodeCapsule(compactFile, { cwd: tmpDir });
+  assert.strictEqual(result.success, true);
+  assert.strictEqual(result.capsuleName, 'm-counter');
+
+  // Verify single file is gone and bak is cleaned up
+  assert.strictEqual(fs.existsSync(compactFile), false, 'Original file should be replaced');
+  assert.strictEqual(fs.existsSync(`${compactFile}.temp.bak`), false, 'Temp bak must be removed on success');
+
+  // Verify unpacked capsule structure
+  const capsuleDir = path.join(tmpDir, 'm-counter');
+  assert.ok(fs.existsSync(capsuleDir), 'Directory capsule must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'm-counter.tsx')), 'Component must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'm-counter.controller.ts')), 'Controller must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'm-counter.spec.ts')), 'Spec must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'index.ts')), 'Index barrel must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'types/props.d.ts')), 'Props type must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'types/state.d.ts')), 'State type must exist');
+  assert.ok(fs.existsSync(path.join(capsuleDir, 'types.d.ts')), 'Types barrel must exist');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('exploder: rolls back and restores from .temp.bak on failure', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-explode-fail');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  // Invalid syntax that fails verification
+  const invalidCode = 'export const Bad = () => { return <div missing closing tag>; };';
+  const targetFile = path.join(tmpDir, 'm-bad.tsx');
+  fs.writeFileSync(targetFile, invalidCode, 'utf-8');
+
+  assert.throws(() => {
+    explodeCapsule(targetFile, { cwd: tmpDir });
+  }, /Explode transaction aborted/);
+
+  // Original file must be restored
+  assert.ok(fs.existsSync(targetFile), 'Original file must be restored on failure');
+  assert.strictEqual(fs.readFileSync(targetFile, 'utf-8'), invalidCode);
+  // Backup must be cleaned up
+  assert.strictEqual(fs.existsSync(`${targetFile}.temp.bak`), false, 'Temp bak must be cleaned up');
+  // Capsule dir must not exist
+  assert.strictEqual(fs.existsSync(path.join(tmpDir, 'm-bad')), false, 'Failed capsule dir must be removed');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/cli/generator-compact.spec.js

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runGenerateWizard, createCapsuleFiles } from './generator.js';
+import { detectStylingStack } from './project-detector.js';
+import { resolveArchetype } from './generator-templates/archetypes/index.js';
+
+test('detectStylingStack: detects tailwind, scss, or css appropriately', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-detect-styling');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  // 1. Plain CSS fallback
+  const plain = detectStylingStack(tmpDir);
+  assert.strictEqual(plain.hasTailwind, false);
+  assert.strictEqual(plain.hasScss, false);
+  assert.strictEqual(plain.styleFlavor, 'css');
+
+  // 2. Tailwind via package.json
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({
+    dependencies: { tailwindcss: '^4.0.0' }
+  }));
+  const twPkg = detectStylingStack(tmpDir);
+  assert.strictEqual(twPkg.hasTailwind, true);
+  assert.strictEqual(twPkg.styleFlavor, 'tailwind');
+
+  // 3. Tailwind via config file
+  fs.unlinkSync(path.join(tmpDir, 'package.json'));
+  fs.writeFileSync(path.join(tmpDir, 'tailwind.config.js'), 'export default {};');
+  const twCfg = detectStylingStack(tmpDir);
+  assert.strictEqual(twCfg.hasTailwind, true);
+  assert.strictEqual(twCfg.styleFlavor, 'tailwind');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('archetypes: resolveArchetype resolves minimal, controls, and canvas archetypes', () => {
+  const minimal = resolveArchetype('m-card', '', 'minimal');
+  assert.strictEqual(minimal.id, 'minimal');
+
+  const bare = resolveArchetype('m-card', '', 'bare');
+  assert.strictEqual(bare.id, 'minimal');
+
+  const controls = resolveArchetype('m-dock', '', 'controls');
+  assert.strictEqual(controls.id, 'controls');
+
+  const canvas = resolveArchetype('m-stage', '', 'canvas');
+  assert.strictEqual(canvas.id, 'canvas');
+});
+
+test('generator: --compact generates single clean file with inlined types and controller', async () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-gen-compact');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  const res = await runGenerateWizard([
+    'molecule',
+    'time-controls',
+    '--compact',
+    '--template=minimal',
+    '-y',
+    `--dir=${tmpDir}`,
+    '--framework=react'
+  ]);
+
+  assert.strictEqual(res.success, true);
+  assert.strictEqual(res.compact, true);
+  assert.strictEqual(res.capsuleName, 'm-time-controls');
+
+  const singleFilePath = path.join(tmpDir, 'm-time-controls.tsx');
+  assert.ok(fs.existsSync(singleFilePath), 'Compact file must exist');
+
+  const content = fs.readFileSync(singleFilePath, 'utf-8');
+  assert.ok(content.includes('interface TimeControlsProps'), 'Must inline props');
+  assert.ok(content.includes('interface TimeControlsState'), 'Must inline state');
+  assert.ok(content.includes('useTimeControlsController'), 'Must inline controller hook');
+  assert.ok(content.includes('export const TimeControls'), 'Must export component');
+
+  const lineCount = content.split('\n').length;
+  assert.ok(lineCount < 80, `Compact file must be < 80 lines (got ${lineCount})`);
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test('generator: skips scss creation when tailwind is detected or --css=none', async () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-gen-tailwind');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  const res = await runGenerateWizard([
+    'molecule',
+    'quick-card',
+    '--css=tailwind',
+    '-y',
+    `--dir=${tmpDir}`,
+    '--framework=react'
+  ]);
+
+  assert.strictEqual(res.success, true);
+  const capsuleDir = path.join(tmpDir, 'm-quick-card');
+  const scssFile = path.join(capsuleDir, '_m-quick-card.scss');
+  assert.strictEqual(fs.existsSync(scssFile), false, 'SCSS file must not exist for tailwind');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/cli/generator-framework.spec.js

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert';
 import fs from 'node:fs';
 import path from 'node:path';
+import ts from 'typescript';
 import { runGenerateWizard } from './generator.js';
 import { auditFile } from './audit.js';
 
@@ -115,6 +116,15 @@ test('generator integration: Vue capsule with --desc generates Vue reactivity an
   assert.ok(!controllerContent.includes("from 'react'"), 'Vue controller must NOT import from react');
   assert.ok(!controllerContent.includes('useState'), 'Vue controller must NOT use useState');
 
+  // Assert method collision is prevented
+  assert.ok(!controllerContent.includes('.filter.value'), 'Must not collide Array.filter method with filter.value');
+  assert.ok(controllerContent.includes('items.value.filter'), 'Must unwrap items.value before Array.filter');
+  assert.ok(controllerContent.includes("filter.value === 'active'"), 'Must unwrap filter state variable comparison');
+
+  // Assert controller parses with zero TypeScript syntax errors
+  const sf = ts.createSourceFile('test.ts', controllerContent, ts.ScriptTarget.Latest, true);
+  assert.strictEqual(sf.parseDiagnostics?.length || 0, 0, 'Generated Vue controller must have zero TypeScript syntax errors');
+
   // Assert no old generic placeholder properties
   assert.ok(!viewContent.includes('descriptor.className'));
   assert.ok(!viewContent.includes('descriptor.text'));
@@ -161,6 +171,10 @@ test('generator integration: Svelte capsule with --desc generates matching view
   assert.ok(!controllerContent.includes("from 'react'"), 'Svelte controller must NOT import from react');
   assert.ok(!controllerContent.includes('useState'), 'Svelte controller must NOT use useState');
 
+  // Assert Svelte controller parses with zero TypeScript syntax errors
+  const sfSvelte = ts.createSourceFile('test.ts', controllerContent, ts.ScriptTarget.Latest, true);
+  assert.strictEqual(sfSvelte.parseDiagnostics?.length || 0, 0, 'Generated Svelte controller must have zero TypeScript syntax errors');
+
   const returnedKeys = parseControllerReturns(controllerContent);
   const destructuredKeys = parseViewDestructured(viewContent);
 
@@ -241,3 +255,61 @@ test('generator integration: auto-detects framework from .chemx/config.json when
   fs.rmSync(tmpDir, { recursive: true, force: true });
 });
 
+test('generator integration: mechanical contract diff and syntax check across all frameworks with --desc', async () => {
+  const frameworks = ['react', 'vue', 'svelte'];
+  const testDesc = 'add, toggle, and remove tasks with an input field';
+
+  for (const fw of frameworks) {
+    const tmpDir = path.resolve(process.cwd(), `scratch/test-contract-diff-${fw}`);
+    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+
+    const res = await runGenerateWizard([
+      'molecule',
+      'task-list',
+      '-y',
+      `--dir=${tmpDir}`,
+      `--framework=${fw}`,
+      `--desc=${testDesc}`
+    ]);
+
+    assert.strictEqual(res.success, true, `Scaffolding must succeed for ${fw}`);
+    const capsuleDir = path.join(tmpDir, 'm-task-list');
+    const ext = fw === 'react' ? 'tsx' : fw;
+    const viewPath = path.join(capsuleDir, `m-task-list.${ext}`);
+    const controllerPath = path.join(capsuleDir, 'm-task-list.controller.ts');
+
+    assert.ok(fs.existsSync(viewPath), `View file must exist for ${fw}`);
+    assert.ok(fs.existsSync(controllerPath), `Controller file must exist for ${fw}`);
+
+    const viewContent = fs.readFileSync(viewPath, 'utf8');
+    const controllerContent = fs.readFileSync(controllerPath, 'utf8');
+
+    // 1. Mechanical check: TS syntax validation
+    const sf = ts.createSourceFile('test.ts', controllerContent, ts.ScriptTarget.Latest, true);
+    assert.strictEqual(
+      sf.parseDiagnostics?.length || 0,
+      0,
+      `Controller for ${fw} must have zero TypeScript syntax errors`
+    );
+
+    // 2. Mechanical check: diff controller return shape against view destructure
+    const returnedKeys = parseControllerReturns(controllerContent);
+    const destructuredKeys = parseViewDestructured(viewContent);
+
+    assert.ok(destructuredKeys.size > 0, `View for ${fw} must destructure controller properties`);
+    for (const key of destructuredKeys) {
+      assert.ok(
+        returnedKeys.has(key),
+        `[${fw}] View property "${key}" must be present in controller return object: ${[...returnedKeys].join(', ')}`
+      );
+    }
+
+    // 3. Audit check: CONTROLLER_VIEW_MISMATCH must report 0 violations
+    const violations = auditFile(viewPath, `m-task-list.${ext}`);
+    const mismatchViolations = violations.filter((v) => v.rule === 'CONTROLLER_VIEW_MISMATCH');
+    assert.strictEqual(mismatchViolations.length, 0, `Audit must report 0 mismatch violations for ${fw}`);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+

package/cli/generator-templates/archetypes/collection-archetypes.js

@@ -7,7 +7,7 @@ export const COLLECTION_ARCHETYPES = [
     id: 'task-list',
     name: 'Collection & Task List',
     keywords: ['task', 'todo', 'tasklist', 'checklist', 'item', 'queue', 'list', 'add', 'toggle', 'remove', 'delete'],
-    destructure: 'items, activeCount, setFilter, toggleItem, removeItem, addItem',
+    destructure: 'items, filter, activeCount, setFilter, toggleItem, removeItem, addItem',
     buildState: (name, pascal) => `export interface ${pascal}Item {
   readonly id: string;
   readonly title: string;
@@ -151,7 +151,7 @@ export const use${pascal}Controller = (options: { rows?: readonly ${pascal}Row[]
     }
   };
 
-  return { sortColumn, sortDirection, page, sortBy, setPage };
+  return { rows: options.rows || [], sortColumn, sortDirection, page, sortBy, setPage };
 };
 `,
     buildReactBody: (name, pascal) => `      <div className="${name}__header">
@@ -189,7 +189,7 @@ export interface ${pascal}State {
     buildController: (name, pascal) => `import { useState } from 'react';
 import type { ${pascal}Node } from './types';
 
-export const use${pascal}Controller = (options: { onSelect?: (id: string) => void } = {}) => {
+export const use${pascal}Controller = (options: { nodes?: readonly ${pascal}Node[]; onSelect?: (id: string) => void } = {}) => {
   const [expandedIds, setExpandedIds] = useState<readonly string[]>([]);
   const [selectedId, setSelectedId] = useState<string | null>(null);
 
@@ -202,7 +202,7 @@ export const use${pascal}Controller = (options: { onSelect?: (id: string) => voi
     options.onSelect?.(id);
   };
 
-  return { expandedIds, selectedId, toggleNode, selectNode };
+  return { nodes: options.nodes || [], expandedIds, selectedId, toggleNode, selectNode };
 };
 `,
     buildReactBody: (name, pascal) => `      <div className="${name}__tree">
@@ -235,11 +235,11 @@ export interface ${pascal}State {
 `,
     buildController: (name, pascal) => `import { useState } from 'react';
 
-export const use${pascal}Controller = () => {
+export const use${pascal}Controller = (options: { series?: readonly ${pascal}DataPoint[]; timeRange?: '1h' | '24h' | '7d' | '30d' } = {}) => {
   const [activeIndex, setActiveIndex] = useState<number | null>(null);
   const [timeRange, setTimeRange] = useState<'1h' | '24h' | '7d' | '30d'>('24h');
 
-  return { activeIndex, timeRange, setActiveIndex, setTimeRange };
+  return { series: options.series || [], activeIndex, timeRange, setActiveIndex, setTimeRange };
 };
 `,
     buildReactBody: (name, pascal) => `      <div className="${name}__toolbar">
@@ -274,9 +274,9 @@ export interface ${pascal}Column {
 }
 `,
     buildController: (name, pascal) => `import { useState } from 'react';
-import type { ${pascal}Card } from './types';
+import type { ${pascal}Card, ${pascal}Column } from './types';
 
-export const use${pascal}Controller = (options: { cards?: readonly ${pascal}Card[]; onCardMove?: (id: string, colId: string) => void } = {}) => {
+export const use${pascal}Controller = (options: { columns?: readonly ${pascal}Column[]; cards?: readonly ${pascal}Card[]; onCardMove?: (id: string, colId: string) => void } = {}) => {
   const [cards, setCards] = useState<readonly ${pascal}Card[]>(options.cards || []);
   const [activeCardId, setActiveCardId] = useState<string | null>(null);
 
@@ -286,7 +286,7 @@ export const use${pascal}Controller = (options: { cards?: readonly ${pascal}Card
     options.onCardMove?.(cardId, toColumnId);
   };
 
-  return { cards, activeCardId, setActiveCardId, moveCard };
+  return { columns: options.columns || [], cards, activeCardId, setActiveCardId, moveCard };
 };
 `,
     buildReactBody: (name, pascal) => `      <div className="${name}__columns">